GitHub Pages用户页需仓库名严格为username.github.io，使用相对路径引用资源，Pages设置选main分支根目录，SPA刷新404问题可通过复制index.html为404.html解决。
仓库名必须是 username.github.io 才能直接访问根域名
如果你希望网站地址是 https://yourname.github.io（不带子路径），仓库名必须严格写成 yourname.github.io，其中 yourname 是你的 GitHub 用户名，全部小写、不能有下划线或大写字母。GitHub Pages 会自动把这种命名的仓库识别为“用户主页”，并从 main 分支根目录找 index.html。
常见错误：建了个叫 my-portfolio 或 website 的仓库，也设了 Pages，结果网址是 https://yourname.github.io/my-portfolio/ —— 这属于“项目页”，不是“用户页”，无法省略路径。
- 用户页（推荐新手）：仓库名 =
username.github.io→ 访问https://username.github.io - 项目页（灵活但带路径）：任意仓库名 → 访问
https://username.github.io/repo-name/ - 两者不能混用；一个账号只能有一个
username.github.io仓库
资源路径必须用相对路径，否则 CSS/JS 图片全 404
本地双击打开 index.html 能正常显示样式和图片，一推到 GitHub Pages 就全白屏或样式丢失？大概率是路径写死了。GitHub Pages 不是本地文件系统，file:/// 协议那一套不生效，所有 href、src 必须基于当前页面 URL 解析。
正确做法是统一用相对路径：
立即学习“前端免费学习笔记（深入）”；
- ✅
<link rel="stylesheet" href="style.css">（同级目录） - ✅
<img src="images/logo.png">（子目录） - ❌
<link rel="stylesheet" href="/style.css">（开头斜杠 → 指向根域，对项目页无效） - ❌
<img src="C:/project/images/logo.png">（绝对本地路径，毫无意义）
如果项目结构含子目录（如 css/、js/），确保 index.html 中引用路径与实际层级一致，并在 GitHub 仓库里保持同样结构。
监控一个或多个 GitCode 仓库的 PR，通过 OpenClaw Gateway 自动执行 AI 审查，发布 PR 评论，并发送钉钉和企业微信通知。
Pages 设置必须选对分支和根目录
即使代码已 push，GitHub Pages 也不会自动上线——你得手动进 Settings > Pages 开启并确认源配置。
- Source 选
Branch，不是Deploy from a branch旧选项 - Branch 选
main（不是master，GitHub 默认已切为main） - Folder 选
/(root)，不是/docs或其他子文件夹（除非你真把index.html放在docs/里） - 点 Save 后等 10–30 秒，页面顶部会出现绿色提示 “Your site is live at https://...”
如果没反应，检查是否漏点 Save，或是否误选了 gh-pages 分支（该分支需手动创建并 push，不推荐新手用）。
单页应用（SPA）刷新 404？加个 404.html 就行
用 Vue Router、React Router 或原生 History API 做前端路由时，访问 https://username.github.io/about 刷新会 404 —— 因为 GitHub Pages 只托管静态文件，它找不到 /about 这个真实 HTML 文件。
解决方法不是配服务器，而是利用 GitHub Pages 的 fallback 机制：
- 在仓库根目录新建一个
404.html文件 - 内容跟
index.html完全一样（复制粘贴即可） - 提交并 push
原理：当请求路径不匹配任何真实文件时，GitHub Pages 会返回 404.html，而这个文件又加载了你的 SPA 入口逻辑，Router 就能接管并渲染对应路由。不需要改 JS 路由模式，也不用配 base 标签（除非你用了构建工具且输出路径含前缀）。
这个技巧只对纯前端路由有效；如果你依赖后端 API，fetch 地址仍需指向外部服务，GitHub Pages 本身不运行任何服务端代码。
