uni-app怎么将打包好的H5部署到GitHub

浅杰吖_3718

发布时间：2026-11-02 06:08:29

324人浏览过

来源于php中文网

原创

GitHub Pages 托管 uni-app H5 必须满足：仓库名与 manifest.json 的 name 字段完全一致；路由模式设为 hash；部署到 gh-pages 分支并强制推送；手动在 Settings 中启用 Pages 服务。

uni-app怎么将打包好的h5部署到github

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 就必然发生。

Workspace Git Setup

一键在任意工作目录中设置 Git 跟踪，并附带安全为重点的 .gitignore（包括凭证、TLS/SSH 私钥、令牌、运行时缓存和 PID 等）

下载

操作要点：

创建 GitHub 仓库时，名称必须与 manifest.json 中的 "name": "xxx" 字段值完全一致（区分大小写、无空格、仅字母数字和短横线）
修改后需重新执行构建：npm run build:h5 或通过 HBuilderX「发行 → 网站-H5」
不要手动改 unpackage/dist/build/h5/index.html 里的 <base href="/>%20%E2%80%94%E2%80%94%20uni-app%20%E9%BB%98%E8%AE%A4%E4%B8%8D%E5%86%99%E8%AF%A5%E6%A0%87%E7%AD%BE%EF%BC%9B%E8%8B%A5%E4%BD%A0%E5%8A%A0%E4%BA%86%EF%BC%8C%E5%8F%8D%E8%80%8C%E4%BC%9A%E7%A0%B4%E5%9D%8F%E8%B7%AF%E7%94%B1%E8%B7%B3%E8%BD%AC

%0A%0A

`git%20push`%20%E5%BF%85%E9%A1%BB%E6%8E%A8%E9%80%81%E5%88%B0%20`gh-pages`%20%E5%88%86%E6%94%AF%EF%BC%8C%E4%B8%94%E7%94%A8%20`-f`%20%E5%BC%BA%E5%88%B6%E8%A6%86%E7%9B%96

%0A

GitHub%20Pages%20%E9%BB%98%E8%AE%A4%E5%8F%AA%E4%BB%8E%20gh-pages%20%E5%88%86%E6%94%AF%E6%8F%90%E4%BE%9B%E9%9D%99%E6%80%81%E6%96%87%E4%BB%B6%E6%9C%8D%E5%8A%A1%EF%BC%8C%E4%B8%8D%E6%98%AF%20main%20%E6%88%96%20master%E3%80%82%E8%80%8C%E4%B8%94%E6%AF%8F%E6%AC%A1%E6%9E%84%E5%BB%BA%E4%BA%A7%E7%89%A9%E9%83%BD%E6%98%AF%E5%85%A8%E6%96%B0%E7%94%9F%E6%88%90%E7%9A%84%EF%BC%8C%E6%97%A7%E6%96%87%E4%BB%B6%E6%AE%8B%E7%95%99%E4%BC%9A%E5%AF%BC%E8%87%B4%20JS/CSS%20%E7%BC%93%E5%AD%98%E9%94%99%E4%B9%B1%E6%88%96%20404%E3%80%82

%0A

%E6%A0%87%E5%87%86%E5%91%BD%E4%BB%A4%E5%BA%8F%E5%88%97%EF%BC%88%E5%9C%A8%20unpackage/dist/build/h5%20%E7%9B%AE%E5%BD%95%E5%86%85%E6%89%A7%E8%A1%8C%EF%BC%89%EF%BC%9A

%0A

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

%0A

%E6%B3%A8%E6%84%8F%EF%BC%9A

%0A

