这个脚本是干什么的？

tools/upgrade.sh 是一个本地开发机使用的脚本，一键完成：

  1. 更新所有 npm 依赖（包括 Hexo）到最新版本
  2. 重新拉取 Butterfly 主题最新版
  3. 清理缓存并重新生成站点

使用场景

  • 定期更新博客依赖，获取 bug 修复和新功能
  • Butterfly 主题发布新版本后想升级
  • 依赖出问题时"重置"整个构建环境

用法

在仓库根目录执行：

bash tools/upgrade.sh

执行完成后：

  • 本地预览：npm run server
  • 正式部署：npm run publish

完整源码

#!/bin/bash
# HExLL 自动更新部署脚本
# 用途：更新所有依赖（包括 Hexo）+ 更新 Butterfly 主题 + 重新生成站点

set -euo pipefail

echo "HExLL 自动更新部署开始..."

# 进入项目目录
cd "$(dirname "$0")/.."

# 1. 更新所有依赖到最新版本（包括 Hexo）
echo "更新依赖到最新版本..."
npm update
# 如果想更激进地升级（包括 major 版本），可手动运行：npx npm-check-updates -u && npm install

# 2. 下载最新 Butterfly 主题
echo "更新 Butterfly 主题到最新版..."
if [ -d "themes/butterfly" ]; then
    rm -rf themes/butterfly
fi
git clone --depth 1 --branch latest https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
rm -rf themes/butterfly/.git

# 3. 清理 Hexo 缓存
echo "清理 Hexo 缓存..."
npx hexo clean

# 4. 生成静态文件
echo "生成静态文件..."
npx hexo generate

# 5. 本地预览提示
echo ""
echo "构建完成！"
echo ""
echo "📋 下一步操作:"
echo "   预览: npm run server"
echo "   部署: npm run deploy"
echo ""
echo "Butterfly 版本: latest"
echo "Hexo 版本: $(npx hexo version | head -1)"

逐行代码解析

第 1-3 行：Shebang 和注释

#!/bin/bash
# HExLL 自动更新部署脚本
# 用途：更新所有依赖（包括 Hexo）+ 更新 Butterfly 主题 + 重新生成站点
  • #!/bin/bash：指定用 bash 执行
  • 注释说明脚本用途，方便日后维护

第 5 行：严格模式

set -euo pipefail

三个选项的含义：

  • -e：任何命令失败立即退出
  • -u：使用未定义变量报错
  • -o pipefail：管道中任一命令失败则整体失败

第 10 行：定位仓库根目录

cd "$(dirname "$0")/.."
  • $0：脚本路径
  • dirname：取目录部分
  • /..：上一级

无论从哪执行，都能正确进入仓库根目录。

第 13-15 行：更新 npm 依赖

echo "更新依赖到最新版本..."
npm update
# 如果想更激进地升级（包括 major 版本），可手动运行：npx npm-check-updates -u && npm install

关键点：

命令 行为
npm install 安装 package.json 声明的版本
npm ci 严格按 package-lock.json 安装（可复现）
npm update 更新到 package.json 允许的最新版本
npm-check-updates -u 把 package.json 中的版本号直接改成最新（包括大版本）

npm update 会更新到 semver 范围内的最新版本。例如：

  • "hexo": "^8.0.0" → 会更新到 8.x.x 的最新版，但不会跳到 9.x
  • 想升级大版本需要手动操作或用 npm-check-updates

第 17-23 行：更新 Butterfly 主题

echo "更新 Butterfly 主题到最新版..."
if [ -d "themes/butterfly" ]; then
    rm -rf themes/butterfly
fi
git clone --depth 1 --branch latest https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
rm -rf themes/butterfly/.git

逻辑分解：

  1. 如果 themes/butterfly 存在，先删除
  2. 浅克隆（--depth 1）最新版本（--branch latest）
  3. 删除主题的 .git 目录（不需要主题自己的版本历史）

为什么不用 npm 安装主题：Butterfly 推荐 git clone 方式，便于获取最新版本和查看源码。

第 25-28 行：清理缓存

echo "清理 Hexo 缓存..."
npx hexo clean

hexo clean 删除：

  • public/ 目录（生成的静态文件）
  • db.json（Hexo 数据库缓存）

为什么需要：升级后可能有缓存不兼容，清理后重新生成更可靠。

第 30-32 行：生成静态文件

echo "生成静态文件..."
npx hexo generate

根据 source/ 目录的内容生成 public/ 目录。

第 34-42 行：完成提示

echo ""
echo "构建完成！"
echo ""
echo "📋 下一步操作:"
echo "   预览: npm run server"
echo "   部署: npm run deploy"
echo ""
echo "Butterfly 版本: latest"
echo "Hexo 版本: $(npx hexo version | head -1)"

输出友好提示和版本信息，方便确认升级结果。

注意事项

1. 主题自定义会被覆盖

脚本会删除并重新拉取 themes/butterfly。如果你直接修改过主题源码，会丢失。

正确做法：所有主题配置都放在 _config.butterfly.yml，不要直接改主题源码。

2. npm update 的局限性

npm update 只更新到 package.json 允许的范围内。如果想跨大版本升级：

# 检查哪些包有新版本
npx npm-check-updates

# 更新 package.json 到最新版本
npx npm-check-updates -u

# 安装
npm install

3. 升级后记得测试

npm run server

本地预览没问题再 npm run publish。

与其他脚本的关系

脚本 用途 使用环境
upgrade.sh 更新依赖和主题 本地开发机
update.sh 同步 gh-pages 内容 服务器
md2Hexo.py 批量转换 Markdown 本地开发机