前言

在使用 Hexo 部署博客时，一个常见的问题是：执行 hexo deploy 后，静态文件被推送到了源码分支（如 main 或 hexo），而不是预期的部署分支（如 gh-pages）。

这会导致源码被覆盖，造成严重的数据丢失。本文将详细分析原因并提供完整的解决方案。

问题现象

执行 hexo deploy 后出现以下情况：

  • 静态文件被推送到 main 或 hexo 分支
  • 原有的 Markdown 源码文件消失
  • GitHub Pages 无法正常访问

原因分析

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

这是最常见的原因。

Hexo 的部署依赖于 _config.yml 文件中的 deploy 配置。如果没有明确指定 branch 参数，或者将 branch 写成了当前的源码分支，Hexo 就会推送到错误的分支。

错误配置示例：

1
2
3
4
deploy:
  type: git
  repo: [email protected]:username/repo.git
  # 缺少 branch 参数，或 branch 写成了源码分支

正确配置示例：

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 仓库，用于暂存生成的静态网页并推送到远端。

问题：如果之前配置错误并运行过部署，或者在该文件夹内手动执行过 Git 操作，.deploy_git 里面绑定的分支状态可能已经错乱。

即使修改了 _config.yml，它仍然可能推送到错误的分支。

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

这是概念理解上的问题。最佳实践是将博客源码和生成的静态网页分开存放：

类型 分支名称 内容 管理方式
源码分支 main / hexo / source Markdown、主题配置 手动 git push
部署分支 gh-pages / master HTML/CSS/JS hexo deploy 自动推送

特殊情况：GitHub User Pages（仓库名为 用户名.github.io）默认读取 main 或 master 分支。此时需要：

  • 将源码存放在其他分支（如 hexo）
  • 让 hexo deploy 推送到 main 或 master

解决方案

方案一：修正 _config.yml 配置

打开项目根目录的 _config.yml，找到 deploy 字段：

1
2
3
4
5
deploy:
  type: git
  repo: [email protected]:你的用户名/你的仓库名.git
  branch: gh-pages  # 或 master（针对 User Pages）
  message: "Site updated: {{ now('YYYY-MM-DD HH:mm:ss') }}"

分支选择建议：

  • Project Pages（username.github.io/repo）：使用 gh-pages 分支
  • User Pages（username.github.io）：使用 main 或 master 分支

方案二：清理 .deploy_git 缓存并重新部署

如果配置正确但仍然推送到错误分支，需要清理缓存：

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

# 2. 清除 Hexo 缓存
hexo clean

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

或者简写为：

1
rm -rf .deploy_git && hexo clean && hexo g -d

方案三：正确的分支管理流程

对于 Project Pages

1
2
3
4
5
6
7
# 1. 源码推送到 main 分支
git add .
git commit -m "update blog source"
git push origin main

# 2. 部署到 gh-pages 分支（由 hexo deploy 自动完成）
hexo clean && hexo g -d

_config.yml 配置：

1
2
3
4
deploy:
  type: git
  repo: [email protected]:username/project-name.git
  branch: gh-pages

对于 User Pages（username.github.io）

1
2
3
4
5
6
7
# 1. 源码推送到 hexo 分支
git add .
git commit -m "update blog source"
git push origin hexo

# 2. 部署到 master 分支
hexo clean && hexo g -d

_config.yml 配置：

1
2
3
4
deploy:
  type: git
  repo: [email protected]:username/username.github.io.git
  branch: master

预防措施

1. 使用部署脚本

创建 deploy.sh 脚本，统一管理部署流程：

1
2
3
4
5
6
7
8
9
10
11
12
#!/bin/bash

echo "🧹 Cleaning..."
hexo clean

echo "📦 Generating..."
hexo generate

echo "🚀 Deploying..."
hexo deploy

echo "✅ Deploy completed!"

使用方式：

1
2
chmod +x deploy.sh
./deploy.sh

2. 添加 .gitignore

确保 .deploy_git 不被意外提交：

1
2
3
4
5
6
# Hexo
.deploy_git/
public/
node_modules/
db.json
*.log

3. 定期备份源码

在执行 hexo deploy 之前，先提交源码：

1
2
3
git add .
git commit -m "backup source"
git push

4. 使用 CI/CD 自动部署

配置 GitHub Actions 自动部署，避免手动操作失误：

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
# .github/workflows/deploy.yml
name: Deploy Hexo

on:
  push:
    branches:
      - hexo  # 源码分支

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: hexo
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install Dependencies
        run: npm install
      
      - name: Deploy
        run: |
          hexo clean
          hexo generate
          hexo deploy
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}

常见问题

Q1: 执行 hexo deploy 后提示 ERROR Deployer not found: git

解决方法：安装 hexo-deployer-git 插件

1
npm install hexo-deployer-git --save

Q2: 部署后 GitHub Pages 显示 404

可能原因：

  1. 分支选择错误
  2. 仓库 Settings 中的 Pages 配置未设置正确

解决方法：

  1. 检查 _config.yml 中的 branch 配置
  2. 进入 GitHub 仓库 → Settings → Pages → 选择正确的分支

Q3: 如何查看当前 .deploy_git 绑定的分支？

1
2
3
cd .deploy_git
git branch -a
git remote -v

总结

问题 解决方案
配置未指定分支 修改 _config.yml，明确指定 branch
缓存分支错误 删除 .deploy_git，重新部署
分支概念混淆 分离源码分支和部署分支

核心要点：

  1. ✅ 在 _config.yml 中明确指定部署分支
  2. ✅ 遇到问题时先清理 .deploy_git 缓存
  3. ✅ 源码和部署文件使用不同分支管理
  4. ✅ 部署前先备份源码

📝 希望这篇文章能帮助你解决 Hexo 部署分支问题！如有疑问欢迎留言讨论。