git%20push%20-f%20%E6%98%AF%E5%BF%85%E9%9C%80%E7%9A%84%20%E2%80%94%E2%80%94%20%E5%90%A6%E5%88%99%E7%AC%AC%E4%BA%8C%E6%AC%A1%E9%83%A8%E7%BD%B2%E4%BC%9A%E5%9B%A0%E5%88%86%E6%94%AF%E5%8E%86%E5%8F%B2%E4%B8%8D%E4%B8%80%E8%87%B4%E8%80%8C%E5%A4%B1%E8%B4%A5
%E5%A6%82%E6%9E%9C%E4%B9%8B%E5%89%8D%E5%B7%B2%E6%8E%A8%E8%BF%87%EF%BC%8C%E4%BD%86%E9%A1%B5%E9%9D%A2%E7%A9%BA%E7%99%BD%E6%88%96%E6%8A%A5%20404%EF%BC%8C%E5%A4%A7%E6%A6%82%E7%8E%87%E6%98%AF%E6%B2%A1%E5%8A%A0%20-f%EF%BC%8C%E5%AF%BC%E8%87%B4%E6%97%A7%20HTML%20%E6%96%87%E4%BB%B6%E8%BF%98%E5%9C%A8%EF%BC%8C%E4%BD%86%E6%96%B0%20JS%20%E6%96%87%E4%BB%B6%E5%B7%B2%E8%A2%AB%E8%A6%86%E7%9B%96%E6%88%96%E7%BC%BA%E5%A4%B1
%E7%A1%AE%E4%BF%9D%E8%BF%9C%E7%A8%8B%E5%9C%B0%E5%9D%80%E4%B8%AD%E7%9A%84%20username%20%E5%92%8C%20your-repo-name%20%E4%B8%8E%20GitHub%20%E5%AE%9E%E9%99%85%E4%B8%80%E8%87%B4%EF%BC%8C%E5%A4%A7%E5%B0%8F%E5%86%99%E9%94%99%E8%AF%AF%E4%BC%9A%E5%AF%BC%E8%87%B4%20remote:%20Repository%20not%20found

%0A%0A

H5%20%E8%B7%AF%E7%94%B1%E6%A8%A1%E5%BC%8F%E5%BF%85%E9%A1%BB%E8%AE%BE%E4%B8%BA%20`hash`%EF%BC%8C%E5%90%A6%E5%88%99%20GitHub%20Pages%20%E6%97%A0%E6%B3%95%E6%AD%A3%E7%A1%AE%E5%93%8D%E5%BA%94%E5%88%B7%E6%96%B0

%0A

uni-app%20%E9%BB%98%E8%AE%A4%20H5%20%E8%B7%AF%E7%94%B1%E6%98%AF%20history%20%E6%A8%A1%E5%BC%8F%EF%BC%8C%E5%AE%83%E4%BE%9D%E8%B5%96%E6%9C%8D%E5%8A%A1%E7%AB%AF%E5%AF%B9%E6%89%80%E6%9C%89%E8%B7%AF%E5%BE%84%E9%83%BD%E8%BF%94%E5%9B%9E%20index.html%E3%80%82%E4%BD%86%20GitHub%20Pages%20%E6%98%AF%E7%BA%AF%E9%9D%99%E6%80%81%E6%89%98%E7%AE%A1%EF%BC%8C%E4%B8%8D%E6%94%AF%E6%8C%81%E6%9C%8D%E5%8A%A1%E7%AB%AF%E9%87%8D%E5%AE%9A%E5%90%91%20%E2%80%94%E2%80%94%20%E5%88%B7%E6%96%B0%20/user/123%20%E9%A1%B5%E9%9D%A2%E6%97%B6%EF%BC%8C%E4%BC%9A%E7%9B%B4%E6%8E%A5%20404%E3%80%82

%0A

%E8%A7%A3%E5%86%B3%E6%96%B9%E5%BC%8F%EF%BC%9A%E5%9C%A8%20pages.json%20%E9%A1%B6%E5%B1%82%E6%98%BE%E5%BC%8F%E5%A3%B0%E6%98%8E%EF%BC%9A

%0A

