这篇记录博客从动机、选型、部署到日常维护的完整过程，也作为以后迁移到其他设备时的备忘。

一、为什么搭建博客

本科阶段就有“做一个属于自己的网站 / 知识库”的想法，但一直没有行动。求职阶段回头看，学了很多东西，却没有留下系统的沉淀。于是决定用博客持续记录学习轨迹、踩坑经验和阶段性总结。

网上的教程很多，原本担心会很复杂，实际两天左右就完成了可用的初版。博客的定位是个人学习记录，不追求花哨的功能。

二、技术选型与部署

框架使用 Hexo，主题使用 Butterfly。

部署方式起初考虑过买服务器（例如阿里云）自己部署，但运维要花额外的时间，博客主要是自用记录，对性能和动态功能的需求很低，服务器费用也没有必要。最终选择 GitHub Pages，另外购买了国内域名，方便国内访问。

方面 体验
优点 免服务器，配置简单，便于长期维护
缺点 图片首次加载稍慢

三、源码备份

GitHub Pages 上只有生成后的静态页面，本地源文件一旦丢失就很难恢复。所以另外建了一个私人仓库存放 Hexo 源码（source/、配置和主题定制），每次写完文章、生成部署后，再把源码推送到这个仓库。

四、站点的定制

在 Butterfly 的基础上，逐步加入了这些定制：

  • 统一的深蓝色视觉：主题配色、页面顶图和文章封面都由 scripts/ 中的脚本按分类自动生成 SVG，不依赖外部图片；
  • 首页的精选入口和主题导航，以及“路径规划理论”专题页；
  • 构建校验脚本 tools/validate_build.js：检查每个页面的标题、图片尺寸、站内链接等，发现问题时构建失败；
  • 图片统一转换成 WebP，用浏览器原生懒加载；
  • 数学公式用 KaTeX，流程图用 Mermaid；
  • 访客统计由一个 Cloudflare Worker 提供。

五、写作与发布流程

  1. 在 source/_posts/<分类目录>/ 下新建 Markdown 文件，写好 front-matter（标题、日期、分类、标签、description）；
  2. 在 source/_data/cover_profiles.yml 中为新文章添加封面配置，否则构建校验会失败；
  3. 插图放到 source/img/posts/<文章>/，然后运行 python3 tools/optimize_images.py 转成 WebP；
  4. 本地预览，确认无误后运行完整检查，再部署。

六、常用命令

1
2
3
4
5
6
7
npm run server   # 本地预览：http://localhost:4000
npm run check    # 清理、生成、校验、测试访客统计服务
npm run deploy   # 部署到 GitHub Pages

git add .
git commit -m "docs: 新增文章"
git push         # 推送源码到私人仓库