GitHub Pages 上手指南：从空仓库到自定义域名

GitHub Pages 大概是对个人博客最友好的托管方式：免费、自带 HTTPS、可以直接挂自定义域名。但它也有几个容易绊人的细节，这篇就把整个流程从头到尾理一遍。

先分清两种站点#

GitHub Pages 有两种形态，选错了会在资源路径上浪费一个下午。

个人博客推荐用用户站：一个账号只能有一个，地址短，也不用处理子路径。如果想让多个项目各自有站点，再用项目站。

三步上线#

1. 在 GitHub 上新建仓库。用户站必须叫 <username>.github.io。
2. 把站点文件推送到 main 分支。
3. 打开仓库的 Settings → Pages，把 Source 设为 GitHub Actions。

如果你只是想先看看效果，也可以选择 “Deploy from a branch”，把分支设为 main、目录设为 / (root)。但这样一来，dist/ 必须提交进仓库，构建产物和源文件混在一起，不太优雅。推荐往下看。

用 Actions 自动部署#

在仓库里放一个 .github/workflows/deploy.yml：

name: Deploy blog

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python build.py
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

这份配置做三件事：检出代码、用 Python 跑构建脚本、把 dist/ 作为 Pages 产物发布。permissions 和 environment 是必须的，少了会在部署阶段报权限错误。

推送之后，Actions 页面会出现一次运行记录。第一次通常要一两分钟，之后增量构建会快很多。

自定义域名#

在仓库的 Settings → Pages → Custom domain 填入域名，然后去域名服务商处添加解析：

等 DNS 生效后，勾选 Enforce HTTPS。证书一般几分钟内签发，偶尔要等上半小时。如果一直卡在 “Certificate is being provisioned”，先把自定义域名删掉再重新添加一次，通常就好了。

还有一点：在站点根目录放一个 CNAME 文件，内容是域名本身。我这个项目里，只要在 site.config.json 的 customDomain 填上域名，构建时就会自动生成。

几个常见的坑#

• Jekyll 把下划线目录吃掉了。 Pages 默认会跑一遍 Jekyll，以下划线开头的文件夹会被忽略。放一个空的 .nojekyll 文件即可。
• 项目站的资源 404。 因为页面在 /repo/ 下，/assets/style.css 会指向域名根目录。所有站内链接都要带上 base 前缀。
• 文件名大小写。 本地是 Windows 或 macOS，部署到 Linux 后大小写敏感，Cover.PNG 和 cover.png 是两回事。
• 私有仓库。 公开仓库免费；从私有仓库发布 Pages 需要付费套餐，具体以 GitHub 当前政策为准。

最后#

Pages 不是 CMS，它只负责把一堆静态文件放到网上。真正让博客运转起来的，是“写 → 构建 → 推送”这条简单的流水线。把它搭顺一次，之后就可以专心写字了。

下一篇我会写这个站点具体是怎么组织的，包括那个一千多行的构建脚本。