"h5": {
  "router": {
    "mode": "hash",
    "base": "/"
  }
}

%0A

%E8%BF%99%E6%A0%B7%E6%89%80%E6%9C%89%E8%B7%AF%E7%94%B1%E5%8F%98%E6%88%90%20#/user/123%EF%BC%8C%E6%B5%8F%E8%A7%88%E5%99%A8%E5%8F%AA%E5%81%9A%E5%89%8D%E7%AB%AF%E8%B7%B3%E8%BD%AC%EF%BC%8C%E4%B8%8D%E8%A7%A6%E5%8F%91%E6%9C%8D%E5%8A%A1%E7%AB%AF%E8%AF%B7%E6%B1%82%EF%BC%8CGitHub%20Pages%20%E5%AE%8C%E5%85%A8%E5%85%BC%E5%AE%B9%E3%80%82

%0A

%E5%B8%B8%E8%A7%81%E8%AF%AF%E6%93%8D%E4%BD%9C%EF%BC%9A

%0A

%E5%8F%AA%E6%94%B9%E4%BA%86%20vue-router%20%E9%85%8D%E7%BD%AE%EF%BC%88uni-app%20%E4%B8%8D%E8%B5%B0%E5%8E%9F%E7%94%9F%20vue-router%EF%BC%89
%E5%9C%A8%20manifest.json%20%E9%87%8C%E9%85%8D%20h5.router.mode%20%E2%80%94%E2%80%94%20%E6%97%A0%E6%95%88%EF%BC%8C%E8%AF%A5%E5%AD%97%E6%AE%B5%E4%B8%8D%E5%AD%98%E5%9C%A8
%E6%9E%84%E5%BB%BA%E5%90%8E%E6%89%8B%E5%8A%A8%E6%94%B9%20index.html%20%E5%BC%95%E5%85%A5%20router%20%E2%80%94%E2%80%94%20%E4%B8%8D%E5%BF%85%E8%A6%81%EF%BC%8Cuni-app%20%E5%B7%B2%E5%86%85%E7%BD%AE

%0A%0A

%E9%A6%96%E6%AC%A1%E9%83%A8%E7%BD%B2%E5%90%8E%E8%A6%81%E7%AD%89%E5%87%A0%E5%88%86%E9%92%9F%EF%BC%8C%E4%B8%94%E5%BF%85%E9%A1%BB%E5%8E%BB%20GitHub%20%E4%BB%93%E5%BA%93%20Settings%20%E2%86%92%20Pages%20%E6%89%8B%E5%8A%A8%E5%90%AF%E7%94%A8

%0A

GitHub%20%E4%B8%8D%E4%BC%9A%E8%87%AA%E5%8A%A8%E6%BF%80%E6%B4%BB%20Pages%20%E5%8A%9F%E8%83%BD%E3%80%82%E5%8D%B3%E4%BD%BF%20gh-pages%20%E5%88%86%E6%94%AF%E6%8E%A8%E9%80%81%E6%88%90%E5%8A%9F%EF%BC%8C%E8%AE%BF%E9%97%AE%E9%93%BE%E6%8E%A5%E4%BB%8D%E6%98%BE%E7%A4%BA%20404%EF%BC%8C%E7%9B%B4%E5%88%B0%E4%BD%A0%E5%9C%A8%E4%BB%93%E5%BA%93%E8%AE%BE%E7%BD%AE%E9%87%8C%E6%89%8B%E5%8A%A8%E5%BC%80%E5%90%AF%E3%80%82

%0A

%E8%B7%AF%E5%BE%84%EF%BC%9ASettings%20%E2%86%92%20Pages%20%E2%86%92%20Branch%20%E2%86%92%20gh-pages%20/%20(root)%20%E2%86%92%20Save

%0A

