UI 视觉设计 / 系统课时
在 CI 中比较生成文件差异
在 CI 中比较生成文件差异
Token 变更后若漏提交新生成的 CSS 与 ESM,组件仍会引用旧值。本课用 GitHub Actions 在每次提交时清空输出目录并重新构建,与 Git 中已提交的生成文件比对;出现修改、缺失或新增就让校验失败,避免不一致的产物进入主分支。
学习目标
- 区分 Token 权威源文件、可重复构建命令与提交到 Git 的生成产物。
- 在 CI 中检测生成文件的修改、删除和新增,输出可审查的差异。
- 复现一次失败、修复提交,并让检查结果成为合并门槛。
确定比较基准
示例项目以 tokens/tokens.json 为输入,生成 generated/tokens.css 和 generated/tokens.mjs。这两个输出文件必须纳入 Git 跟踪,不应被 .gitignore 忽略;package-lock.json 也要提交,供 npm ci 安装锁定的依赖版本。
比较的基准是当前 PR 检出的提交中已保存的 generated/ 文件,而不是直接把 PR 的产物与 main 比较。这样修改 Token 并同步更新产物的合法变更可以通过,漏提交产物的变更会失败。
准备可重复的生成命令
以下是一个不依赖第三方库的最小工程;已有 Style Dictionary 项目可保留自己的转换配置,只要 npm run build:tokens 能从源文件确定性地重建 generated/ 即可。先在仓库根目录保存 package.json:
{
"name": "token-ci-demo",
"version": "1.0.0",
"private": true,
"scripts": {
"build:tokens": "node scripts/build-tokens.mjs"
}
}输入文件 tokens/tokens.json 使用 DTCG 的 $type、$value 字段:
{
"color": {
"brand": {
"primary": {
"$type": "color",
"$value": "#2563eb"
}
}
}
}在 scripts/build-tokens.mjs 写入完整构建脚本:
import { readFileSync, mkdirSync, writeFileSync } from 'node:fs';
const tokens = JSON.parse(readFileSync('tokens/tokens.json', 'utf8'));
const rawColor = tokens.color.brand.primary.$value;
// 输入非法时立刻停止,避免把错误值发布给组件。
if (typeof rawColor !== 'string' || !/^#[0-9a-fA-F]{6}$/.test(rawColor)) {
throw new Error('color.brand.primary 必须是六位十六进制颜色');
}
const color = rawColor.toLowerCase();
mkdirSync('generated', { recursive: true });
// 固定输出顺序和换行,不写入时间戳、绝对路径等环境信息。
writeFileSync('generated/tokens.css', `:root {\n --color-brand-primary: ${color};\n}\n`, 'utf8');
writeFileSync('generated/tokens.mjs', `export const brandPrimary = '${color}';\n`, 'utf8');使用 Node.js 24,在支持 Bash 的终端执行;首次通过 npm install --package-lock-only 生成锁文件,提交时将它与其他源文件、产物一起加入 Git:
npm install --package-lock-only
npm ci
npm run build:tokens
cat generated/tokens.css预期结果:构建成功,最后一条命令打印以下 CSS;npm 自身的安装提示可能随版本变化。
:root {
--color-brand-primary: #2563eb;
}同时,generated/tokens.mjs 应包含 export const brandPrimary = '#2563eb';。固定颜色格式、输出顺序及 LF 换行,可以减少跨环境构建时不必要的文件差异。
在 GitHub Actions 中设置校验闸门
在 .github/workflows/token-diff.yml 创建工作流。处理顺序是检出 PR 内容、安装锁定依赖、清空旧生成目录、重新构建,然后与 Git 工作区的基准文件比较。先删除旧目录能额外发现已提交、但现有构建器不再产出的过期文件。

name: Token generated files
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
token-diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '24'
cache: npm
- run: npm ci
- name: Rebuild
run: |
rm -rf generated/
npm run build:tokens
- name: Compare generated files
shell: bash
run: |
# 打印已跟踪文件的修改或删除差异,便于审查。
git diff -- generated/
untracked="$(git ls-files --others --exclude-standard -- generated/)"
if [ -n "$untracked" ]; then
printf '新增但未提交的文件:\n%s\n' "$untracked"
fi
# git diff 不检查新文件,必须单独检查未跟踪列表。
if ! git diff --quiet -- generated/ || [ -n "$untracked" ]; then
echo "::error::生成文件与提交不一致,请重新构建并提交 generated/"
exit 1
fi这里使用 GitHub Actions 的 actions/checkout@v7 和 actions/setup-node@v7,并通过 node-version: '24' 固定 Node.js 主版本。cache: npm 使用锁文件生成缓存键,但不会替代 npm ci;锁文件与依赖声明不一致时,安装阶段就会失败。
git diff --quiet 对已跟踪文件的修改与删除返回非零状态;git ls-files --others --exclude-standard 补查未跟踪的新文件。任何一项命中即退出 1,其余情况完成为成功。这里的 rm -rf 只针对固定的仓库内生成目录,不能替换成接收不可信参数的路径。
验证失败、修复与合并保护
- 首次运行构建后提交
package.json、package-lock.json、tokens/、scripts/、generated/和工作流文件,确认 PR 的token-diff检查通过。 - 将
tokens/tokens.json中的$value从#2563eb改成#1d4ed8,只提交源文件。CI 重建后会发现tokens.css和tokens.mjs均与提交版本不同,并以失败状态结束。 - 本地运行
npm run build:tokens,检查git diff -- generated/,把更新后的两个生成文件一同提交。重新运行的检查应通过。 - 再试着提交一个不再由构建器生成的
generated/old.css:CI 清空并重建目录后会把它识别为删除差异;仅有新增未跟踪文件时则由第二道检查拦截。
成功时,Compare generated files 步骤退出码为 0,整个 token-diff 任务显示成功;失败时会输出已跟踪文件的差异或新增文件路径,并显示 ::error:: 产生的错误注解。检查异常时,应先确认构建命令正常执行,再判断是忘记提交产物,还是生成器本身产生了不稳定输出。
最后在仓库针对主分支的 Ruleset 或分支保护中,将 token-diff 设为必需通过的状态检查。只配置工作流而不设置合并保护,失败的 PR 仍可能被合并。若产物一直漂移,应排查 Node 版本、锁文件、排序、换行与时间戳;这道闸门验证的是生成结果是否与提交一致,仍需另外运行 Token 类型、引用和可访问性等语义校验。