🚨 Hexo GitHub Actions 部署踩坑记录：从 ESM 错误到 Node.js 版本问题
记录一次完整的 Hexo + GitHub Actions 部署问题排查过程：从 hexo: command not found 到 ESM 模块错误，再到最终的 Node.js 版本兼容性解决方案。
背景说明 正在将 Hexo 博客从传统的 hexo-deployer-git 方式迁移到现代化的 GitHub Pages 部署方式，遇到了一系列依赖和兼容性问题。
🔴 问题一：hexo: command not found 现象 1 2 3 Run npx hexo clean /home/runner/work/_temp/0b03d745-88c2-4991-a01f-22bd91c0e9dd.sh: line 1: hexo: command not found Error: Process completed with exit code 127.
原因分析 GitHub Actions 环境中 Hexo 没有全局安装，只能通过 npx 运行本地版本。
解决方案 将工作流中的 hexo 命令改为 npx hexo：
1 2 3 4 5 6 7 8 9 10 11 - name: Build run: | hexo clean hexo generate - name: Build run: | npx hexo clean npx hexo generate
🔴 问题二：ESM 模块兼容性错误 现象 1 2 FATAL Error [ERR_REQUIRE_ESM]: require() of ES Module /home/runner/work/myblog/myblog/node_modules/strip-ansi/index.js from /home/runner/work/myblog/myblog/node_modules/hexo/dist/plugins/console/list/common.js not supported.
原因分析
strip-ansi@7.1.2 是纯 ESM 模块Hexo 8.0.0 使用 CommonJS require() 加载
Node.js 18 对 ESM 兼容性不够完善
尝试的解决方案 方案 A：降级 strip-ansi 版本 1 npm install strip-ansi@6.0.1 --save-exact
结果 ：部分成功，但 GitHub Actions 中 Hexo 内部的 strip-ansi@7.1.2 仍然覆盖了修复。
方案 B：使用 npm overrides 1 2 3 4 5 { "overrides" : { "strip-ansi" : "6.0.1" } }
结果 ：理论上可行，但配置复杂。
✅ 最终解决方案：升级 Node.js 版本 原理 Node.js 22 对 ESM 模块支持更加完善，可以正确处理 CommonJS 和 ESM 的互操作。
实施步骤
修改 GitHub Actions 工作流 ：
1 2 3 4 5 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' cache: 'npm'
简化依赖安装 ：
1 2 3 4 5 - name: Install dependencies run: | npm ci # 确保安装所有必需的渲染器 npm install hexo-renderer-pug hexo-renderer-stylus --save
本地环境保持一致 ：
关键要点
环境一致性 ：本地和 CI 环境使用相同 Node.js 版本简化依赖 ：不再强制指定 strip-ansi 版本，让 Node.js 22 自动处理兼容性移除冗余 ：删除 hexo-deployer-git 等不再需要的依赖
🔧 完整的 GitHub Pages 部署工作流 文件：.github/workflows/pages.yml 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 name: Build and Deploy to GitHub Pages on: push: branches: [ master ] workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: "pages" cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 with: submodules: recursive - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '22' cache: 'npm' - name: Install dependencies run: | npm ci # 确保安装所有必需的渲染器 npm install hexo-renderer-pug hexo-renderer-stylus --save - name: Build run: | npx hexo clean npx hexo generate - name: Setup Pages uses: actions/configure-pages@v4 - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: ./public deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4
📋 部署配置更新 1. 更新 _config.yml 1 2 3 4 5 6 7 8 url: https://SVEN-chr.github.io/myblog
2. 清理不需要的依赖 1 2 3 4 5 npm uninstall hexo-deployer-git "deploy" : "echo 'Deploy handled by GitHub Actions'"
🎯 验证步骤
本地测试 ：
1 npx hexo clean && npx hexo generate
推送代码 ：
1 git add . && git commit -m "migrate: 升级到 GitHub Pages 部署" && git push
启用 GitHub Pages ：
进入仓库 Settings → Pages
Source 选择 “GitHub Actions”
检查部署 ：
访问 https://username.github.io/repo-name
查看 Actions 运行日志确认成功
📚 经验总结 ✅ 正确的做法
使用 npx 运行 Hexo ：避免全局依赖问题Node.js 版本一致 ：本地和 CI 环境使用相同版本优先使用现代方案 ：GitHub Pages 部署比 hexo-deployer-git 更可靠环境变量管理 ：使用 npm ci 而非 npm install 确保依赖一致性
❌ 避免的坑
不要混用部署方案 ：要么 hexo-deployer-git，要么 GitHub Pages不要忽略 Node.js 版本 ：不同版本的 ESM 支持差异很大不要强制依赖版本 ：除非必要，否则让包管理器处理兼容性不要忽略权限配置 ：GitHub Pages 需要正确的 permissions 设置
🔄 迁移对比
方面
hexo-deployer-git
GitHub Pages
配置复杂度 中等（需配置 SSH）
简单（自动认证）
部署速度 慢（需推送两个仓库）
快（直接部署）
可靠性 中等（依赖 SSH 配置）
高（官方支持）
维护成本 高（需维护两个仓库）
低（单仓库）
推荐度 ⭐⭐⭐
⭐⭐⭐⭐⭐
结语 通过这次踩坑经历，深刻体会到：
环境一致性的重要性 ：本地和 CI 环境的差异是很多问题的根源Node.js 版本升级的价值 ：新版本对现代 JS 生态支持更好选择合适的技术方案 ：GitHub Pages 部署比传统方式更可靠系统化排查问题 ：从命令错误到依赖兼容性，需要层层深入
如果你也遇到类似问题，希望这篇踩坑记录能帮你节省时间！
📚 参考链接
