GitHubPages建站教程：gh-pages分支部署指南

本文彻底澄清了GitHub Pages部署中长期被误解的gh-pages分支问题：自2021年起，GitHub已默认支持直接从main/master分支的根目录或/docs目录发布站点，gh-pages分支仅作向后兼容，不仅非必需，反而极易引发404、循环部署、权限异常和协作断层等实际风险；文章直击痛点，明确指出绝大多数项目应摒弃gh-pages分支，转而通过正确配置发布源、确保index.html存在、合理设置base URL（尤其对非username.github.io的项目页至关重要），并推荐使用gh CLI或标准化Actions自动化部署——帮你避开踩坑、简化流程、回归高效开发。

gh-pages 分支不是必须的，现在绝大多数场景下不推荐用它。

GitHub Pages 自 2021 年起已默认支持从 main（或 master）分支的根目录 / 或 /docs 目录直接发布，gh-pages 分支仅保留向后兼容，且会引入额外管理负担。除非你明确需要 Jekyll 构建流程隔离、或依赖某些老旧 CI 脚本，否则别碰它。

gh-pages 分支为什么容易出问题

• 它和主分支历史完全分离，每次推送都要 git push origin gh-pages --force 或 git subtree push，极易覆盖线上内容
• 本地误删 gh-pages 分支再重建，会导致 GitHub Pages 设置里“Source”仍指向该分支，但实际无内容，页面 404
• GitHub Actions 若配置了写入权限到 gh-pages 分支，又没加 if: github.event_name == 'push' && github.event.branch == 'main' 这类保护条件，可能触发循环部署
• gh-pages 分支无法享受主分支的 PR 检查、代码审查、自动格式化等协作流程

如果非要用 gh-pages 分支，必须做这三件事

• 创建分支并推送到远程：

  git checkout -b gh-pages  
  git push origin gh-pages

  注意：不要在 gh-pages 分支上直接写代码，它应只含构建产物（如 index.html、dist/ 内容）

• 在仓库 Settings → Pages → Source 中，手动选中 gh-pages 分支，并确认保存
  若页面显示 “Your site is ready to be published at https://xxx.github.io”，说明生效；若一直卡在 “Building” 或报错，大概率是分支里缺少 index.html 或文件权限异常（比如用了 git add -f 强制添加了 .gitignore 里的构建目录但未提交）

• 部署时避免手动生成 + 手动 push：

  • 不要 npm run build && cp -r dist/* ../gh-pages/ && git add . && git commit -m "deploy" 这种操作——容易漏文件、路径错乱
  • 更稳妥的是用 gh pages deploy --dir ./dist（需先安装 gh CLI 并登录）
  • 或用 peaceiris/actions-gh-pages@v3 的 Action，配合 publish_branch: gh-pages 参数

index.html 路径和 base URL 容易被忽略

如果你的仓库名不是 username.github.io（即不是个人主页），而是普通项目页（如 my-project），那么 GitHub Pages 默认访问路径是 https://username.github.io/my-project/。此时：

• index.html 中所有相对路径（如 ./css/style.css）会按这个子路径解析
• 若你用 Vite / Vue / React 等构建工具，必须在配置里显式设 base: "/my-project/"，否则 JS/CSS 404
• 不要指望