GitHub Pages 托管 uni-app H5 必须满足：仓库名与 manifest.json 的 name 字段完全一致；路由模式设为 hash；部署到 gh-pages 分支并强制推送；手动在 Settings 中启用 Pages 服务。
GitHub Pages 要求仓库名和 manifest.json 的 name 一致
这不是可选项，是 GitHub Pages 托管 H5 的硬性约束。uni-app 构建出的 H5 是单页应用（SPA），依赖 index.html 根路径加载，而 GitHub Pages 的默认站点根目录就是仓库名对应的子路径（如 https://username.github.io/your-repo-name/）。如果 manifest.json 里的 name 值不是 your-repo-name，H5 内部资源（比如 static/js/app.js）会尝试从根路径 /static/... 加载，但实际被托管在子路径下，404 就必然发生。
操作要点：
- 创建 GitHub 仓库时，名称必须与
manifest.json中的"name": "xxx"字段值完全一致（区分大小写、无空格、仅字母数字和短横线） - 修改后需重新执行构建：
npm run build:h5或通过 HBuilderX「发行 → 网站-H5」 - 不要手动改
unpackage/dist/build/h5/index.html里的git init git add . git commit -m "deploy h5" git remote add origin https://github.com/username/your-repo-name.git git branch -M gh-pages git push -f origin gh-pages<p>注意：</p> <ul> <li> <code>git push -f</code> 是必需的 —— 否则第二次部署会因分支历史不一致而失败</li> <li>如果之前已推过，但页面空白或报 404，大概率是没加 <code>-f</code>，导致旧 HTML 文件还在，但新 JS 文件已被覆盖或缺失</li> <li>确保远程地址中的 <code>username</code> 和 <code>your-repo-name</code> 与 GitHub 实际一致，大小写错误会导致 <code>remote: Repository not found</code> </li> </ul> <h3>H5 路由模式必须设为 <code>hash</code>，否则 GitHub Pages 无法正确响应刷新</h3> <p>uni-app 默认 H5 路由是 <code>history</code> 模式，它依赖服务端对所有路径都返回 <code>index.html</code>。但 GitHub Pages 是纯静态托管，不支持服务端重定向 —— 刷新 <code>/user/123</code> 页面时，会直接 404。</p> <p>解决方式：在 <code>pages.json</code> 顶层显式声明：</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill11058" title="Workspace Git Setup"><img src="https://img.php.cn/upload/skill/001/246/273/6adaf20e695c2374.jpg" alt="Workspace Git Setup" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill11058" title="Workspace Git Setup" class="overflowclass">Workspace Git Setup</a> <p class="overflowclass">一键在任意工作目录中设置 Git 跟踪，并附带安全为重点的 .gitignore（包括凭证、TLS/SSH 私钥、令牌、运行时缓存和 PID 等）</p> </div> <a rel="nofollow" href="/xiazai/skill11058" title="Workspace Git Setup" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div> <pre class="brush:php;toolbar:false;">"h5": { "router": { "mode": "hash", "base": "/" } } 这样所有路由变成
#/user/123，浏览器只做前端跳转，不触发服务端请求，GitHub Pages 完全兼容。常见误操作：
- 只改了
vue-router配置（uni-app 不走原生 vue-router） - 在
manifest.json里配h5.router.mode—— 无效，该字段不存在 - 构建后手动改
index.html引入 router —— 不必要，uni-app 已内置
首次部署后要等几分钟，且必须去 GitHub 仓库 Settings → Pages 手动启用
GitHub 不会自动激活 Pages 功能。即使
gh-pages分支推送成功，访问链接仍显示 404，直到你在仓库设置里手动开启。路径：
Settings → Pages → Branch → gh-pages / (root)→ Save之后 GitHub 会开始构建并部署，状态条可能卡在 “Building” 几分钟。此时刷新页面仍是 404，不是失败，是真正在处理。典型等待时间是 1–3 分钟，最长不超过 10 分钟。
容易忽略的点：
- 未勾选
Enforce HTTPS会导致部分资源（如字体、图片）被浏览器拦截 —— 建议勾上，生效后自动跳转 - 如果用了自定义域名，CNAME 文件必须放在
unpackage/dist/build/h5根目录下，且内容只能是域名（如example.com），不能带协议或路径 - 部署后访问链接格式一定是
https://username.github.io/your-repo-name/，末尾斜杠不能省，否则路由 hash 可能失效
- 只改了
