Hexo 博客源码仓库与发布仓库分离实践

Hexo 博客通常会涉及两个不同概念：源码仓库和发布仓库。源码仓库存放 Markdown、主题配置、脚本和静态资源；发布仓库存放 hexo generate 之后生成的 HTML、CSS、JS 和图片。

如果这两个仓库的边界不清楚，后续维护很容易混乱：源码没有保存，发布内容能访问但无法复现；或者把生成文件提交到源码仓库，导致 diff 变得很吵；再或者把源码误推到 GitHub Pages 仓库，影响线上站点结构。

把源码仓库和发布仓库分离，是个人博客长期维护里非常值得做的一件小事。

一、先区分两类文件

Hexo 源码仓库里应该重点保存这些内容：

source/_posts/ 下的 Markdown 文章。
source/assets/、source/img/ 下的图片资源。
_config.yml 和主题配置。
package.json 和依赖声明。
自定义脚本，例如 deploy.sh。
说明文档，例如 README.md。

发布仓库里应该保存的是构建产物：

index.html。
archives/、categories/、tags/ 页面。
每篇文章生成后的 index.html。
主题生成的 CSS 和 JS。
被复制到 public/ 的静态资源。
CNAME。

这两类文件的生命周期不同。源码需要长期可编辑、可审查、可回滚；构建产物只需要能被 Pages 服务读取。

二、为什么不要混在一起

把源码和发布产物混在一个仓库里，短期看起来简单，长期会带来几个问题。

第一，提交记录难读。每写一篇文章，除了 Markdown，还会生成大量 HTML、分页、标签页和归档页。真正的内容改动会被构建产物淹没。

第二，冲突更容易出现。分页和归档文件经常变化，多端维护时很容易产生无意义冲突。

第三，回滚成本更高。想回滚一篇文章时，需要同时处理源码和生成文件，容易漏掉关联页面。

第四，自动化更难做。CI 或本地脚本需要判断哪些文件是源文件、哪些文件是产物，流程边界不清晰。

分离之后，源码仓库只关心内容和配置，发布仓库只关心线上结果。

三、推荐的仓库关系

一种常见结构是：

blog-source
  _config.yml
  package.json
  source/
  themes/
  tools/
  deploy.sh

loki0210.github.io
  index.html
  archives/
  categories/
  tags/
  2026/
  css/
  js/

源码仓库可以使用普通名字，例如 blog、blog-source 或 my-site。发布仓库使用 GitHub Pages 要求的仓库名，例如：

1	username.github.io

Hexo 的 _config.yml 里只需要把 deploy 指向发布仓库：

deploy:
  type: git
  repo: git@github.com:username/username.github.io.git
  branch: master

这样执行 hexo deploy 时，Hexo 会把 public/ 目录里的生成结果提交并推送到发布仓库。

四、源码仓库也要有正确远端

很多博客是从模板仓库初始化出来的。如果初始化后没有改远端，origin 可能仍然指向模板仓库。

可以用下面命令检查：

1	git remote -v

如果输出仍然是模板地址，就应该换成自己的源码仓库：

1	git remote set-url origin git@github.com:username/blog-source.git

或者先移除旧远端，再添加新远端：

1 2	git remote remove origin git remote add origin git@github.com:username/blog-source.git

这一步很重要。发布仓库配置正确，只能保证线上站点能更新；源码仓库远端正确，才能保证 Markdown 和配置不会只留在本机。

五、部署脚本只做发布

部署脚本建议保持简单：

#!/usr/bin/env bash
set -euo pipefail

npm run clean
npm run build
npm run deploy

它的职责是从源码生成站点，并推送发布仓库。不要在部署脚本里顺手提交源码仓库，因为这会把两个动作绑得太死。

更合理的日常流程是：

# 1. 修改或新增 Markdown
npm run build

# 2. 确认内容没问题后提交源码
git add source/_posts/new-post.md
git commit -m "Add new blog post"
git push

# 3. 发布线上站点
./deploy.sh

如果是个人自动化流程，也可以把第 2 步封装成单独脚本，但最好仍然明确区分“保存源码”和“发布站点”。

六、哪些目录应该忽略

源码仓库通常不应该提交构建产物和部署缓存。

.gitignore 可以包含：

node_modules/
public/
.deploy_git/
db.json
.DS_Store

其中：

node_modules/ 是依赖安装结果。
public/ 是 Hexo 构建产物。
.deploy_git/ 是 Hexo deploy 使用的临时发布仓库。
db.json 是 Hexo 本地缓存。

这些文件可以由命令重新生成，不应该污染源码历史。

七、发布前做两次确认

一次确认是构建确认：

1	npm run build

它能发现 front matter、Markdown 渲染、资源路径和主题模板层面的问题。

另一次确认是远端确认：

1	git remote -v

尤其是在新机器、迁移仓库或刚接手旧博客时，要确认源码远端和发布远端分别指向哪里。

发布远端可以在 _config.yml 里看：

1 2	deploy: repo: git@github.com:username/username.github.io.git

源码远端用 git remote -v 看。两者不应该混淆。

八、遇到脏工作区怎么办

博客仓库经常会出现很多未提交文件，尤其是从旧目录迁移或补齐历史文章时。此时不要急着 git add .。

更稳妥的做法是：

git status --short
git add source/_posts/target-post.md
git diff --cached
git commit -m "Add target post"

只暂存当前任务相关文件。其它历史改动先保留在工作区，等确认归属后再统一处理。

这条原则对 AI 协作尤其重要。AI 可以帮忙生成文章和部署，但不应该在没有确认的情况下把整个脏工作区打包提交。

九、总结

Hexo 博客维护的关键，不只是能把页面推上去，还要保证源码可追踪、发布可复现、仓库边界清楚。

推荐的基本原则是：

源码仓库保存 Markdown、配置、脚本和资源。
发布仓库保存 public/ 生成后的静态站点。
deploy.sh 只负责构建和发布。
源码提交和站点发布分开执行。
工作区很脏时，只提交当前任务相关文件。

这样维护博客时，既能保持发布流程简单，也能避免源码和构建产物互相干扰。