GitHub Pages部署必须满足三要素：仓库名严格为username.github.io（用户页）或任意名（项目页）、index.html置于main分支根目录、Pages功能在Settings中手动开启并选对分支与文件夹，缺一不可。
能直接部署，但必须满足三个硬性条件：仓库命名合规、index.html在正确位置、Pages 功能手动开启——缺一不可，不会“稍等片刻就自动生效”。
仓库名和访问路径怎么选才不 404
你不是在“上传一个文件”，而是在配置一个托管入口，路径规则由仓库名决定：
- 要建个人主页（如
https://yourname.github.io）：仓库名必须严格为yourname.github.io，不能多字符、不能少点、不能大小写错 - 要建项目页（如
https://yourname.github.io/my-project）：仓库名随意，但所有资源链接（<link>、<script>、img src）必须适配子路径——本地双击能跑，上传后全挂，八成是这里没改 - 别用
gh-pages分支：它已过时，2021 年起 GitHub 默认支持从main分支根目录或/docs目录发布；用它只会增加分支同步风险和配置复杂度
index.html 放哪儿、怎么命名才有效
index.html 是唯一被自动识别的入口文件，GitHub Pages 不会猜你想要哪个 HTML：
- 必须放在仓库根目录（即
main分支最外层），或/docs目录下（如果你在 Settings → Pages 里把 Folder 设为/docs） - 文件名必须是
index.html，大小写敏感；Index.html、INDEX.HTML、home.html都无效 - 不能依赖后端：删掉所有
.php、.js服务端逻辑，也不能指望.htaccess生效——它们会被当文本下载，而不是执行
为什么 push 完还是打不开？Pages 设置三步不能跳
很多人卡在这一步：代码已推、文件已传、但页面始终不出现。根本原因是 Pages 功能默认关闭，且设置项容易选错：
Git Changelog Generator
下载
使用约定式提交（Conventional Commits）从 Git 历史记录中生成结构化变更日志，支持多种格式、AI 增强型描述以及可自定义的范围……
立即学习“前端免费学习笔记（深入）”；
- 进仓库 → Settings → 左侧菜单找到 Pages（在 Code and automation 分类下）
- Source 选分支：
Branch选main（或你实际使用的默认分支），Folder选/(root)（除非你把文件全放进了/docs） - 点 Save 后等 30 秒–2 分钟，下方出现绿色提示 “Your site is live at …” 才算真正启用；如果只显示 “Build queued”，说明
index.html缺失或路径不对
SPA 刷新 404 或资源加载失败的常见补救
单页应用（Vue/React）或含相对路径资源的页面，上线后常出现白屏或控制台报 404，问题往往不在代码本身：
- 前端路由必须用
hash模式（如/#/about），history模式在 GitHub Pages 下无服务端 fallback，必然刷新 404 - 项目页（非
username.github.io）需显式配置base：Vite 项目加base: '/仓库名/'，Vue CLI 加publicPath: '/仓库名/'，否则所有js/css请求地址都会错位 - 加一个
404.html放在根目录：GitHub Pages 会把它作为 SPA 的兜底页，避免用户刷新时看到默认 404 页面
最容易被忽略的是路径与 base 的耦合关系：你以为只是改个链接，其实它决定了整个资源加载链路。调试时别只看 console 报错，先确认浏览器地址栏路径是否匹配你的仓库类型，再检查所有 href 和 src 值是否带了预期的前缀。
