Hexo博客持续更新指南

Hexo博客持续更新与双仓库备份指南

适用对象：已搭好 Hexo 博客、希望在新电脑 / 新环境下继续发布文章，并用两个 GitHub 仓库做「源码」与「站点」分离备份的用户。
环境前提：本机已安装 Node.js 与 Git（本文不展开 Node / Git 的安装步骤）。

一、核心概念：源码 vs 站点（为何要两个仓库）

一个 Hexo 博客天然包含两份不同的东西：

  • 源码（构建输入）：_config.yml、source/_posts/*.md 文章、主题配置、依赖清单 package.json。这是你写文章、改配置的地方。
  • 站点（构建输出）：hexo g 生成的 public/ 目录，全是 .html / .css / .js。GitHub Pages 实际服务的就是这份。

hexo d 的作用就是把 public/ 推到 GitHub；GitHub Pages 再从指定分支读出来变成网站。因此「源码」和「站点」本质是一个工程的两个角色，必须分开管理。

把二者放进两个独立仓库，是最清晰、最不容易出事故的方案：

仓库 角色 内容 由谁更新
站点库 用户名.github.io（公开，Pages 要求） 构建输出 hexo d 自动推送的 public/ 静态站点 hexo d
源码库 blog-source（建议 Private） 构建输入 配置、source/ 文章、package.json、scaffolds/、.gitignore、.github/ git push

一句话记忆：源码库存「怎么生成网站」，站点库存「生成好的网站」。两个 remote 天然隔离，几乎不可能把源码误覆盖到正在服务的站点上——这正是双仓库比「单仓库双分支」更省心的地方。

主题若通过 npm 安装（如 hexo-theme-fluid），npm install 会自动恢复，源码库连主题目录都不用存。

二、两个仓库各自管什么（职责表）

以实际目录为例：C:\Users\ZYUE\Documents\githubBlog（博客源码）、站点库 zyue2022.github.io、源码库 githubBlog-source。

仓库 角色 存放内容 不收
站点库 zyue2022.github.io（公开、已有、不动） 构建输出 hexo d 自动推送的 public/ 静态站点（html/css/js/img） 源码、node_modules
源码库 githubBlog-source（新建、建议 Private） 构建输入 _config.yml / _config.fluid.yml、package.json / package-lock.json、source/（文章 + about + 图片）、scaffolds/、.gitignore、.github/ node_modules/（重装）、public/（去站点库）、db.json、*.deploy*（部署临时）

由于 .gitignore 已自动排除 node_modules/、public/、db.json、.deploy*/，执行 git add -A 时生成产物和部署临时目录都不会被带进源码库。

三、首次建立双仓库备份

前提：你已找回整个博客文件夹（含 _config.yml、source/_posts 等源码特征），且里面尚无 .git。

1. 确认是「源码」不是「生成产物」

目录里应存在：_config.yml、package.json、source/_posts/*.md、themes/（主题走 npm 时可能为空，属正常）。
若只有 index.html / css/ / js/ / archives/，那是 public/ 生成物，不是源码，需走重建路线。

2. 本地提交源码库

1
2
3
4
5
cd <博客文件夹>
git init
git add -A                       # .gitignore 已排除 node_modules/public/db.json/.deploy*
git commit -m "初始化 Hexo 源码"
git branch -M main               # 源码库主分支叫 main

3. 关联远程源码库并推送

先在 GitHub 新建仓库 githubBlog-source（建议设为 Private，因为站点库因 Pages 必须公开，源码隔离更稳妥），然后：

1
2
git remote add origin git@github.com:用户名/blog-source.git
git push -u origin main

站点库 用户名.github.io 完全不用动，它现在就是线上网站，hexo d 继续往里推。

4. 部署配置（双仓库下无需修改）

_config.yml 的 deploy 指向站点库，保持原样：

1
2
3
4
deploy:
  type: git
  repo: git@github.com:用户名/用户名.github.io.git
  branch: main

若未装部署插件：npm install hexo-deployer-git --save。

5. .deploy_git 说明

它是 hexo-deployer-git 私有的嵌套 git 仓库（remote 指向站点库），与源码库无关，且已被 .gitignore 的 .deploy*/ 忽略，安全无影响，保持原样即可。

四、日常持续更新流程（发布文章!!!）

1
2
3
hexo new post "标题"                          # 1. 写文章（生成 source/_posts/标题.md）
hexo clean && hexo g && hexo d                # 2. 生成并部署 → 更新站点库
git add -A && git commit -m "更新: 标题" && git push   # 3. 备份源码 → 更新源码库
  • 第 1、3 步工作在源码库；第 2 步由 hexo d 维护站点库。
  • 两个 remote 各管各的，天然隔离，不会互相覆盖。
  • 建议每次发布后顺手 push 一次源码，换电脑也能无缝继续。

若未全局安装 hexo-cli，直接用 npm run server / npm run build / npm run deploy / npx hexo new，它们会自动使用本地 node_modules/.bin/hexo。

五、Hexo 与主题的安装和更新

5.1 安装依赖（恢复 / 重建环境）

Hexo 本体、主题、部署插件等全部通过 npm 管理，依赖清单写在 package.json。无论首次恢复还是换电脑，重建运行环境只需一条：

1
npm install

它会按 package.json 安装 hexo、hexo-theme-fluid、hexo-deployer-git 等全部依赖（含 node_modules）。

