【GitHub Workflows】GitHub Pages 自动部署进阶：PR 预览、多语言、自定义域名绑定

🌍 GitHub Pages 自动部署进阶：PR 预览、多语言、自定义域名绑定

---

📌 一、PR 预览环境（Pull Request Preview）

🧐 场景

想象你在开源项目中维护文档或 UI 展示网站，每次改动都希望 reviewer 能在线预览效果，这时 PR Preview 环境就派上用场了！

✅ 原理

1. 每当有人提 PR 时，GitHub Actions 自动构建预览版本；
2. 构建结果上传为 Artifact；
3. 由 deploy-pages 发布到临时预览 URL；
4. 预览地址挂在 PR 页面上，供开发者查看。

---

📦 实战 Workflow 示例（PR 预览）：

name: Preview Deploy

on:
  pull_request:
    branches: [main]

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

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install && npm run build

      - name: Upload Preview Artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: './dist'

  deploy:
    needs: preview
    runs-on: ubuntu-latest
    environment:
      name: github-pages-preview
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy PR Preview
        uses: actions/deploy-pages@v3

🚀 效果

PR 打开后自动生成 preview_url，点进去就能预览本分支的构建效果。

---

🌐 二、多语言站点部署（i18n）

🧐 场景

比如你写了一个文档站，要支持 /en/ 和 /zh/ 两种语言，部署时希望两个版本都能在线访问。

✅ 方法一：多语言文件夹合并构建

构建阶段把所有语言内容都构建进 dist 目录，例如：

dist/
├── en/
├── zh/
└── index.html

部署时只要指定 publish_dir: ./dist 即可。

✅ 方法二：构建多个子项目，合并为一份部署产物

使用自定义构建脚本将多个语言项目结果整合为一个总目录并上传 artifact，参考如下：

npm run build:en && mv dist dist-en
npm run build:zh && mv dist dist-zh

mkdir dist-all
mv dist-en dist-all/en
mv dist-zh dist-all/zh

上传 dist-all 目录即可。

---

🔐 三、自定义域名绑定 + HTTPS

✅ 步骤一：DNS 配置你的域名

到域名服务商（如 Cloudflare、Namecheap）配置以下记录：

类型	名称	值
CNAME	www	<你的 GitHub 用户名>.github.io
A	@	185.199.108.153（GitHub IP）等

官方推荐用 CNAME，尤其是子域名部署。

---

✅ 步骤二：GitHub Pages 绑定域名

进入项目设置 → Pages → Custom Domain → 输入你的域名，例如：

www.my-docs-site.com

然后勾选 Enforce HTTPS。

---

✅ 步骤三（可选）：通过 CNAME 文件绑定

你也可以在构建时自动生成 dist/CNAME 文件：

echo "www.my-docs-site.com" > dist/CNAME

这样每次部署都会自动更新绑定。

---

🧠 Bonus：部署后自动通知或评论 PR

可以搭配 github-script action，在 PR 下评论部署链接：

- name: Comment PR with preview URL
  uses: actions/github-script@v6
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: "📦 预览已部署：[点击查看](${{ steps.deployment.outputs.page_url }})"
      })

---

✅ 总结

功能	技术点	是否推荐
PR 预览	upload-pages-artifact + deploy-pages	✅✅✅
多语言支持	构建时合并子目录	✅✅
自定义域名	DNS + CNAME 文件	✅✅✅
自动评论通知	github-script + REST API	✅✅

---