%E4%B9%8B%E5%90%8E%20GitHub%20%E4%BC%9A%E5%BC%80%E5%A7%8B%E6%9E%84%E5%BB%BA%E5%B9%B6%E9%83%A8%E7%BD%B2%EF%BC%8C%E7%8A%B6%E6%80%81%E6%9D%A1%E5%8F%AF%E8%83%BD%E5%8D%A1%E5%9C%A8%20%E2%80%9CBuilding%E2%80%9D%20%E5%87%A0%E5%88%86%E9%92%9F%E3%80%82%E6%AD%A4%E6%97%B6%E5%88%B7%E6%96%B0%E9%A1%B5%E9%9D%A2%E4%BB%8D%E6%98%AF%20404%EF%BC%8C%E4%B8%8D%E6%98%AF%E5%A4%B1%E8%B4%A5%EF%BC%8C%E6%98%AF%E7%9C%9F%E6%AD%A3%E5%9C%A8%E5%A4%84%E7%90%86%E3%80%82%E5%85%B8%E5%9E%8B%E7%AD%89%E5%BE%85%E6%97%B6%E9%97%B4%E6%98%AF%201%E2%80%933%20%E5%88%86%E9%92%9F%EF%BC%8C%E6%9C%80%E9%95%BF%E4%B8%8D%E8%B6%85%E8%BF%87%2010%20%E5%88%86%E9%92%9F%E3%80%82

%0A

%E5%AE%B9%E6%98%93%E5%BF%BD%E7%95%A5%E7%9A%84%E7%82%B9%EF%BC%9A

%0A

%E6%9C%AA%E5%8B%BE%E9%80%89%20Enforce%20HTTPS%20%E4%BC%9A%E5%AF%BC%E8%87%B4%E9%83%A8%E5%88%86%E8%B5%84%E6%BA%90%EF%BC%88%E5%A6%82%E5%AD%97%E4%BD%93%E3%80%81%E5%9B%BE%E7%89%87%EF%BC%89%E8%A2%AB%E6%B5%8F%E8%A7%88%E5%99%A8%E6%8B%A6%E6%88%AA%20%E2%80%94%E2%80%94%20%E5%BB%BA%E8%AE%AE%E5%8B%BE%E4%B8%8A%EF%BC%8C%E7%94%9F%E6%95%88%E5%90%8E%E8%87%AA%E5%8A%A8%E8%B7%B3%E8%BD%AC
%E5%A6%82%E6%9E%9C%E7%94%A8%E4%BA%86%E8%87%AA%E5%AE%9A%E4%B9%89%E5%9F%9F%E5%90%8D%EF%BC%8CCNAME%20%E6%96%87%E4%BB%B6%E5%BF%85%E9%A1%BB%E6%94%BE%E5%9C%A8%20unpackage/dist/build/h5%20%E6%A0%B9%E7%9B%AE%E5%BD%95%E4%B8%8B%EF%BC%8C%E4%B8%94%E5%86%85%E5%AE%B9%E5%8F%AA%E8%83%BD%E6%98%AF%E5%9F%9F%E5%90%8D%EF%BC%88%E5%A6%82%20example.com%EF%BC%89%EF%BC%8C%E4%B8%8D%E8%83%BD%E5%B8%A6%E5%8D%8F%E8%AE%AE%E6%88%96%E8%B7%AF%E5%BE%84
%E9%83%A8%E7%BD%B2%E5%90%8E%E8%AE%BF%E9%97%AE%E9%93%BE%E6%8E%A5%E6%A0%BC%E5%BC%8F%E4%B8%80%E5%AE%9A%E6%98%AF%20https://username.github.io/your-repo-name/%EF%BC%8C%E6%9C%AB%E5%B0%BE%E6%96%9C%E6%9D%A0%E4%B8%8D%E8%83%BD%E7%9C%81%EF%BC%8C%E5%90%A6%E5%88%99%E8%B7%AF%E7%94%B1%20hash%20%E5%8F%AF%E8%83%BD%E5%A4%B1%E6%95%88