2026-06-15博客仓库整理与部署全过程

博客仓库整理与部署全过程

背景

这次整理的目标不是单纯“把博客跑起来”，而是把整个仓库从一个能用但比较混乱的状态，整理成一个结构清晰、可本地调试、可安全部署、可继续维护的 Hexo 博客项目。

当前仓库地址：

666xz666/source.666xz666.github.io

最终希望达到的效果有四点：

• 本地命令清晰，随时可以重新启动和生成
• 仓库结构干净，不保留无意义目录和历史残留
• 图片全部本地静态化，不依赖随时可能失效的外链
• 部署过程安全，不把 token 直接写进仓库

一开始遇到的问题

最开始的问题并不是单点故障，而是一连串的小坑叠在一起：

• 项目目录里残留了不少历史文件，不容易判断哪些还在使用
• 多个配置文件同时存在，职责边界不清楚
• data/ 目录里有部署状态文件，但并不是博客运行必须内容
• 主题目录和本地配置叠在一起，不容易判断哪些是自定义、哪些是主题原始文件
• 图片既有外链，也有本地资源，组织方式不统一
• 部署相关文件中残留了敏感 token

如果不先把这些基础问题梳理清楚，后面无论是调试、写文章还是部署，都会反复踩坑。

先做仓库结构清理

第一步做的是“看清项目到底有哪些东西”。

这一步主要梳理了：

• source/：博客正文、页面和图片资源
• scaffolds/：Hexo 创建文章和页面时使用的模板
• scripts/：Hexo 自定义脚本
• themes/fluid/：本地主题目录
• _config.yml：站点主配置
• _config.fluid.yml：主题覆盖配置

在这一步里，顺带还处理了几个具体问题：

• 明确 scaffolds/ 不是垃圾目录，而是新建文章时的模板来源
• 确认 package-lock.json 需要保留，不应该忽略
• 清理不再需要的额外配置文件
• 检查 themes/fluid/ 是否确实被当前主题引用

其中一个比较明确的结论是：有些目录看起来像“缓存”或者“临时产物”，但实际上和 Hexo 的正常工作流有关，不能乱删；反过来，有些文件确实只是历史遗留，就应该及时移除或归档。

处理 data 目录和无效文件

这一步的重点是减少仓库噪音。

之前 data/ 目录中有部署状态数据库之类的文件，这类文件对当前博客发布并不是必须内容，而且容易让仓库显得脏乱。

最终处理思路是：

• 不把这类历史部署状态文件继续保留在仓库核心结构里
• 能删除就删除，而不是一边保留一边继续维护 ignore 规则

后面又进一步处理了几个看起来“很突兀”的资源：

• source/_posts/差分.assets/image-20250123191035683.png
• source/images/ 根目录下的两张微信图片

这些文件都没有继续参与正文引用，于是统一归档到了：

• source/images/trash/差分/
• source/images/trash/wechat/

这样做的好处是：

• 主资源目录更清晰
• 历史资源没有立刻彻底丢失
• 后续如果确认永远不用，再统一删除即可

整理配置文件

配置层面最开始最大的疑问，是为什么不同 yml 里都有 deploy 配置。

后来梳理出来的结论是：

• _config.yml 才是站点主配置，应该承担部署配置
• _config.fluid.yml 是主题覆盖配置，不应该继续承担重复部署信息

因此后续做了两件事：

1. 清理 _config.fluid.yml 中不该承担的部署配置
2. 把部署入口统一收敛到 _config.yml

最终主配置里的部署段大致是这个思路：

deploy:
  type: git
  repo: https://github.com/666xz666/666xz666.github.io.git
  token: $GITHUB_TOKEN
  branch: main

也就是说，仓库中不再保存真实 token，而是运行时从环境变量读取。

本地命令链路梳理

在仓库整理过程中，也顺手把本地开发和部署链路梳理清楚了。

当前本地全周期最常用命令如下：

安装依赖

npm install

启动本地预览

hexo s

清理生成缓存

hexo clean

重新生成静态页面

hexo g

创建新文章

hexo new "文章标题"

创建新页面

hexo new page "页面名"

执行部署

npm run deploy

这里有一个细节：

• 日常生成、预览已经统一用全局 hexo
• 但部署仍然保留在 npm run deploy

原因是部署脚本额外负责读取项目根目录下的 .env，把 GITHUB_TOKEN 注入当前进程，再调用 hexo deploy。这一层用 npm script 包起来更稳。

调试过程中解决的实际故障

整理不是纯文件搬运，中间还修过实际运行错误。

其中一个比较关键的问题是本地执行 hexo server 时，marked 渲染链报错，根因是 callouts 的处理逻辑被主题脚本和仓库自定义脚本重复接管了。

最后的处理方式是：

• 保留仓库自己的 scripts/callouts.js
• 去掉主题里重复的同类接管逻辑

这样 Hexo 渲染链恢复正常，hexo generate 和本地预览都能跑通。

对照线上站点做调试

在本地端口预览正常之后，又对照线上站点逐项检查了页面表现。

这一步的意义在于：

• 验证本地生成内容是否与线上一致
• 找出本地缺失的配置、资源或渲染差异
• 为后面的图片静态化做准备

很多博客项目的问题不是“根本跑不起来”，而是“跑起来了，但和线上版本不一致”。这一轮对照就是为了把这种隐性差异尽量提前消掉。

