将 Hexo 站点发布到 GitHub Pages

目标#

把本地 Hexo 生成的静态文件发布到 GitHub Pages，并通过 https://USERNAME.github.io/ 访问。

前置条件#

• 已有可运行的 Hexo 项目。
• 已安装受支持的 Node.js LTS 和 Git。
• GitHub 账号可以创建公开仓库。

创建 Pages 仓库#

在 GitHub 创建名为 USERNAME.github.io 的公开仓库，其中 USERNAME 必须与账号名完全一致。这种命名对应用户站点；普通项目仓库则发布在子路径下，Hexo 的 URL 配置也不同。

配置 Git 身份与 SSH#

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
ssh-keygen -t ed25519 -C "your-email@example.com"

为私钥设置口令，把生成的 .pub 公钥添加到 GitHub 的 Settings > SSH and GPG keys。验证连接：

ssh -T git@github.com

不要上传私钥，也不要把私钥内容粘贴到仓库配置。

安装 Git 部署器#

在 Hexo 项目根目录执行：

npm install --save hexo-deployer-git

修改 _config.yml：

url: https://USERNAME.github.io
root: /

deploy:
  type: git
  repo: git@github.com:USERNAME/USERNAME.github.io.git
  branch: main

YAML 冒号后需要空格，并且缩进只能使用空格。

发布与验证#

npx hexo clean
npx hexo generate
npx hexo server

先在本地检查文章、资源路径和链接，再执行：

npx hexo deploy

在仓库 Settings > Pages 中确认发布来源指向部署分支。GitHub Pages 更新可能需要几分钟；部署失败时先查看仓库分支和 Pages 构建记录。

回滚#

静态站点内容来自部署分支。需要回滚时，恢复源内容并重新生成部署；不要直接长期修改生成分支，否则下一次发布会覆盖修改。

参考#

• GitHub Pages：Creating a site
• Hexo one-command deployment
• GitHub SSH authentication