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,不要覆盖已有脚本:
{
"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,就会在这一关失败。

配置 GitHub Actions 执行检查
创建 .github/workflows/check-tokens.yml。以下完整工作流在拉取请求和推送到 main 时运行;假设工作目录就是仓库根目录,npm run build:tokens 可以在其中执行。
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 设为必需状态检查,失败才会实际阻止合并。