让 hexo 命令全局可用（直接敲 hexo s 而非 npm run server）：

1
npm install -g hexo-cli

全局 hexo-cli 只是「命令壳」，实际调用的是项目本地 node_modules 里的 hexo 版本，二者兼容，可放心装。

5.2 更新 Hexo 版本

1
npm install hexo@latest --save      # 升级到最新稳定版

升级目标受 Node 版本约束（Hexo 官方版本表）：

Hexo 版本 Node.js 要求
6.x 最高仅支持 Node 18.5.0
7.0+ Node 14.0.0 ~ latest
8.0+ 最低 Node 20.19.0

因此，若新电脑是 Node 20 / 22，旧 Hexo 6 属于「官方不支持」，本地能跑也只是侥幸，建议升级。先 node -v 判断目标版本，再执行上面的命令。

升级 Hexo 后必须同步升级主题：新版 Hexo（尤其 8.x）与旧版 Fluid（如 1.9.x）可能不兼容，会导致 hexo g 报错或样式异常。请紧接着执行 5.3 的 npm install --save hexo-theme-fluid 把主题升到兼容版本，再验证。

5.3 更新主题（以 Fluid 为例）

官方安装 / 更新命令：

1
2
npm install --save hexo-theme-fluid        # 安装或更新到最新稳定版
# 仅更新已有主题也可：npm update --save hexo-theme-fluid

Fluid 版本号 X.Y.Z 中，X 代表产品级重大重构，跨 X 时涉及大范围配置变更，更新前必须阅读文档。从 1.x → 2.x 即跨 X，需特别注意：

  • 移除 51la / cnzz 统计插件（2.x 破坏性变更）：旧 _config.fluid.yml 若用了这两项会失效，可改 Umami / 百度统计 / GA4 或自定义 js；
  • Google Analytics 的 UA 已被 GA4 取代，相关字段需调整；
  • 升级后需对照 node_modules/hexo-theme-fluid/_config.yml（主题默认配置）重审你的 _config.fluid.yml，删除已废弃项。

5.4 升级前务必先建源码库基线

大版本升级（如 Hexo 6→7/8、Fluid 1.x→2.x）可能让主题报错、配置失效。升级前请先按第三节把当前可跑版本提交到源码库，一旦翻车可回退到该基线。

官方文档参考：Hexo https://hexo.io/zh-cn/docs/；Fluid https://fluid.ist/docs/start/

六、换电脑 / 重新拉取后如何恢复继续更新

1
2
3
4
git clone git@github.com:用户名/blog-source.git my-blog   # 拉取源码库
cd my-blog
npm install                            # 按 package.json 恢复 hexo + 主题等依赖
npm run server                         # 或 hexo s，本地预览 http://localhost:4000

确认文章与主题都正常后，即可照常执行第四节的更新流程。

若 hexo 命令找不到，用上面对应的 npm run / npx 写法；是否升级 Hexo / Fluid 大版本见第五节，且升级前务必已建好源码库基线。

七、部署与备份要点（红线）

  • 站点库 main 分支：只由 hexo d 维护，不要手动提交源码，也不要 git push --all 把源码推上去覆盖线上站点。
  • 源码库 main 分支：只由 git push 维护。
  • 两条线互不干扰，这就是双仓库的护城河。

八、常见问题

  1. hexo 不是内部或外部命令
    未全局安装 hexo-cli。用 npm run server / npm run deploy / npx hexo new 等本地调用；或 npm install -g hexo-cli 一劳永逸。

  2. 换电脑后 hexo d 提示认证失败
    GitHub 已默认禁用密码，改用 Personal Access Token 或配置 SSH key；远程地址建议用 git@github.com:... 形式。

  3. 部署后样式丢失 / 空白页
    通常是 root 配置错误。若部署到子路径（github.io/repo），需把 root: /repo/ 填对；User 主页用 root: /。

  4. 文章不更新
    先 hexo clean 再重新 hexo g && hexo d，排除旧缓存干扰。

  5. .deploy_git 嵌套仓库提示 warning
    git 可能提示 ignoring nested git repository .deploy_git，这是正常提示，不是错误，忽略即可。

  6. npm install 后一大堆 vulnerabilities / audit 警告
    旧依赖的已知漏洞统计，静态博客线上风险有限。不要跑 npm audit fix --force（强制升级大版本会破坏兼容）；npm audit fix（不带 force）也建议暂不跑，等上线稳定后再单独处理。

九、命令速查

命令 作用
npm install 安装 / 恢复 hexo + 主题等全部依赖
npm install -g hexo-cli 全局安装 hexo 命令壳
npm install hexo@latest --save 升级 Hexo 到最新稳定版
npm install --save hexo-theme-fluid 安装 / 更新 Fluid 主题
hexo new post <标题> / npx hexo new post <标题> 新建文章
hexo s / npm run server 本地预览
hexo g / npm run build 生成静态文件
hexo d / npm run deploy 部署 → 更新站点库
hexo clean 清除缓存
git add -A && git commit && git push 备份源码 → 更新源码库

组合发布：hexo clean && hexo g && hexo d，随后 git push。

博客搭建
#Hexo #博客
Hexo博客持续更新指南
https://zyue2022.github.io/2026/08/08/Hexo博客持续更新/
作者
ZYUE
发布于
2026年8月8日
更新于
2026年8月8日
许可协议