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：
- 不要
npm run build && cp -r dist/* ../gh-pages/ && git add . && git commit -m "deploy"这种操作——容易漏文件、路径错乱 - 更稳妥的是用
gh pages deploy --dir ./dist（需先安装ghCLI 并登录） - 或用
peaceiris/actions-gh-pages@v3的 Action，配合publish_branch: gh-pages参数
- 不要
index.html 路径和 base URL 容易被忽略
如果你的仓库名不是 username.github.io（即不是个人主页），而是普通项目页（如 my-project），那么 GitHub Pages 默认访问路径是 @#@#@#@#@#@#@#@#@#@1。此时：
-
index.html中所有相对路径（如./css/style.css）会按这个子路径解析 - 若你用 Vite / Vue / React 等构建工具，必须在配置里显式设
base: "/my-project/"，否则 JS/CSS 404 - 不要指望
<base href="/>%20%E6%A0%87%E7%AD%BE%E8%83%BD%E5%85%9C%E5%BA%95%E2%80%94%E2%80%94%E5%AE%83%E5%AF%B9%20script%20src%E3%80%81link%20href%20%E6%9C%89%E6%95%88%EF%BC%8C%E4%BD%86%E5%AF%B9%E5%89%8D%E7%AB%AF%E8%B7%AF%E7%94%B1%20history%20%E6%A8%A1%E5%BC%8F%E6%97%A0%E6%95%88%20%20
%E6%9C%80%E7%AE%80%E5%8D%95%E7%9A%84%E9%AA%8C%E8%AF%81%E6%96%B9%E5%BC%8F%EF%BC%9A%E6%89%93%E5%BC%80%E6%B5%8F%E8%A7%88%E5%99%A8%E5%BC%80%E5%8F%91%E8%80%85%E5%B7%A5%E5%85%B7%20%E2%86%92%20Network%20%E6%A0%87%E7%AD%BE%E9%A1%B5%EF%BC%8C%E7%9C%8B%E6%98%AF%E5%90%A6%E6%9C%89%20404%20%E7%9A%84%E8%B5%84%E6%BA%90%E8%AF%B7%E6%B1%82%EF%BC%8C%E5%B0%A4%E5%85%B6%E6%98%AF%20assets/%20%E6%88%96%20css/%20%E5%BC%80%E5%A4%B4%E7%9A%84%E8%B7%AF%E5%BE%84%E3%80%82
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
