⚙️ 配置 GitHub Actions 每周自动更新

中级 · 15 分钟 · 2026-08-16

1. 创建 workflow 文件

仓库根目录已经有 .github/workflows/update-data.yml。如果你 fork 了一份，先看下：

.github/workflows/update-data.yml

2. 完整 workflow 代码

name: Update DSH Radar data

on:
  # 每周一 UTC 02:00（北京时间 10:00）自动跑
  schedule:
    - cron: '0 2 * * 1'
  # 允许手动触发（Actions → Run workflow）
  workflow_dispatch:
  # 脚本改动时也触发（方便调试）
  push:
    paths:
      - 'scripts/**'

jobs:
  build-data:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Cache npm + GitHub data
        uses: actions/cache@v4
        with:
          path: |
            ~/.npm
            data/.cache
          key: cache-${{ runner.os }}-${{ hashFiles('scripts/**') }}
          restore-keys: |
            cache-${{ runner.os }}-

      - name: Fetch + score plugins
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LIMIT: '0'  # 0 = 全量 711；初次试跑可设 100
        run: node scripts/build-data.mjs

      - name: Build search index
        run: node scripts/build-search-index.mjs

      - name: Build changelog
        run: node scripts/build-changelog.mjs

      - name: Build authors index
        run: node scripts/build-authors.mjs

      - name: Commit updated data
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'data: refresh plugin scores [skip ci]'
          file_pattern: 'data/**'

  build-web:
    needs: build-data
    runs-on: ubuntu-latest
    # deploy-pages@v4 必须要这三个权限，少一个就是 Permission denied
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      # 注意：要拉上一个 job 刚提交的最新数据
      - uses: actions/checkout@v4
        with:
          ref: main

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'
          cache-dependency-path: web/pnpm-lock.yaml

      - name: Install + build web
        working-directory: web
        run: |
          pnpm install --frozen-lockfile
          pnpm build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: web/dist

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3. 步骤拆解

这套 workflow 分成两个 job，六个关键步骤，各自负责一件事：

两个 job 用 needs: build-data 串起来：数据没抓完就不会 build 站点， 避免把半截数据推上线。commit message 里的 [skip ci] 则防止自动提交再次触发 workflow 造成死循环。

4. 配置 secrets

GitHub Actions 里需要这些 secrets。仓库 → Settings → Secrets and variables → Actions → New repository secret：

GITHUB_TOKEN 是 GitHub Actions 自动提供的，不用手动设。 它让你的 build 能调 5000 次/小时 GitHub API（vs 60 次/小时未认证）。

5. cron 语法速查

GitHub Actions 的 cron 是 UTC 时区：

┌──────── 分钟 (0 - 59)
│  ┌───── 小时 (0 - 23, UTC)
│  │  ┌── 日 (1 - 31)
│  │  │  ┌─ 月 (1 - 12)
│  │  │  │  ┌ 周 (0 - 7, 0 和 7 都是周日)
│  │  │  │  │
*  *  *  *  *

# 常见例子：
'0 2 * * 1'     # 每周一 02:00 UTC = 北京周一 10:00（本项目默认）
'0 0 * * 0'     # 每周日 00:00 UTC
'0 14 * * *'    # 每天 14:00 UTC
'0 */6 * * *'   # 每 6 小时一次

⚠️ GitHub Actions 的定时 schedule 有时延迟（10-30 分钟），不要用来做精确任务。

6. 启用 GitHub Pages

1. 仓库 → Settings → Pages
2. Source: GitHub Actions（不是 "Deploy from a branch"）
3. 保存
4. 第一次跑 workflow 后会自动创建 Pages 环境

7. 手动触发测试（workflow_dispatch）

1. 仓库 → Actions 标签
2. 左侧选 "Update DSH Radar data"
3. 右侧 "Run workflow" → 选 main 分支 → Run
4. 等 5-30 分钟，看日志

8. 常见故障排查