GitHub Pages 能直接发布纯 HTML5 网页，不需要构建工具、不需要后端，但必须注意仓库命名、分支选择和路径结构这三点，否则页面 404 或样式/脚本加载失败。
仓库名必须是 username.github.io
这是唯一能启用「用户主页」模式的命名规则。如果建的是普通仓库（比如叫 my-app），默认只能用 gh-pages 分支或 docs 文件夹，且访问地址会多一级路径（https://username.github.io/my-app/），这时所有相对路径（如 ./css/style.css）容易出错。
- 新建仓库时名称严格写成
your-github-username.github.io（用户名全小写，不能有下划线或数字开头） - 这个仓库只能放一个网站，所有文件放在根目录，
index.html是首页入口 - 如果已有其他项目想单独部署，改用项目页模式（见下一条）
项目页模式：用 gh-pages 分支或 docs 文件夹
适合把 HTML5 页面作为某个项目的演示页，比如你有个 React 小游戏，想附带一个可玩的在线 demo。这时不强制要求仓库名匹配，但得明确指定源。
- 进仓库 Settings → Pages → Source，选
gh-pages branch（推荐）或main branch /docs folder - 如果选
gh-pages分支，把所有 HTML/CSS/JS 文件（包括index.html）推送到该分支根目录 - 如果选
/docs，就把整个站点文件放进docs/子目录，GitHub 会自动从这里读取 - 访问地址变成
https://username.github.io/repo-name/，注意末尾有斜杠——所有资源路径要按此层级调整，例如图片引用得写成./images/icon.png而不是/images/icon.png
index.html 里别用绝对路径引用本地资源
GitHub Pages 是静态托管，不支持服务端重写，所以路径写错会导致 CSS、JS、图片全部 404。常见错误是开头加了 /，比如 <link rel="stylesheet" href="/css/main.css">，这会让浏览器去根域名下找，而项目页模式下实际根是 /repo-name/。
立即学习“前端免费学习笔记（深入）”；
- 一律用相对路径：
./css/main.css、../js/app.js、images/logo.svg - 如果必须用绝对路径（比如 SEO 或 PWA 需求），通过
<base href="/repo-name/">声明基准 URL（仅限项目页模式），然后所有路径按此基准写 - 检查浏览器开发者工具 Console 和 Network 标签页，看是否有 404 请求，快速定位路径问题
HTML5 本身无需特殊配置，但注意 MIME 类型和缓存
GitHub Pages 自动设置正确的 Content-Type（如 text/html; charset=utf-8），但某些自定义文件类型（比如 .glb 3D 模型、.webp 图片）可能被识别为 application/octet-stream，导致浏览器无法正确加载。
- 确保文件扩展名标准（
.webp、.glb、.json都支持，但.gltf可能被误判） - 如果发现模型/字体加载失败，检查 Network 面板 Response Headers 中的
Content-Type，不对就换扩展名（比如.gltf改成.json）或用 Base64 内联 - GitHub Pages 默认开启强缓存，修改文件后可能仍加载旧版，可临时在链接后加查询参数调试，如
style.css?v=2
最容易被忽略的是路径层级和 base 标签配合问题——项目页模式下，漏掉 <base> 又用绝对路径，或者写了 <base> 却没同步改所有资源引用，结果页面白屏却查不出原因。