把外链图片全部改成静态资源

这部分是整个整理过程中最花时间的一步之一。

一开始文章里有不少外链图片，尤其是原来挂在 OSS 上的资源：

• https://pic--oss.oss-cn-beijing.aliyuncs.com/...

这类图床一旦失效，博客正文和封面就会同时出问题，所以最终统一改成了本地静态资源方案。

最终采用的策略是：

• 统一把文章相关图片放到 source/images/posts/
• 文章 front matter 中的 cover 和 index_img 都改成本地路径
• 正文里的插图也尽量改为本地资源

处理 Bing 外链封面失败问题

中间还踩了一个很典型的坑：原本想把几张失效的 Bing 图片封面下载下来保存到本地，结果所谓的“图片文件”其实是 Bing 返回的 HTML 页面。

也就是说，文件扩展名虽然是 .jpg，但内容根本不是图片。

这会导致两类问题：

• 浏览器显示失败
• Hexo 虽然能复制文件，但页面里实际引用的是错误资源

最后的解决思路是不再继续依赖这类不稳定的外链抓取，而是直接为相关文章制作本地静态封面。

后来给几篇文章换成了本地封面，例如：

• /images/posts/bfs-flood-fill-cover.svg
• /images/posts/bfs-multi-source-cover.svg
• /images/posts/mst-cover.svg

这一步的核心不是“图片多精美”，而是“封面一定稳定、可控、可版本管理”。

重新整理图片目录

随着图片静态化完成，目录组织也顺手统一了。

最终约定如下：

• 正常文章资源：source/images/posts/
• 暂时不用但保留的资源：source/images/trash/
• 不再推荐使用 source/_posts/*.assets/

这比“图到处散着放”要好很多，因为后面维护时能快速判断：

• 哪些是正文现役资源
• 哪些只是历史残留
• 哪些可以继续清理

处理部署安全问题

部署链路真正的高风险点，是 token 一度被写进了仓库文件里。

具体来说，早期的 deploy_config.json 中残留了真实 GitHub PAT，结果在 git push 时被 GitHub Push Protection 拦截。

报错本质上是：

• 当前提交历史中包含明文 secret
• 就算后面删掉文件，如果历史里还存在那次提交，也一样会被阻止推送

这个问题最后是这样处理的：

1. 删除 deploy_config.json
2. 把它加入 .gitignore
3. 重建根提交，彻底移除含密钥的那次旧提交历史

这个过程再次说明一个事实：

• 只在工作区“删掉敏感文件”是不够的
• 如果 secret 已经进了提交历史，就必须改写历史

当然，更重要的一点是：泄露过的 token 必须立即废弃并重新生成，不能继续使用。

README 和文档补全

在清理和调试基本完成之后，又补了一轮项目文档。

这部分主要包括：

• 更新 README.md
• 把本地命令统一成当前实际使用的全局 hexo 方式
• 说明 .env / .env.example 的作用
• 解释部署时为什么仍然保留 npm run deploy

这样做的好处是，后面重新打开这个仓库时，不需要再靠记忆猜命令。

给 AI 写作流程补规范

后面又补了一份 AI_README.md，专门给 agent 工具使用。

这份文件的目的很明确：

• 约束 AI 写博客时的 front matter
• 约束标题、分类、标签、图片路径
• 规定不能把 token、外链失效图片之类的内容写进仓库

后来又进一步补了一条重要规则：

• AI 不能直接把新文章写进 source/_posts/
• 必须先写进 source/_drafts/

同时在仓库里创建了：

• source/_drafts/.gitkeep

这里的 .gitkeep 只是一个占位文件，用来让 Git 跟踪原本的空目录。

最终得到的仓库状态

整理完成后，当前仓库已经基本具备下面这些特征：

• 本地开发命令明确
• 主题和站点配置职责清晰
• 图片资源以本地静态文件为主
• 历史垃圾文件得到归档或删除
• 部署不再依赖仓库内明文 token
• AI 写作流程也有了明确规则

换句话说，这个博客项目现在已经不是“勉强能跑”，而是进入了“可以长期维护”的状态。

这次整理里最重要的几个经验

1. 先梳理结构，再修故障

如果一上来就只盯着某个报错，很容易头痛医头、脚痛医脚。
先搞清楚目录、配置、资源、部署链路分别由谁负责，后面的修复会快很多。

2. 外链图片迟早会变成维护债务

只要博客想长期存活，重要图片就应该尽量本地化。
封面图尤其如此，因为一旦失效，首页和文章页会同时变丑。

3. secret 不能只“删文件”，必须看提交历史

如果 token 已经进过提交，真正要处理的是 Git 历史，而不是当前工作区。

4. 文档和规范本身也是维护成本的一部分

把 README、AI 写作规范、草稿流程补齐之后，后面的维护成本会明显下降。

结尾

这次整理看上去是在“修博客”，但本质上做的是一轮完整的工程化收敛：

• 清目录
• 清配置
• 清资源
• 清部署链路
• 清安全隐患
• 补文档
• 补工作流

如果后面继续写文章、换主题样式、补自动化部署，这一轮整理打下的基础会非常有价值。至少以后再回来看这个仓库，不会再有一种“能跑，但完全不想碰”的感觉。