GitHub Pages 教程：免费托管网站，分步发布你的第一个页面

GitHub Pages 是什么

GitHub Pages 是内置于 GitHub 的免费静态网站托管服务。你把网站文件保存在普通的 Git 仓库中，GitHub 通过 HTTPS 直接提供这些文件。每次向目标分支执行 git push，网站都会随之更新，因此无需单独的 FTP、托管面板或手动上传文件。

关于这项服务，人们有很多不同的说法，例如「GitHub Pages」「github pages 教程」「github 免费托管」。也有人搜索「git pages 是什么」，但正确的名称是 GitHub Pages：它是 GitHub 平台的功能，而不是 Git 本身。Git 不发布任何内容，它只保存修改的历史。

GitHub Pages 最常用于项目文档、个人主页和作品集、博客、落地页、学习项目，以及用 React、Vue 或 Svelte 构建后的前端演示应用。

Git pages：面向静态内容的托管

关键词是「静态」。GitHub Pages 把已经生成好的文件（HTML、CSS、JavaScript、图片、字体、JSON）交给浏览器。它不会在服务器端执行代码：PHP、Python、服务器端 Node.js 和数据库都无法在这里运行。如果网站需要注册、购物车或带数据库的后台，就需要普通的虚拟主机或云平台。

不过，浏览器中的 JavaScript 照常运行。单页应用可以访问外部 API，表单可以通过第三方服务提交，站内搜索也可以在客户端完成。

GitHub Pages 有哪些类型的网站

GitHub Pages 有三种类型的站点，网站地址取决于类型。

每个账号只能有一个用户站点或组织站点，但项目站点可以有多个，每个仓库一个。个人站点的仓库名必须与你的 GitHub 用户名完全一致：如果用户名是 ivan-petrov，仓库就叫 ivan-petrov.github.io。

公开仓库的 Pages 在免费套餐中可用。从私有仓库发布网站需要 GitHub 的付费套餐；但即使如此，已发布的网站仍然对所有人公开可见。

分步发布网站：GitHub Pages 教程

我们从最简单的方式开始：现成的 HTML 文件，从分支发布。你需要一个 GitHub 账号和已安装的 Git。

第 1 步：创建仓库

在 GitHub 上新建一个公开仓库。个人站点命名为 username.github.io，项目站点可以任意命名。然后克隆仓库，并添加首页：

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>你好，GitHub Pages</h1>" > index.html

首页必须命名为 index.html（或 index.md、README.md，GitHub 同样会把它们转换成首页）。大小写很重要：Index.html 不起作用。

第 2 步：把文件推送到 GitHub

git add index.html
git commit -m "第一个网页"
git push origin main

如果你第一次推送时 Git 要求输入用户名和密码，请使用个人访问令牌或浏览器登录：普通的 GitHub 账号密码不能用于 HTTPS 方式的 git push。

第 3 步：在设置中开启 Pages

打开 GitHub 上的仓库，进入 Settings，在左侧菜单中选择 Pages。在 Build and deployment 部分的 Source 中选择 Deploy from a branch。然后指定分支（通常是 main）和文件夹：根目录 / (root) 或 /docs。点击 Save。

当仓库中既有项目代码，又有单独的文档网站目录时，/docs 文件夹很方便。

第 4 步：等待发布完成

发布通常需要几秒到几分钟；GitHub 提示首次发布可能需要最多 10 分钟。构建过程可以在 Actions 标签页中查看，那里会出现 pages build and deployment 任务。任务完成并显示绿色对勾后，Settings → Pages 中会出现网站地址。

之后的流程很简单：修改文件，提交，然后 git push，网站就会自动更新。

通过 GitHub Actions 发布

当仓库中已经是现成的文件时，从分支发布很合适。但如果网站需要先构建，例如基于 Vite、React 的应用，或 Hugo 之类的生成器，那么使用 GitHub Actions 作为来源更方便。在 Settings → Pages 的 Source 中选择 GitHub Actions，GitHub 会提供现成的 workflow 模板。

对于构建后位于 dist 文件夹中的静态文件，最简单的 workflow 如下：

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

该文件保存在 .github/workflows/pages.yml 中。执行 git push 后，Actions 会安装依赖、构建项目，并发布 dist 的内容。这种方式的好处是：仓库中只保存源代码，构建产物不会占满提交历史。

项目站点常见的陷阱是路径。网站地址是 /仓库名/，而构建工具默认引用的资源是从根路径 / 开始的。结果页面加载时没有样式和脚本。解决办法是设置基础路径：在 Vite 中使用 base: '/仓库名/'，其他构建工具中也有类似的选项。

Jekyll 与静态网站生成器

从分支发布时，GitHub 默认会用 Jekyll 处理文件。Jekyll 是基于 Ruby 的静态网站生成器。因此你可以用 Markdown 编写页面，使用主题和模板，GitHub 会自动把它们转换为 HTML。对于博客或文档来说，这很方便：你写 .md 文件，样式由主题决定。

副作用是：Jekyll 会忽略名称以下划线开头的文件和文件夹，例如 _next 或 _assets。如果你的网站是用其他工具构建的，并且需要这些文件夹，可以在根目录放一个空的 .nojekyll 文件：

