产品给了一个 UI 设计稿需求，做完后不想只发文件给同事，想给一个在线链接直接打开看？不用买服务器、不用装环境，用 GitHub Pages 免费托管，一行代码都不用写后端。

一、为什么选 GitHub Pages

作为一个前端/产品经理/设计师，你经常会有这些场景：

• 做了一个 HTML 原型想分享给团队看效果
• 写了个人主页想让外网能访问
• 项目文档想做成在线文档站

传统做法：买域名 → 买服务器 → 配置 Nginx → 部署。一套下来几百块起步，折腾半天。

GitHub Pages 完全免费，提供 1GB 存储空间 + 每月 100GB 流量，自动 HTTPS，自带全球 CDN，还支持绑定自定义域名。对于纯静态页面（HTML/CSS/JS），它是最省事的方案。

二、前置准备

1. 一个 GitHub 账号：https://github.com 注册即可
2. 你的 HTML 文件：确保是自包含的单个文件（或包含 HTML/CSS/JS 的文件夹）

注意：GitHub Pages 只支持静态资源，不能运行 Node.js、PHP、Python 等后端代码。纯前端页面完全没问题。

三、创建仓库

1. 登录 GitHub，点击右上角 + → New repository，或直接访问 https://github.com/new

2. 填写仓库信息：

   • Repository name：取个名字，比如 ui-mockup-demo
   • Description（可选）：填写说明
   • 选择 Public（免费用户必须公开才能用 Pages）
   • 勾选 ✅ Add a README file
   • 点击 Create repository

四、上传 HTML 文件

有两种方式，任选其一。

方式一：网页直接上传（推荐新手）

1. 进入刚创建的仓库页面
2. 点击 Add file → Upload files
3. 把你的 HTML 文件拖进去或点选择文件
4. 关键步骤：把文件名改为 index.html

⚠️ 必须命名为 index.html！GitHub Pages 默认访问根路径时会自动寻找 index.html 文件。如果你的文件叫 demo.html，访问链接会变成 https://用户名.github.io/仓库名/demo.html，容易让人困惑。

5. 在 Commit message 写一句说明，点 Commit changes

方式二：Git 命令行推送

# 克隆仓库到本地
git clone https://github.com/你的用户名/仓库名.git
cd 仓库名

# 把 HTML 文件复制进来并重命名为 index.html
# 然后推送
git add index.html
git commit -m "deploy: add HTML page"
git push origin main

五、开启 GitHub Pages

1. 进入仓库 → 点击顶部 Settings（设置）
2. 左侧菜单找到 Pages（在 Code and automation 分类下）
3. Source 选择：Deploy from a branch
4. Branch 选择：main（或你的默认分支）
5. 文件夹 选择：/（root）
6. 点击 Save

保存后，页面顶部会显示：

Your site is live at https://你的用户名.github.io/仓库名/

六、等待部署完成

GitHub 需要 1-3 分钟来构建和部署。期间访问链接可能显示 404，耐心等待即可。

部署成功后，点击生成的链接就能看到你的页面了。

七、常见问题排查

问题 1：打开页面显示 README 内容而不是 HTML

原因：文件名不是 index.html。

解决：把 HTML 文件重命名为 index.html，Commit 后等几分钟刷新。

问题 2：页面样式乱了 / 字体不显示

原因：HTML 中引用了 Google Fonts（fonts.googleapis.com），在国内被墙，无法加载。

解决：把 Google Fonts CDN 替换为国内镜像源。比如：

/* 原来（国内无法访问） */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@300;400;500;600;700&display=swap');

/* 改为国内镜像（fonts.loli.net） */
@import url('https://fonts.loli.net/css2?family=Noto+Sans+SC:wght@300;400;500;600;700&display=swap');

或者干脆不用 web font，直接用系统字体：

body {
  font-family: -apple-system, BlinkMacSystemFont, "Microsoft YaHei", sans-serif;
}

问题 3：修改了 HTML 但线上没更新

原因：浏览器缓存 或 GitHub Pages CDN 缓存。

解决：

• 浏览器强制刷新：Ctrl + Shift + R（Mac: Cmd + Shift + R）
• 或无痕模式打开：Ctrl + Shift + N

问题 4：Pages 选项在 Settings 里找不到

原因：仓库是 Private（私有） 的。

解决：免费用户只能对 Public 仓库开启 Pages。要么把仓库设为公开，要么升级到 GitHub Pro。

八、进阶用法

绑定自定义域名

如果你有自己的域名（比如 docs.yourcompany.com）：

1. 在 Pages 设置页面，Custom domain 填入你的域名
2. 在你的域名 DNS 管理中，添加 CNAME 记录指向 你的用户名.github.io
3. 等待 DNS 生效即可

批量文件部署

如果你有多个 HTML 页面、CSS、JS、图片等：

1. 把它们放在同一个文件夹里
2. 确保入口文件是 index.html
3. 全部上传到仓库根目录（或一个子目录）
4. 相对路径引用即可正常访问

配合前端框架

Vue / React / Angular 打包后的 dist 目录也可以直接部署到 GitHub Pages，只需要把构建产物推上去就行。

九、总结

项目	说明
成本	完全免费
存储空间	仓库上限 1GB
月流量	100GB
HTTPS	自动启用
自定义域名	支持
适用场景	静态页面、个人博客、项目文档、UI 原型
不适用场景	需要后端、数据库、动态渲染的应用

对于 UI 设计稿分享、个人作品集、产品原型演示，GitHub Pages 是目前最省心、最省钱的方案。不用买服务器、不用配环境，一个 HTML 文件就能搞定。

---

如果你也用过 GitHub Pages，欢迎在评论区分享你的经验和技巧 👇