用 GitHub Pages 发布网站：从提交到上线的完整指南

【免费下载链接】github-pagesCreate a site or blog from your GitHub repositories with GitHub Pages.项目地址: https://gitcode.com/GitHub_Trending/gi/github-pages

需要公网地址的那一刻

小游戏 demo 写好了，你想把链接发给朋友，手里却只有一个本地文件。自建服务器要注册、部署、维护证书，为一个演示页付出这些成本并不划算。GitHub Pages 就是这种场景下拿到公网访问地址的最省事的办法：不用买服务器，提交即上线。

GitHub Pages 能替代什么

一句话说清定位：GitHub Pages 是 GitHub 平台自带的静态站点托管服务，替代「服务器 + HTTPS 证书」这套组合，你的仓库内容直接变成网站。它不替代后端服务：没有数据库，不能跑服务端代码，项目如果依赖实时接口，仍需要单独的服务器或 Serverless。访问地址由平台生成，个人账户形如username.github.io/仓库名，无需购买域名。

核心原理速览

发布分支即站点

你在仓库设置里指定一个分支（通常是 main 或 gh-pages），平台就把该分支内容原样发布。链路是：你 commit → 平台检测到变更 → 重新发布。commit 动作本身就是部署触发点，没有额外的构建环节。

CDN 与 HTTPS 默认开启

发布后静态资源缓存在 CDN 边缘节点，不同地区的访问者都走短路径加载。所有站点默认带 HTTPS，证书由平台统一申请和续期，你不用碰。

每个 commit 都是一份版本快照

站点内容等价于仓库的快照。新版本出了 bug，把分支回退到上一个提交，Pages 会按恢复后的内容重新发布。线上回滚的成本约等于执行一条 git 命令。

实操步骤

第一档：最小闭环

先用 main 分支跑通最短路径。克隆模板仓库，把内容换成你自己的：

git clone https://gitcode.com/GitHub_Trending/gi/github-pages YOUR_SITE cd YOUR_SITE git add . && git commit -m "init site" && git push

把index.html和 JS、CSS 资源放进仓库根目录，推送后到仓库设置的 Pages 项里选择 main 分支和 / 根目录作为发布源，几分钟内就能拿到可访问的站点。练习流程可参考 README.md。

第二档：绑定自定义域名

有自有域名时，在仓库根目录放一个 CNAME 文件：

echo "game.example.com" > CNAME git add CNAME && git commit -m "bind domain" && git push

再到域名服务商处添加一条 CNAME 记录，指向站点地址。DNS 生效后站点切换到你的域名，HTTPS 证书为新域名自动签发。

第三档：构建产物分离

带构建步骤的项目，源码不要直接推到线上分支。用 gh-pages 包把 dist 产物推到独立的 gh-pages 分支，main 的日常迭代就不影响线上站点：

npx gh-pages -d dist -b gh-pages

项目已有 CI 流水线的话，把这条命令放进去，push 后从构建到发布全自动完成。

高频问题排查

1. 推送后站点不更新→ 根因通常是 Pages 发布源指向了另一个分支。修复：到仓库设置的 Pages 项，把源改成你实际提交的分支。
2. 首次访问 404→ 构建发布需要 1~3 分钟，地址本身没有问题。修复：稍等几分钟查看部署日志，同时确认index.html位于发布源根目录，而不是子目录里。
3. 图片、音频 404→ 根因是 HTML 里用了绝对路径。修复：把资源引用改成./js/game.js这类相对路径，并确认资源文件已随代码提交。
4. 自定义域名无法访问→ 通常是 CNAME 文件与 DNS 记录不一致。修复：核对仓库根目录 CNAME 文件里写的域名和 DNS 记录一致，等待 DNS 生效，一般不超过 48 小时。

生态衔接

npm 生态的 gh-pages 包就是为此场景设计的：一条命令把本地 dist 推到 gh-pages 分支，可以写进 package.json 的 scripts 随构建一起执行。Jekyll 这类静态站点生成器也能直接配合 Pages 使用，本仓库的练习正是围绕用 Jekyll 建站展开的。GitHub Actions 这类 CI 服务则能接管部署环节，push 后自动发布，全程记录在仓库日志里。

下一步做什么

GitHub Pages 把静态页面的发布成本压到一次 commit 的水平：代码由你维护，分发、HTTPS 与回滚交给平台。下一步先让index.html的最小版本跑通 main 分支链路，再考虑加域名。

【免费下载链接】github-pagesCreate a site or blog from your GitHub repositories with GitHub Pages.项目地址: https://gitcode.com/GitHub_Trending/gi/github-pages