UI 视觉设计 / 系统课时

在 CI 检查令牌构建的一致性

在 CI 检查令牌构建的一致性

令牌在本地生成成功,不代表每次构建都能得到同样的 CSS 和 JavaScript。本篇把重复构建比较和 Git 产物差异检查放进 CI:前者发现随机输出,后者拦截漏提交或手工修改的生成文件,让不一致的提交无法通过检查。

学习目标

  • 区分重复构建一致性与已提交产物一致性两种检查。
  • 使用锁定依赖、两次干净构建和文件比较配置 GitHub Actions。
  • 根据失败的门禁定位随机输出、产物漏提交与手工修改。

先约定可检查的构建产物

以 Node.js 24、npm、Style Dictionary 5 和 GitHub Actions 的 Ubuntu Runner 为例。假设输入位于 tokens/,配置文件为 sd.config.mjs,dist/tokens/ 内生成 variables.css 与 tokens.js。这些生成文件需要提交到 Git,并且不应被 .gitignore 忽略。

现有 package.json 的脚本片段示例如下,只将 build:tokens 合并进原有 scripts,不要覆盖已有脚本:

json
{
  "scripts": {
    "build:tokens": "style-dictionary build --config ./sd.config.mjs"
  }
}

该片段依赖项目已安装 Style Dictionary 5、已有可用的 sd.config.mjs,并在 CSS 和 JS 平台配置中将 buildPath 设为 dist/tokens/。同时提交 package-lock.json,使 CI 的 npm ci 按锁文件安装依赖。若项目选择不提交生成产物,应另用构建产物发布方案;下面的 Git 差异门禁专用于生成文件入库的做法。

理解两道不同的比较门禁

第一次构建前清理 dist/tokens/,保存构建 A 的所有文件;再次清理目录后执行构建 B。使用 diff -ru 比较两份文件树,能同时发现文件内容不同、缺失或新增。即使两次输出相同,也还要比较构建 B 与 Git 已提交版本:输入 Token 改了却忘记提交 CSS,就会在这一关失败。

两次干净构建和 Git 产物对照的双门禁流程

配置 GitHub Actions 执行检查

创建 .github/workflows/check-tokens.yml。以下完整工作流在拉取请求和推送到 main 时运行;假设工作目录就是仓库根目录,npm run build:tokens 可以在其中执行。

yaml
name: Token consistency
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: '24'
          cache: npm
      - run: npm ci
      - name: Compare two clean builds
        shell: bash
        run: |
          set -euo pipefail
          # 每次构建都移除旧产物,避免残留文件影响判断
          rm -rf dist/tokens
          npm run build:tokens
          test -d dist/tokens
          first="$(mktemp -d)"
          trap 'rm -rf "$first"' EXIT
          cp -a dist/tokens/. "$first/"
          rm -rf dist/tokens
          npm run build:tokens
          diff -ru "$first" dist/tokens
      - name: Check committed outputs
        shell: bash
        run: |
          set -euo pipefail
          # 文件清单检查包括新增文件,避免只比较已跟踪文件
          find dist/tokens -type f -printf '%P\n' | LC_ALL=C sort > "$RUNNER_TEMP/built.txt"
          git ls-files -- dist/tokens | sed 's#^dist/tokens/##' | LC_ALL=C sort > "$RUNNER_TEMP/tracked.txt"
          test -s "$RUNNER_TEMP/tracked.txt"
          diff -u "$RUNNER_TEMP/tracked.txt" "$RUNNER_TEMP/built.txt"
          git diff --exit-code -- dist/tokens

预期结果:两次构建的文件树相同,生成的文件清单与 Git 跟踪清单相同,文件内容也未发生变化时,任务通过;任何一个 diff 返回非零或 git diff --exit-code 检出差异时,任务失败。npm ci 的普通安装日志不作为比较依据。

根据失败位置修复问题

CI 失败位置 典型原因 修复做法
diff -ru 产物嵌入当前时间、随机 ID 或不稳定遍历顺序 删除时间戳;按固定键名排序;不要把绝对构建路径写入产物
文件清单 diff -u 新产物未纳入 Git、旧文件未移除,或目录被忽略 核对 dist/tokens/ 文件清单,将应交付文件提交并移除废弃文件
git diff --exit-code Token 源码已修改但生成文件未更新,或手改了已提交的 CSS 本地运行 npm run build:tokens,审阅差异后同时提交源文件与生成结果

复现实验时,可先只改 tokens/ 中一个颜色值而不更新 dist/tokens/,创建拉取请求:两次重新生成仍应一致,但与 Git 版本的内容比较会失败。随后本地重建、检查变更并提交生成结果,预期相同工作流通过。对 main 开启分支保护并将 check 设为必需状态检查,失败才会实际阻止合并。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

在 CI 检查令牌构建的一致性

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通