touch .nojekyll
git add .nojekyll
git commit -m "关闭 Jekyll"
git push

Hugo、Astro、Eleventy、MkDocs、Docusaurus 等其他生成器通常通过 GitHub Actions 工作：在 workflow 中构建，再发布生成好的文件夹。GitHub Pages 本身并不关心这些工具，它只需要最终的文件。

如何绑定自定义域名

username.github.io 适合学习项目，但对于作品集或正式项目，最好使用自己的域名。绑定需要在两个地方完成：域名注册商和仓库设置。

配置 DNS

对于 www.example.com 或 blog.example.com 之类的子域名，创建一条指向 username.github.io 的 CNAME 记录。对于根域名 example.com，则需要创建指向 GitHub Pages IP 地址的 A 记录：

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

最新的地址列表（包括用于 AAAA 记录的 IPv6 地址）可以在 GitHub 文档中查看，设置前请以文档为准。建议同时配置根域名和 www：这样 GitHub 会把其中一个地址重定向到另一个。

在仓库中设置

在 Settings → Pages 的 Custom domain 中填入域名并保存。从分支发布时，GitHub 会在仓库中创建一个名为 CNAME 的文件，内容就是域名。若通过 Actions 发布，则不需要 CNAME 文件，域名保存在设置中。

GitHub 建议在账号设置的 Pages 部分验证你的域名：这样可以防止他人在你的 DNS 仍指向 GitHub 时，把你的域名绑定到他们自己的仓库上。DNS 的修改最长可能需要一天才能生效，如果域名没有立即生效，请耐心等待。

GitHub Pages 的 HTTPS

对于 *.github.io 地址，HTTPS 始终开启。对于自定义域名，DNS 配置正确后，GitHub 会自动签发 Let's Encrypt 证书。之后，Settings → Pages 中会出现 Enforce HTTPS 复选框，勾选它即可把所有 HTTP 请求重定向到 HTTPS。

如果复选框不可用，说明证书尚未签发：检查 DNS 记录并等待。有时把域名从 Custom domain 中删除再重新添加，可以触发重新签发证书。另外，请确认网站没有通过 http:// 加载图片和脚本：浏览器会把这些资源当作混合内容拦截。

GitHub Pages 的限制

托管是免费的，但有明确的边界。这些限制写在 GitHub 的文档中，对于大多数个人和学习网站来说，它们绰绰有余。

除了技术限制，还有使用规则：GitHub Pages 不适用于网上商店、SaaS 等商业服务，也不适合分发大文件。作品集、文档、博客和项目落地页则完全没问题。

另一个限制是没有服务器端配置：你无法设置自定义重定向、响应头或 .htaccess 之类的规则。唯一能做的是在根目录放一个自定义的 404.html 页面，GitHub 会在地址不存在时显示它。

常见问题及解决方法

GitHub Pages 出现 404 错误

最常见的原因是：在所选的源文件夹中没有 index.html。请检查选择的分支和文件夹（/ (root) 或 /docs），并确认文件名正好是小写的 index.html。第二个原因是网站还没有发布完成：请到 Actions 标签页等待构建结束。

如果单页应用在刷新内部页面时出现 404，问题出在路由上：服务器找不到 /about，因为并没有这个文件。可行的解决办法是使用 hash 路由（/#/about），或者复制一份 index.html 命名为 404.html。

网站没有更新

首先确认修改确实已经到达 GitHub：执行 git status 和 git log origin/main --oneline -3。然后打开 Actions 标签页：如果构建失败，会出现红色叉号和错误日志，例如 Jekyll 文件的语法错误，或 workflow 中的错误。

如果构建成功，而浏览器中仍是旧版本，那么是缓存的问题。GitHub Pages 会缓存文件几分钟，浏览器也会缓存。可以使用强制刷新（Ctrl+F5 或 Cmd+Shift+R），或在无痕窗口中打开。

样式和图片无法加载

几乎都是路径错误。在项目站点中，链接 /style.css 指向的是 username.github.io 的根目录，而不是仓库的文件夹。请使用相对路径（style.css、./img/logo.png），或在构建工具中设置基础路径。另外请检查文件名的大小写：GitHub 的服务器区分 Logo.PNG 和 logo.png，即使在 Windows 本地它们是相同的。

以下划线开头的文件夹消失了

这是 Jekyll 的行为：它不会发布像 _app 这样的目录。可以在根目录添加 .nojekyll 文件，或者改用 GitHub Actions 发布。

总结

GitHub Pages 是免费发布静态网站最快的方法：一个仓库，一个 index.html，在 Settings → Pages 中选择来源，几分钟后网站就会在 username.github.io 上线。对于需要构建的网站，使用 GitHub Actions；绑定自定义域名则需要配置 DNS 记录并勾选 Enforce HTTPS。同时要注意它的边界：只支持静态内容，没有服务器端代码，并且对大小和流量有限制。GitHub 的工作方式、推送修改和自动化，在本课程的 Git 实践中都有详细讲解。