使用 GitHub Pages 部署 React 项目并绑定域名

2023-07-14 21:37:19

最近写一个项目用到了 create-react-app，项目最终部署到 GitHub Pages 并绑定了子域名。过程中踩了一些坑————不乏曾经踩过几遍的————遂在这篇博客里记录下来，for future reference。如果能对其他人有所帮助，那就更好了。

本文的主要内容是如何使用 GitHub Pages 部署 React 项目并绑定域名。

部署 React 项目到 GitHub Pages

GitHub Pages 的原理很简单，就是将你的项目文件托管到 GitHub 上，然后 GitHub 会自动为你生成一个网站。默认情况下，可以通过 https://<username>.github.io/<repository-name> 来访问这个网站，也支持绑定其他域名。

GitHub Pages 支持两种部署方式：

Deploy from a branch：从指定分支部署。这种方式适合于你的页面静态文件已经构建好了，只需要将构建好的文件部署到 GitHub Pages 上。这种方式的缺点是，每次更新页面内容都需要手动构建一次，然后 push 到指定分支上。
使用 GitHub Actions：通过 GitHub Actions 自动构建和部署。这种方式适合于你的页面内容是动态生成的，比如使用了 React、Vue 等框架，或者使用了一些静态网站生成器，比如 Jekyll、Hugo 等。这种方式的优点是，只要你的代码有更新，GitHub Actions 就会自动构建和部署，无需手动操作。

由于我要部署的是 React 项目，并且希望能自动构建，所以选择了第二种方式使用 GitHub Actions。下面介绍如何使用 GitHub Actions 来自动构建和部署 React 项目。

在仓库的设置里找到 Pages 选项卡，在 Build and deployment 的 Source 下拉框中选择 GitHub Actions。点击 create your own 后，页面会跳转到一个 workflow 创建页。

在 workflow 中粘贴如下内容，将文件命名为 deploy.yml，然后点击 Commit changes 保存文件。

此处大致照搬了一位日本开发者的 workflow，只在几处做了微调。
注意检查注释部分，并根据你的项目情况修改。

这个 workflow 共有 2 个 job：Build 和 Deploy。

name: Deploy GitHub Pages

on:
  push:
    branches: ['main'] # 如果你的默认分支不是 main，请修改这里
  workflow_dispatch:

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

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

jobs:
  build:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install dependencies
        run: |
          # 如果你的项目文件不在根目录，需要先 cd 到项目目录
          # cd website
          npm install
      - name: Build
        run: |
          # 如果你的项目文件不在根目录，需要先 cd 到项目目录
          # cd website
          npm ci && CI=false npm run build
        env:
          # 如果你的 URL 从根目录开始，则设置为 /，否则设置为你的子目录，如 /website
          PUBLIC_URL: /
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # 如果你的项目文件不在根目录，请修改这里为项目的 build 目录，如 './website/build'
          path: './build'

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

保存 workflow 文件之后，手动触发一次 Run workflow，等待 workflow 运行完成。

此时你应该可以在https://<username>.github.io/<repository-name> 看到你的网站了。

每当你在指定分支上 push 代码时，GitHub 都会自动运行 workflow，重新构建并部署你的网站，实现丝滑更新🤌

为 GitHub Pages 绑定域名

如果你需要为 GitHub Pages 绑定自定义的域名，大致上参考 GitHub 官方文档即可，这里简单说下我的配置。

在 public 目录下创建一个 CNAME 文件，文件的内容是你要绑定的域名，比如 list.tc-edu.org。
登录你的域名服务商管理页面（我用的是 Cloudflare），在 DNS records 中添加一条 CNAME 记录，让 list.tc-edu.org 指向 <username>.github.io。

这里需要填 3 个东西：
- Type：CNAME。此处我需要配置的是 subdomain，即 list.tc-edu.org，需要的是 CNAME。如果你需要配置顶级域名，比如 tc-edu.org，则需要在 DNS records 中添加 A 记录，具体细节参考官方文档。
- Name：list。这里填写的是你的子域名，比如对于 list.tc-edu.org 来说要填写 list。
- Target：<username>.github.io。这里填写的是你的 GitHub Pages 默认 URL，我的 GitHub 用户名是 ran-huang，所以填写 ran-huang.github.io。
保存 DNS records 后，返回 GitHub 仓库设置页，一段时间后可以看见 DNS check successful 的字样，具体时长取决于你的域名服务商，Cloudflare 通常只需要一两分钟。

Congratulations，你可以通过绑定好的域名访问你的 React 页面了！🎉

参考资料

2023-07-14 21:37:19