gh-pages分支非必须且不推荐，GitHub Pages自2021年起默认支持从main/master分支根目录或/docs目录发布；仅需正确配置发布源、确保index.html存在、设置合理base URL即可避免404等问题。

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://www.php.cn/link/ef3217af91c6be2ed9ff90f60f247620 “Building” 或报错，大概率是分支里缺少 index.html 或文件权限异常（比如用了 git add -f 强制添加了 .gitignore 里的构建目录但未提交）

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

  

  GitHub Iteration Workflow

  GitHub Issue 全流程自动化：自动拉取、修复 Issue，创建 PR，监控 CI/CD，合并部署。

  下载

  立即学习“前端免费学习笔记（深入）”；

  • 不要 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 默认访问路径是 <a href="https://www.php.cn/link/b07dae8bbe4114d04f34488119725b99">https://www.php.cn/link/b07dae8bbe4114d04f34488119725b99</a>。此时：

• index.html 中所有相对路径（如 ./css/style.css）会按这个子路径解析
• 若你用 Vite / Vue / React 等构建工具，必须在配置里显式设 base: "/my-project/"，否则 JS/CSS 404
• 不要指望 <base href="/> 标签能兜底——它对 script src、link href 有效，但对前端路由 history 模式无效

最简单的验证方式：打开浏览器开发者工具 → Network 标签页，看是否有 404 的资源请求，尤其是 assets/ 或 css/ 开头的路径。