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

URL: https://skillaria.top/zh/guides/git/github-pages-hosting

GitHub Pages 是 GitHub 提供的免费静态网站托管服务，直接从仓库发布网站。把 HTML、CSS 和 JavaScript 文件放进仓库，在设置中开启 Pages，网站就会以 username.github.io 的地址上线；还可以绑定自定义域名并启用 HTTPS，但不支持 PHP 等服务器端代码和数据库。

## 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 有三种类型的站点，网站地址取决于类型。

| 类型 | 仓库 | 地址 |
| --- | --- | --- |

| 用户站点 | `username.github.io` | `https://username.github.io/` |

| 组织站点 | `orgname.github.io` | `https://orgname.github.io/` |

| 项目站点 | 任意名称，例如 `docs` | `https://username.github.io/docs/` |

每个账号只能有一个用户站点或组织站点，但项目站点可以有多个，每个仓库一个。个人站点的仓库名必须与你的 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 "

# 你好，GitHub Pages

" > 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 的文档中，对于大多数个人和学习网站来说，它们绰绰有余。

| 限制项 | 数值 |
| --- | --- |

| 内容 | 仅限静态文件，不支持服务器端代码和数据库 |

| 已发布网站的大小 | 最大 1 GB |

| 建议的仓库大小 | 最大 1 GB |

| 流量 | 软限制每月 100 GB |

| 从分支构建 | 软限制每小时 10 次（不适用于 Actions） |

| 发布时间 | 超过 10 分钟的部署会被中断 |

除了技术限制，还有使用规则：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 实践中都有详细讲解。

## FAQ

**GitHub Pages 真的免费吗？**

是的。对于公开仓库，免费套餐中的 GitHub Pages 不收取任何费用，包括 HTTPS 和自定义域名。只有域名本身需要向注册商付费，若想从私有仓库发布网站，才需要 GitHub 的付费套餐。

**能在 GitHub Pages 上部署 PHP 或 WordPress 网站吗？**

不能。GitHub Pages 只提供静态文件，不执行服务器端代码。WordPress 网站可以通过插件导出为静态 HTML，但表单、评论和后台将无法工作。

**一个账号可以创建多少个 GitHub Pages 网站？**

一个用户站点（username.github.io），以及不限数量的项目站点，每个仓库一个。

**搜索引擎会收录 GitHub Pages 网站吗？**

会，这些网站和普通网站一样被收录。为了更好地被收录，可以在根目录添加 sitemap.xml 和 robots.txt，并在搜索引擎的站长工具中验证网站。

**如何删除 GitHub Pages 网站？**

在 Settings → Pages 中点击 Unpublish site（如果该按钮可用），或者在 Source 中为分支选择 None。删除仓库也会同时删除网站。


---
Source: Skillaria.Top (https://skillaria.top)