如果你在使用 Hexo 部署博客时，发现 hexo deploy 把静态文件推送到了存放源码的分支（比如 main 或 master），导致源码被覆盖，不要慌！这篇文章会帮你分析原因并解决问题。

问题描述

当你运行 hexo deploy 时，Hexo 本应把生成的静态文件推送到部署分支（通常是 gh-pages），但实际上却推送到了当前的源码分支。这会导致你的博客源码被静态文件覆盖，损失惨重。

原因分析与解决方法

原因一：_config.yml 配置未指定或指定错了分支

这是最常见的原因。Hexo 的部署配置在根目录的 _config.yml 文件中。如果没有明确指定 branch 参数，或者不小心写成了源码分支名，Hexo 就会把文件推送到错误的分支。

解决方法：

打开 _config.yml，找到 deploy 字段，确保正确指定了部署分支：

1
2
3
4
5
deploy:
  type: git
  repo: [email protected]:你的用户名/你的仓库名.git
  branch: gh-pages  # 明确指定部署分支
  message: "Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}"

⚠️ 注意：YAML 对缩进非常敏感，请使用两个空格进行缩进，不要使用 Tab。

原因二：.deploy_git 缓存文件夹记录了错误的分支状态

首次运行 hexo deploy 后，Hexo 会在项目根目录创建一个 .deploy_git 隐藏文件夹。这是一个本地 Git 仓库，用于暂存静态文件并推送到远端。

如果你之前配置错误并运行过部署，或者在 .deploy_git 里手动执行过 Git 操作，这个文件夹可能记录了错误的分支状态。即使修改了 _config.yml，问题可能依然存在。

解决方法：

彻底清理缓存，重新部署：

1
2
3
4
5
6
7
8
# 1. 删除旧的部署缓存文件夹
rm -rf .deploy_git

# 2. 清除 Hexo 缓存
hexo clean

# 3. 重新生成并部署
hexo generate --deploy

原因三：混淆了”源码分支”和”部署分支”

这是一个概念性的问题。最佳实践是将博客源码和生成的静态文件分开存放：

分支类型 分支名称 用途
源码分支 main / master / source 存放 Markdown 源文件、配置文件等，手动备份
部署分支 gh-pages 存放生成的静态网页，由 hexo deploy 自动推送

特殊情况：User Pages

如果你的仓库名是 用户名.github.io（GitHub User Pages），GitHub 默认会从 main 或 master 分支读取静态文件。这种情况下，你需要：

  1. 把源码存放到其他分支（比如 source）
  2. 让 hexo deploy 推送到 main 分支

配置示例：

1
2
3
4
deploy:
  type: git
  repo: [email protected]:你的用户名/你的用户名.github.io.git
  branch: main  # User Pages 需要推送到 main

总结

遇到 Hexo deploy 推送错误分支的问题，按以下步骤排查：

  1. ✅ 检查配置：确保 _config.yml 中明确指定了正确的 branch
  2. ✅ 清理缓存：删除 .deploy_git 文件夹并运行 hexo clean
  3. ✅ 理清概念：区分源码分支和部署分支，避免混淆

希望这篇教程对你有帮助！如果还有问题，欢迎留言讨论。