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:

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 字段:

json
{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": "#2563eb"
      }
    }
  }
}

在 scripts/build-tokens.mjs 写入完整构建脚本:

js
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:

bash
npm install --package-lock-only
npm ci
npm run build:tokens
cat generated/tokens.css

预期结果:构建成功,最后一条命令打印以下 CSS;npm 自身的安装提示可能随版本变化。

css
:root {
  --color-brand-primary: #2563eb;
}

同时,generated/tokens.mjs 应包含 export const brandPrimary = '#2563eb';。固定颜色格式、输出顺序及 LF 换行,可以减少跨环境构建时不必要的文件差异。

在 GitHub Actions 中设置校验闸门

在 .github/workflows/token-diff.yml 创建工作流。处理顺序是检出 PR 内容、安装锁定依赖、清空旧生成目录、重新构建,然后与 Git 工作区的基准文件比较。先删除旧目录能额外发现已提交、但现有构建器不再产出的过期文件。

Token 生成文件的 CI 重建与差异闸门

yaml
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 只针对固定的仓库内生成目录,不能替换成接收不可信参数的路径。

验证失败、修复与合并保护

  1. 首次运行构建后提交 package.json、package-lock.json、tokens/、scripts/、generated/ 和工作流文件,确认 PR 的 token-diff 检查通过。
  2. 将 tokens/tokens.json 中的 $value 从 #2563eb 改成 #1d4ed8,只提交源文件。CI 重建后会发现 tokens.css 和 tokens.mjs 均与提交版本不同,并以失败状态结束。
  3. 本地运行 npm run build:tokens,检查 git diff -- generated/,把更新后的两个生成文件一同提交。重新运行的检查应通过。
  4. 再试着提交一个不再由构建器生成的 generated/old.css:CI 清空并重建目录后会把它识别为删除差异;仅有新增未跟踪文件时则由第二道检查拦截。

成功时,Compare generated files 步骤退出码为 0,整个 token-diff 任务显示成功;失败时会输出已跟踪文件的差异或新增文件路径,并显示 ::error:: 产生的错误注解。检查异常时,应先确认构建命令正常执行,再判断是忘记提交产物,还是生成器本身产生了不稳定输出。

最后在仓库针对主分支的 Ruleset 或分支保护中,将 token-diff 设为必需通过的状态检查。只配置工作流而不设置合并保护,失败的 PR 仍可能被合并。若产物一直漂移,应排查 Node 版本、锁文件、排序、换行与时间戳;这道闸门验证的是生成结果是否与提交一致,仍需另外运行 Token 类型、引用和可访问性等语义校验。

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

目录与阅读设置

阅读设置

17

记录一个想法

在 CI 中比较生成文件差异

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

登录哪都通