Skip to content创建
GitHub Pages 托管静态页面
概述
GitHub Pages 将仓库指定分支或目录中的静态资源自动发布为站点，默认绑定 *.github.io 域名。整个过程不需额外配置服务器，HTTPS 证书由平台自动生成并续期。
基本概念
仓库的静态文件可以取自两个位置：分支根目录，或分支下的 docs/ 目录。在仓库设置中选定分支和目录后，该分支的每次推送都会触发构建或直接发布，站点随之更新。
域名分配遵循两条规则：
- 仓库名为
<username>.github.io时，站点部署至https://<username>.github.io/ - 其他仓库部署至
https://<username>.github.io/<repo>/
仓库可见性影响部署的默认限制：公开仓库免费使用；私有仓库需要 GitHub Free 以外的计划（如 GitHub Pro）。即使源代码存放在私有仓库中，生成的 Pages 站点本身始终公开可访问。
工作原理
在仓库设置中启用 Pages 后，平台按以下流程处理仓库内容：
- 检查仓库根目录是否存在
.nojekyll文件。 - 若不存在
.nojekyll且仓库内存在 Jekyll 配置文件（_config.yml），则执行 Jekyll 构建。 - 构建产物（或原始静态文件）被部署到站点。
Jekyll 是内置的静态站点生成器，将 Markdown 和模板编译为 HTML。对于不使用 Jekyll 的项目，在仓库根目录放置一个空的 .nojekyll 文件即可跳过构建步骤，直接发布已有的 HTML/CSS/JavaScript 文件。
如果项目需要自己的构建流程（例如 Vite、VuePress、Webpack），通常会通过 GitHub Actions 自定义构建，将输出推送到 gh-pages 等分支，再由 Pages 直接发布该分支。
基本用法
手动部署一个 HTML 站点
假设有一个仅包含 index.html 的项目，可通过以下步骤完成部署：
bash
mkdir my-site
cd my-site
echo '<h1>Hello Pages</h1>' > index.html
git init
git add index.html
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/<username>/my-site.git
git push -u origin main在 GitHub 仓库页面进入 Settings → Pages，将 Source 设置为 Deploy from a branch，选择 main 分支与 / (root) 目录，点击 Save。几分钟后站点在 https://<username>.github.io/my-site/ 可用。
设置页面会显示部署状态与站点实际 URL。如果长时间停留在 “Your site is ready to be published”，应先检查分支名是否正确，以及是否已创建 .nojekyll 文件（纯静态站点建议添加）。
使用 Jekyll 构建
在仓库中创建 _config.yml 和至少一个 index.md，Pages 将自动执行 Jekyll 构建：
yaml
# _config.yml
title: My Jekyll Site
description: 使用 GitHub Pages 自动构建的站点markdown
---
layout: default
---
# 首页
这是一个 Jekyll 生成的页面。推送后，Pages 会执行 jekyll build 并将 _site 目录发布。构建日志可在仓库的 Actions 标签页查看（Jekyll 构建也会产生工作流记录）。构建失败时，通常会收到邮件通知，或 Actions 页面中显示错误信息。
使用 GitHub Actions 自定义构建
对于非 Jekyll 项目，常见的做法是通过 Actions 构建并部署。以下工作流使用 peaceiris/actions-gh-pages 将构建输出推送到 gh-pages 分支：
yaml
# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v2
with:
version: 8
- run: pnpm install --frozen-lockfile
- run: pnpm build
- uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist推送后进入仓库 Settings → Pages，将 Source 改为 Deploy from a branch，分支选择 gh-pages，目录选 / (root)。工作流每次在 main 分支推送后执行，将 ./dist 同步到 gh-pages 分支，Pages 从该分支发布。
将源代码和构建产物放在不同分支，可以避免站点目录与源码混合，同时保留完整的构建历史。
命令/API
创建 .nojekyll 文件
在仓库根目录创建空文件：
bash
touch .nojekyll
git add .nojekyll
git commit -m "Disable Jekyll processing"
git push该文件通知 Pages 跳过 Jekyll 构建，适用于纯 HTML 或其他构建工具生成的项目。
自定义域名设置
如需将域名 www.example.com 指向 Pages，先在 DNS 提供商处添加 CNAME 记录，将 www 指向 <username>.github.io。然后在 Pages 设置的 Custom domain 文本框中填入 www.example.com，保存。
对于 apex 域名（如 example.com），不支持 CNAME，需添加 A 记录指向 GitHub Pages 的 IP 地址。当前（编写时）GitHub 文档列出的 IP 为：
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153实际生效的 IP 以 GitHub Pages 文档 为准。添加 IP 后，在 Pages 设置中填写 example.com 并保存。GitHub 会自动获取 Let's Encrypt 证书，勾选 Enforce HTTPS 后所有 HTTP 请求将被重定向至 HTTPS。
使用 dig 验证 DNS 是否生效：
bash
dig www.example.com CNAME +short
# <username>.github.io.bash
dig example.com +short
# 返回上述 A 记录 IP 之一示例
完整站点构建输出
部署一个 VuePress 项目后，终端输出和站点结构大致如下：
bash
$ pnpm build
> vuepress-starter@ build /home/runner/work/vuepress-starter
> vuepress build src
✔ Build succeeded.
Rendering pages: done in 3.2s.
Output directory: src/.vuepress/dist此时 dist 目录的内容为：
dist/
├── 404.html
├── index.html
├── assets
│ └── style.css
└── guide
└── index.htmlActions 将 dist 推送到 gh-pages 分支后，站点即可访问。VuePress 构建的输出中包含路由对应的 HTML 文件以及静态资源，Pages 直接从分支发布这些文件。
自定义域名配置后的行为
设置 www.example.com 后，Pages 会在仓库根目录自动生成 CNAME 文件，内容为 www.example.com。该文件不应手动删除，否则自定义域名绑定会丢失。如果使用 gh-pages 分支发布，部署时必须保留此文件，不然每次部署会清除自定义域名设置。
证书申请延迟的常见情形：DNS 记录尚未生效，或当域名使用 Cloudflare 代理（橙色云朵）时，Let's Encrypt 的验证可能失败。临时将 Cloudflare 代理切换为仅 DNS，等待证书生成后再开启，是常用的处理方式。
注意点
- 带宽超限：站点月带宽为 100GB。超出限额后 GitHub 通常会发送邮件警告，并可能暂停 Pages 服务。对于流量波动大或静态资源体积庞大的站点，常见方案是在前面增加 CDN（如 Cloudflare）以降低回源流量。
- 构建次数：通过分支部署（内置 Jekyll 构建）的站点，每小时最多触发 10 次构建。频繁推送会导致构建排队，超出后在 Actions 日志中会显示取消记录。如果使用 GitHub Actions 构建，这一构建次数限制针对 Actions 运行，与分支部署的构建限制分开计算，但 Actions 自身也有使用限制。无论哪种方式，调整工作流使其仅在需要时触发（例如正式发布）可规避排队问题。
- 仓库与站点大小：仓库总大小（含 Git 历史）建议不超过 1GB；构建后的站点大小不超过 1GB。大型二进制文件（如图片、视频）不应直接放入仓库，应使用外部存储。
- 私有仓库站点：虽然源码在私有仓库中，站点一经发布即公开。GitHub Pages 自身不提供访问认证机制。
- GitHub Actions 环境约束：GitHub Actions 提供的运行环境是临时的容器，构建任务结束后立即销毁，无法保持持续运行的进程（如 Ruby 服务器）。试图在 Actions 中启动后台服务并期望其跨步骤存活是无效的。
限制
基础限制汇总：
| 限制项 | 数值 |
|---|---|
| 仓库大小 | 1GB（含 Git 历史） |
| 站点构建产物大小 | 1GB |
| 月带宽 | 100GB |
| 每小时构建次数（分支部署） | 10 次 |
与 Vercel、Netlify 等平台相比，GitHub Pages 不提供 Serverless Functions 支持和预览部署（PR 预览）功能，所有逻辑必须在构建阶段完成。
应用
GitHub Pages 适合以下几种场景：
- 个人或项目文档站点：VuePress、VitePress、Docusaurus 等静态站点生成器的输出可直接发布，无需后端。
- 前端演示页面：仅由 HTML/CSS/JavaScript 构成的 Demo，通过一次推送即可部署。
- Jekyll 博客：无需本地安装 Jekyll，在 GitHub 上编辑 Markdown 后自动构建发布。
由于平台不提供动态接口，涉及数据库查询、用户认证或服务端计算的功能不适用于 Pages。这类需求通常需要搭配 BaaS 服务或迁移至支持函数的平台。