1. 项目概述1.1 核心需求解析我一直在想一个开发者到底应该怎么经营自己的技术博客。很多人觉得写博客就是开个博客平台账号然后想起来就写两篇或者干脆把笔记往那一扔就完事。但实际情况远没那么简单。刚开始我也踩过不少坑后来逐渐摸索出一套自己的方法——从域名注册、博客框架选型、服务器部署到内容规划、代码高亮、评论系统、SEO优化再到建立发布流程、维护旧文章这一整套东西其实完全可以当成一个独立的技术项目来对待我就是这么给这套体系起名叫CodeBlogMan的。CodeBlogMan本质上是一个偏个人的、以代码博客为主线的内容输出项目。它解决的痛点是开发者有技术积累但不知道该用什么方式持续、高效地表达出来或者一直在断断续续地写但始终没有形成一套稳定的流程。它适合三类人新入门想建立个人主页的前端/后端工程师想通过技术写作锻炼表达、积累影响力的职场人以及那些手里有一堆零散笔记想系统化整理成文章的老开发。1.2 项目能解决的问题在实践CodeBlogMan的过程中我最直观的感受是写技术博客的门槛从来不是写作能力而是系统性。你需要提前决定博客搭在哪、内容存哪种格式、图片怎么管理、发布时间怎么规划、旧文章怎么维护。这些决策如果不提前做好写到一半特别容易放弃。而在把这一切理顺之后你会发现写作变成了一种习惯——打开编辑器敲几段代码和文字然后通过一套固定的命令完成发布整个过程的重心回归到内容本身而不是被各种杂事分心。另外CodeBlogMan这个模式还天然适合用来做知识沉淀。我在复盘工作时经常发现一篇在博客里写清楚的技术方案往往在半年后变成了团队内部问题的参考答案。技术写作是一种复盘方式它能逼着你把大概知道变成彻底搞明白。这也是为什么我在设计这个项目时特别强调代码可复现和步骤可追踪这两个点——文章里写得越清楚自己之后回看的价值就越大。2. 整体设计与技术选型2.1 为什么选择静态博客而不是平台写作在设计CodeBlogMan时首先需要决策的就是博客形态的选择。很多人的第一反应是去知名写作平台注册一个账号既不需要服务器也不需要域名省事。但实际用下来这种方式有几个很难忽略的短板平台提供的数据导出通常不完整图片水印和排版风格不由你说了算页面广告和推荐算法也在某种程度上稀释了个人品牌的辨识度。更重要的是你自己的内容和流量始终属于平台哪天平台调整策略或者你被限流之前积累的东西可能瞬间失去意义。静态博客方案恰好能规避这些问题。所谓静态博客就是所有页面在本地预先渲染成纯HTML文件部署时只需要把文件放到Web服务器上访问者打开页面时看到的直接就是最终结果不需要后端实时渲染。这种模式的好处很明显性能天生好、抗攻击能力强、成本很低而且内容的所有权完全掌握在自己手里。我最初选择静态博客还有一个很实际的理由——我可以把所有文章用Markdown格式存在Git仓库里。这样每一篇文章都有版本历史改了什么东西、什么时候改的全部有迹可循。2.2 框架选型的心路历程静态博客框架目前市面上有三类主流选择以Hexo、VuePress、Hugo为代表的首选方案。我实际试过Hexo和Hugo最终给CodeBlogMan选择了Hexo。选它的核心原因是生态成熟主题多、插件多几乎你能想到的功能已经有人做成了现成插件。这一点对新手特别重要因为博客搭建的本质是省时间写内容而不是花时间折腾系统。不过我也要客观说一句Hugo的构建速度确实比Hexo快很多尤其是文章数量超过几百篇之后Hexo的构建时间会明显变长我实测过一篇中等规模博客项目两百多篇文章构建大约需要十几秒但Hexo的构建速度在我日常使用场景下完全能接受而它庞大的主题社区带来的便利是Hugo短期内很难追上的。VuePress我也了解过它更适合做项目文档站点对于个人博客这种以文章流为主的场景配置成本相对高一点。综合权衡下来Hexo是那个省心省力的选项。2.3 部署方案:从GitHub Pages到云主机部署这部分其实很值得展开说说因为它是很多新手最没底的地方。一个静态博客的部署方式有很多种最常见的是GitHub Pages——把博客仓库关联上提交代码后自动发布完全免费。但我在实际使用中发现GitHub Pages在国内的访问速度不稳定而且自定义域名需要额外配置HTTPS证书。我的最终方案是买了一台最基础配置的云服务器1核1G的配置跑静态博客绰绰有余配合Nginx做静态文件服务。部署过程其实不复杂先在服务器上装好Nginx然后把生成的public目录上传到服务器指定路径改一下Nginx配置指向这个目录就行。这里有一个细节值得提静态博客部署时不需要配置数据库不需要装PHP或Node环境运行服务进程本地构建时才会用到Node服务器上只需要一个Web服务软件就够了这就让运维成本变得非常低。我从买服务器到博客上线前后花了一个小时其中大部分时间还在等域名解析生效。3. 核心细节解析与实操要点3.1 目录结构与内容组织方式CodeBlogMan的目录结构延续了Hexo的通用设计在默认为基础上做了一些自定义我觉得这种组织方式对于保证长期维护效率是很关键的。source/_posts/所有文章存放的目录按年份分子目录管理例如source/_posts/2025/一年一个文件夹查找历史文章时非常直观。source/images/图片资源统一放这里按文章名建子目录存放避免一篇文章的图片散落各处。themes/主题目录我的自定义改动全部集中在主题目录下便于未来升级主题时对比。_config.yml站点主配置文件管理博客名称、URL、部署信息等核心参数。scaffolds/脚手架目录这里可以自定义文章模板新建文章时会自动带入模板内容省去每次手敲front matter的麻烦。在实际操作中我给每篇文章的front matter区即文章头部信息区定了几个约定格式title标题、date发布时间、tags标签、categories分类。这两者的区别我也重新理了一下tags用来描述文章内容的细粒度特征比如Nginx配置、Flexbox布局categories则用于文章的大类归属比如前端、运维。清晰的分类体系在日后做专题整理时会节省极大的时间成本。我的约定是一篇文章最多设置3个标签优先保证分类的唯一性避免标签过于发散导致后期难以维护。3.2 写作流程与发布管线CodeBlogMan的发布流程我把它拆成了几个固定步骤每篇新文章都走这一套管线在source/_posts/下按年份创建文章目录把图片素材放到对应目录。执行hexo new post 文章标题用脚手架生成Markdown文件自动填入日期和默认模板。在Markdown文件里完成正文撰写所有代码块标注语言类型图片使用相对路径引用。本地执行hexo clean hexo generate生成静态文件。在本地浏览器预览确认排版无误这一点我会在后面的调试经验里展开。执行hexo deploy或手动上传public目录完成发布。这套流程看起来简单但有一个容易忽略的隐藏细节如果本地Node版本和主题要求的版本不一致生成出的页面可能有些小功能不工作比如代码复制按钮消失。为了避免类似问题我在项目里放了一份.nvmrc文件锁定了Node版本。这样做的好处是哪怕半年后这台电脑重装系统我也能快速重建出和原先一致的构建环境。3.3 代码高亮与阅读体验优化CodeBlogMan作为一个面向技术内容的博客代码高亮的质量直接决定文章的专业感和可读性。Hexo默认使用highlight.js或prismjs做高亮这取决于主题配置。我更推荐在Hexo中使用prismjs因为它的语言支持更全面对JSX、Go、Rust这类现代语言的支持更友好而且高亮的配色方案可选范围更大。代码块在高亮之外还有几个细节值得优化行号显示方便读者定位讨论代码行、一键复制按钮最好再配合一个复制成功的交互反馈、大段代码块的横向滚动而不是换行避免代码被硬折行破坏格式。我的经验是代码块的字号可以略小于正文但行高不能太窄否则代码密集时阅读压力很大。配色方面我最终选了一个偏深色但对比适中的背景文字用浅色但不刺眼的色调。在这里我特别想给一个建议高亮配色一定要在真实页面里截图检查直接看代码在不同屏幕亮度下的实际表现不要只看主题文档里的预览图。3.4 评论系统与搜索功能静态博客没有后端数据库评论系统和搜索功能不能直接开箱即用这算是静态化方案最大的一个短板。我当时的解决方式是评论系统接入了第三方服务选型时我对比过waline和utterances这两个主流方案最终选了更轻量的那个而站内搜索功能使用了基于本地索引的前端搜索方案。这两个方案各有一个共同特点——不需要自建后端服务数据和配置都被文件化保存正好契合静态博客的定位。坦白说评论系统的接入体验和平台自带的评论还是有一些差距的尤其是面对垃圾评论时需要自己维护过滤规则。如果你对评论互动的要求比较高我建议可以认真考虑一下第三方服务的账号绑定流程是否顺畅避免访客觉得登录门槛太高而放弃留言。搜索功能方面静态博客要实现全文搜索一般是把文章内容提前生成一份JSON索引由前端脚本动态匹配。这个方案在小数据量下速度很快但文章数量超过几百篇时索引文件会变大搜索响应会稍慢。到时候可以按需做索引分片优化但大部分个人博客不至于走到这一步。4. 实操过程与核心环节实现4.1 环境准备与初始配置开始搭建CodeBlogMan之前我先把环境整理了一遍避免中后期在环境问题上反复折腾。本地需要的核心工具是Node.js我用的版本是18 LTS和Git。Node.js的版本我建议直接选择LTS版本不要追新因为某些Hexo插件在新版本Node下可能存在兼容性问题而维修这些问题的成本完全可以通过选择LTS版本规避。初始化博客的命令很简单依次执行npm install -g hexo-cli hexo init blog cd blog npm install hexo serverhexo init执行完会在blog目录下生成一个功能完整的博客骨架hexo server是本地预览命令默认在4000端口启动一个开发服务器。第一次执行hexo server你在浏览器输入http://localhost:4000应该就能看到默认主题的欢迎页。完成了这一步CodeBlogMan的骨架就搭起来了。之后需要修改_config.yml里的几个核心字段。title字段会出现在浏览器的标题栏和首页顶部建议直接用你的博客名字url字段填你最终绑定的域名这个字段会影响文章链接的生成方式最好在发布初期就定义好不然后期改域名链接结构变化会影响收录language字段设置为zh-CN可以确保时间和日期格式符合国内阅读习惯。这些配置改完之后建议执行一次hexo clean再重新hexo generate确保配置生效。4.2 主题定制与页面结构调整主题是博客气质的直接体现。CodeBlogMan的默认主题是Hexo自带的landscape我个人觉得它的排版风格偏传统所以换了一款支持更多自定义能力的主题。主题的安装方式通常是下载主题文件到themes/目录然后在_config.yml里把theme字段改成对应目录名。主题安装完成后我做的第一件事不是改样式而是调整页面结构。我的博客需要这几个核心页面首页文章列表、归档页按时间倒序的所有文章、标签页按标签聚合的文章集合、关于页介绍博主自己和这个项目。虽然主题通常自带这些页面模板但你需要手动创建对应的页面文件否则路由不会生效。创建方式是执行hexo new page tags这类命令然后在生成的index.md里根据需要修改页面属性。页面结构调整的同时我需要重点检查的是导航菜单的链接是否正确。很多人在这一步会踩坑导航栏的链接写的是相对路径部署到子目录环境下就出现404。我的建议是在本地预览时直接点击所有导航链接逐项检查不要只看页面能否打开首页就完事。这种检查虽然琐碎但能避免上线后才发现某个页面无法访问的尴尬。4.3 部署上线与HTTPS配置CodeBlogMan上线部署的过程我把它总结为一个标准流程方便以后在别的机器上复现。第一步是在服务器上安装Nginxsudo apt update sudo apt install nginx装好之后Nginx默认会在/var/www/html目录下寻找网页文件。我的做法是给博客单独建一个目录例如/var/www/codeblogman然后把本地hexo generate出来的public文件夹内容完整上传到这个目录。上传方式可以用scp也可以借助Git仓库做同步不过最省心的方式其实是配合GitHub仓库的webhook做自动部署这部分后面讲自动化时再细说。接下来修改Nginx配置server { listen 80; server_name codeblogman.example.com; root /var/www/codeblogman; index index.html; location / { try_files $uri $uri/ 404; } location ~* \.(css|js|png|jpg|jpeg|gif|svg|webp|woff|woff2)$ { expires 30d; add_header Cache-Control public, no-transform; } }try_files这一行是静态文件服务器的关键配置它的作用是先尝试按请求的URI查找文件找不到再尝试按目录解析最终返回404。这样做的目的是保证用户在访问不带.html后缀的链接时Nginx也能正确找到对应的HTML文件。静态资源的expires 30d设置浏览器缓存图片字体这些内容可以缓存一个月能显著提升重复访问的加载速度。HTTPS配置我用了certbot工具。这个工具有一个很大的优点是自动化程度高它会自动识别Nginx的配置、自动申请证书、自动续期sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d codeblogman.example.com执行过程中会问你是否要把HTTP请求重定向到HTTPS我选了是。需要提醒的是HTTPS证书的自动续期依赖于一个定时任务安装certbot时它会自动创建。你可以在部署完一段时间后执行sudo certbot renew --dry-run验证续期流程是否正常。4.4 自动化发布流程的搭建手动上传public目录的方式虽然可行但每次都要打开终端执行上传命令有一定的重复劳动。为了让CodeBlogMan的运行流程更顺畅我引入了一个简单的自动化发布机制在Git仓库设置一个webhook当我把博客源码推送到远程仓库时服务器收到通知后自动从仓库拉取最新代码并重新构建发布。实现这套流程需要服务器上安装Node.js环境。注意这和运行时所需的Node版本应该尽量与本地构建版本一致避免构建结果出现差异。服务器上支持的脚本逻辑大致是从Git仓库拉取源码进入源码目录执行npm install安装依赖、hexo generate构建静态文件然后把生成的public目录同步到Nginx的根目录。这里我想强调一个非常关键的细节构建热点要放在一个临时目录中发布时再做文件替换。之所以不直接在Nginx根目录下构建是因为构建过程中如果出现临时文件缺失访问者可能会看到半完成的页面状态。正确的做法是先在临时目录构建完整确认成功后再用rsync同步到正式目录这样发布过程对访问者完全透明不会出现页面瞬间404的情况。我实际跑通了这套方案之后写文章的整个流程简化为本地写Markdown → 推送到Git仓库 → 服务器自动构建发布。整个链路稳定运行了很久没有再为发布这件事费过心。5. 常见问题与排查技巧实录5.1 本地预览正常但线上样式丢失这个问题我在不同阶段遇到过好几次典型表现是本地执行hexo server访问时一切正常但部署到服务器后页面没有任何样式变成了纯文本的HTML。排查思路其实很固定。先用浏览器的开发者工具打开Network面板找到加载失败的CSS文件看它的URL路径。如果CSS文件的URL路径是根路径以/开头而你的博客部署在域名根目录那问题大概率出在域名和_config.yml中的url字段不一致或者资源路径配置有误。Hexo的文章链接和静态资源路径都依赖根路径配置如果配置不当生成的页面会引用错误路径线上自然加载不到CSS。另一种常见原因是Nginx的配置拦截了静态资源的请求。比如某些安全策略会禁止特定后缀文件的访问或者location匹配规则有问题导致CSS文件被当作其他类型返回。排查方法是直接在服务器上执行curl -I http://你的域名/css/style.css看返回的HTTP状态码和Content-Type类型。如果状态码不是200就要继续检查Nginx的root路径是否配置正确。这类问题绝大多数都出在路径不匹配上。5.2 文章链接修改导致收藏失效博客运行时间长了会面临文章重命名或分类调整的情况。改文章标题时文章的URL链接通常会跟着变结果就是读者收藏的旧链接直接访问不了。这其实是静态博客维护过程中最常见的暗坑。我踩过几次坑之后现在处理这类变更采用了一个固定的策略任何文章链接地址的变更必须配置301重定向。Nginx的rewrite指令可以很方便地实现这个需求location ~ ^/old-path/ { rewrite ^/old-path/(.*)$ /new-path/$1 permanent; }permanent参数表示返回301状态码浏览器和搜索引擎都会把旧链接的访问请求转移到新链接上。重点在于只要涉及到链接变更就需要用这个机制这样既保住了已有读者的访问也保住了搜索引擎对这篇文章的权重积累。5.3 图片加载缓慢与存储方案优化图片加载速度对博客体验的影响极为明显。从一开始我的CodeBlogMan就面临图片体积偏大、服务器带宽有限的问题。一篇技术文章如果配了五六张截图每张截图一两MB页面加载时间就会变得非常难堪。我做了两件事来优化第一所有图片在上传前必须经过压缩处理截图类图片统一转成适当质量的WebP格式第二对于体积还是很大的图片使用图床服务托管。使用图床需要注意一点要选择那些提供长期稳定服务的服务商并且自己保留一份原始图片备份。因为所有外链图片都是依托第三方服务的如果第三方服务调整政策或停止运营文章的图片就会全面丢失。对于重要的技术截图我更倾向于把图片压缩后放在自己的服务器上。压缩加格式转换的这套流程实际上可以把图片体积压缩到原来的十分之一甚至更小效果立竿见影。我在实际操作中还总结了一个小习惯将图片素材逻辑上分区管理。文章里用到的示意图放一个目录运行结果截图放另一个目录截图命名采用日期描述.png的形式。这样当文章内容需要反复修改时不需要在茫茫图海中找一张特定截图所有图片的位置和用途一目了然。5.4 评论身份认证和垃圾评论问题引入独立评论系统后发现垃圾评论和恶意广告比想象中多。虽然第三方评论服务都提供了基础的反垃圾机制但实际用下来默认配置拦截效果不算理想时不时还是有漏网之鱼。我的处理方式是开启必须登录才能评论的限制并且配置了关键词过滤规则某些明显的垃圾广告关键词出现时会自动进入待审核状态。这个处理方式会让评论区失去一部分随手评论的便利性但对个人博客来说维护一个干净、高质量的讨论氛围的价值远远大于评论数量本身。我现在每次打开待审核列表只需要几秒钟就能处理一批明显是垃圾的评论整体维护成本是可以接受的。5.5 构建版本兼容性维护静态博客项目有一个容易被忽视的问题依赖包版本漂移。你半年后重新执行npm install新安装的依赖版本可能和当初搭建时不完全一致构建结果也可能因此出现细微变化甚至某些插件会报错。我为了规避这个问题把package-lock.json文件完整地纳入了版本管理并且给项目配置了Node版本锁定文件。这样每次重新安装依赖时安装的依赖版本都是一致的彻底避免了在别人电脑上构建出不同结果的问题。6. 延伸思考:内容规划与长期运营6.1 写作选题与内容规划方法技术博客最容易遇到的问题就是不知道写什么。我个人在运营CodeBlogMan过程中摸索出一套选题方法从自己实际做过的事情中挖掘素材。每完成一个技术任务我就问自己几个问题这件事的难点是什么我是怎么排查出来的有没有更简洁的方案这样的思路几乎永远不会缺选题因为工作过程中遇到的每个问题都是潜在的素材。在这个基础上我会给每个主题设定一个参考价值的判断标准这篇内容如果三个月后我自己回来看会不会觉得有帮助如果答案是肯定的就值得写。这个标准虽简单但非常有效它能过滤掉一大半标题党的内容。为了让文章保持持续产出我给自己定了一个最低频次的目标每月至少两篇技术文章。实际写下来发现一个月写两篇完全不是负担反而能形成一种推动力——在写文章的过程中你会逼着自己去把知识点整理得更系统。内容规划上不必追求每天更新固定更新节奏比更新数量更有利于保持读者的信任感。6.2 从文章到知识库:渐进式整理写了一定量的文章之后会自然地遇到一个问题文章分散在归档页里读者以及你自己很难从单篇文章看到完整的知识体系。CodeBlogMan运行一段时间后我开始将零散的文章逐步整理成专题系列。例如把分散的Nginx配置类文章汇总成部署运维系列把前端相关的文章归类为前端工程化系列。每个系列有一个专属的导航页面把文章按顺序串起来读者可以更好地循着思路深挖。整理成系列的额外好处是它迫使你去检查旧文章里是否有错误或过时的技术决策。文章这东西写出来不是终点持续维护才是。一个半年后仍然能查漏补缺、更新版本的系列文章它的价值远远高于一百篇写完就再也不碰的单篇文章。6.3 访问数据分析与行为洞察博客的统计工具我选用了轻量的访问统计服务这类服务很多核心功能大同小异选择的原则就是数据准确 免费额度足够。每日访问量、访客来源渠道、热门文章、搜索关键词这几个指标是必须关注的核心数据。分析这些数据能帮你判断读者的实际需求。比如我发现自己写的某篇问题排查类文章明显比其他文章浏览量高说明这类内容有真实需求后续就应该在类似方向上多做输出。这里要特别提一下不要过分迷信访问量的高低。技术博客的读者质量远比数量重要。有时候一篇几百阅读的文章如果能帮到几个真正遇到同样问题的人它的价值就超过了流量。短期的数据波动不用太在意技术积累和信任建构是长期的事情。6.4 技术债务:长期维护中的取舍写博客和写代码一样也需要面对技术债务。具体到CodeBlogMan项目里技术债务的表现形式是某些主题配置为了实现一个临时的小功能而做了硬编码或者文章里嵌入了早已失效的外部链接。这些债务如果不及时清理会随着博客体量增大而变得越来越难处理。我的处理原则是顺手清理。每次更新旧文章时顺手把失效的外链替换掉或者删掉已经废弃的配置项。每次修改主题时把相关改动记录在主题目录下的README文件里方便后续核对。这种做法不会占用多少额外时间但能让整个项目的健康度始终维持在一个可控的状态。7. 我的实际使用感受与后续扩展建议7.1 这个方案最值得借鉴的地方CodeBlogMan这个项目在做了这么长时间的维护和迭代之后我最满意的地方其实是轻。它不依赖任何重型服务数据库、后台、构建系统全都能在半个小时内跑通。写文章的工具就是VS Code加一个Markdown文件发布过程完全自动化日常维护几乎不需要花额外时间。这种轻量感让我把注意力几乎全部放在内容本身而不是维系一套复杂的系统。如果你也想照着这个思路搭建自己的技术博客我建议你遵循一条原则能文件化、能自动化的东西就不要引入额外的人工操作或重型依赖。技术方案选择上的克制会直接转化为长期运营中的省心。7.2 后续可能的优化方向CodeBlogMan现在的运行状态已经比较稳定了不过有两个方向是我接下来想继续尝试的。一个是给博客增加英文版本的内容切换这对于面向更广读者群体验会有明显提升。另一个是把博客的构建输出接入RSS订阅源的自动化同步同时探索如何将系列文章更好地以电子文档的形式沉淀下来。双语文版这件事在静态博客体系内实现是有可行性的基本思路是维护两套Markdown文件加一套多语言配置。RSS订阅则能让不只是固定的读者群体看到你的内容而是让内容主动地分发到各个阅读器终端。这部分我还在实践摸索中。7.3 最后分享一个提升体验的小技巧在CodeBlogMan的日常维护中我发现有一个小技巧对提升写作和发布体验特别有效给常用命令配置shell别名。我把清理并重新生成和本地预览这两个最常用的操作分别设置成了简短的别名这样每次写文章时的重复操作只需要敲两个字母就能完成。修改~/.zshrc或~/.bashrc加入alias hbhexo clean hexo generate alias hshexo server配置别名之后日常发布流程进一步缩短成写完文章 →hb→ 推送Git仓库这简单的两步。好的工具应该是让人感觉不到工具的存在CodeBlogMan这套体系目前对我来说已经接近这个状态了。