这篇文章是本仓库的**“维护终章”**：把日常维护、更新、部署、批量导入、工具脚本与常见问题全部系统化整理成一份可执行的操作手册。

如果你只记一个命令：

  • 日常发布：npm run publish

0. 你正在维护的是什么

  • 站点框架：Hexo 8.x
  • 主题：Butterfly（仓库依赖锁定在 hexo-theme-butterfly）
  • 部署方式：hexo-deployer-git 推送静态产物到 gh-pages 分支（GitHub Pages 读取该分支）
  • 内容目录：source/_posts/
  • 维护脚本目录：tools/

主题不要直接改 themes/butterfly/ 源码（会被升级脚本覆盖），主题改动统一写在 _config.butterfly.yml。

1. 日常维护（90% 情况只需要这几条）

1.1 本地预览

npm run server

如果你希望每次都从干净状态起：

npm run dev

1.2 一键发布到线上（推荐）

npm run publish

它等价于：

hexo clean && hexo generate && hexo deploy

你几乎总是应该用它，而不是单独 hexo deploy。

1.3 只部署（你已经 generate 过）

npm run deploy
# 或
npx hexo deploy

2. 文章与内容管理

2.1 新建文章

npx hexo new "文章标题"

然后去 source/_posts/ 编辑生成的 Markdown。

2.2 关于内部链接（非常重要）

站内文章互相链接时，不要写成文件路径：

  • ❌ source/_posts/xxx.md

应该写成站内 URL（更稳，生成后一定可用）：

  • ✅ /YYYY/MM/DD/文章标题/

比如工具文章统一在这里：

  • /2025/12/31/HExLL维护/HExLL工具脚本总览/

3. 部署体系与认证（避免踩坑）

3.1 GitHub Pages 的正确设置

  • 目标分支：gh-pages
  • 站点根目录：/（root）

3.2 推荐使用 SSH 部署（不要把 token 写进仓库）

如果你当前使用的是 https + token（最常见问题：token 过期导致 deploy 失败），建议切换到 SSH：

  1. 生成 SSH key：
ssh-keygen -t ed25519 -C "your_email@example.com"

  1. 把公钥加入 GitHub（Settings → SSH and GPG keys）

  2. 将 _config.yml 中 deploy.repo 改为：

deploy:
  type: git
  repo: git@github.com:yuanweize/yuanweize.github.io.git
  branch: gh-pages

4. tools/ 目录：维护脚本与使用边界

先看总览（建议收藏）：

4.1 md2Hexo：批量补齐 front matter

适用：外部 Markdown 导入、整理知识库、批量迁移。

常用命令：

# 交互式
python3 tools/md2Hexo.py

# 预览（不写入）
python3 tools/md2Hexo.py --dry-run -d source/_posts

# 配置文件批处理
python3 tools/md2Hexo.py --config tools/configs/awesome-cheatsheets.json -d source/_posts/awesome-cheatsheets

详细说明：

4.2 upgrade.sh：本地升级依赖/主题并重新生成

适用：你希望更新 Hexo、插件依赖、Butterfly 主题，并重新生成静态文件。

bash tools/upgrade.sh

它做的事情（按顺序）：

  1. npm install（确保依赖存在）
  2. npm update（更新依赖到允许范围内的新版本）
  3. 删除并重拉 themes/butterfly（确保主题为上游最新）
  4. hexo clean
  5. hexo generate

风险提示：

  • 如果你曾经直接改过 themes/butterfly/，会被覆盖；请把改动迁移到 _config.butterfly.yml。

详细说明：

4.3 update.sh：服务器侧对齐 gh-pages

适用：你有服务器工作区，Nginx/宝塔直接指向站点目录，需要“强制对齐”到 origin/gh-pages。

bash tools/update.sh

详细说明：

5. 一张表搞定：所有维护操作与命令

目标 命令
本地预览 npm run server
清理缓存 npm run clean
生成静态 npm run build
一键发布（推荐） npm run publish
仅部署 npm run deploy
更新 Algolia 索引 npm run algolia
批量补 front matter（预览） python3 tools/md2Hexo.py --dry-run -d source/_posts
升级依赖/主题并重新生成 bash tools/upgrade.sh
服务器对齐 gh-pages bash tools/update.sh

6. 常见问题（Troubleshooting）

6.1 hexo deploy 失败 / Exit Code 非 0

优先使用：

npm run publish

如果还是失败，99% 是认证问题（token 过期 / SSH 未配置）或网络问题。

6.2 工具文章里链接点不开

确保链接写的是 URL 形式：

  • ✅ /2025/12/31/HExLL维护/upgrade-sh-本地升级脚本/

不要写源文件路径。

7. 结语

至此，这个仓库的“维护体系”已经闭环：

  • 日常发布：npm run publish
  • 批量导入：md2Hexo.py
  • 本地升级：upgrade.sh
  • 服务器同步：update.sh

建议你把这篇文章加入书签，之后维护就按表执行即可。