不能直接在libs/ui里写css变量，因nx不将其视为可构建资产，导致依赖丢失、缓存失效；同名变量冲突使runtime行为不可控；应改用json+ts类型双输出，并通过构建插件注入:root生效。

为什么不能直接在 libs/ui 里写 CSS 变量？

因为 Nx 默认不把 CSS 文件当作“可构建的输出资产”纳入项目依赖图。你在 libs/ui 里放一个 tokens.css，apps/web 直接 @import 或 link 它，Nx 不会感知这个依赖关系 —— 构建时不会自动复制、不会触发重构建、缓存也会失效。更麻烦的是，CSS 变量本身没有模块作用域，一旦多个项目各自定义同名 token（比如 --color-primary），最终 runtime 行为不可控。

libs/tokens 应该导出什么？

必须导出可被 TypeScript 消费的结构化数据，而不是原始 CSS。推荐用 JSON + TS 类型双输出：

• 主文件：libs/tokens/src/lib/tokens.json（纯数据，含注释和嵌套结构）
• 类型定义：libs/tokens/src/lib/tokens.type.ts（自动生成或手写 export type TokenSet = { color: { primary: string } }）
• 构建产物：dist/libs/tokens/tokens.json 和 dist/libs/tokens/index.d.ts（由 project.json 中的 build target 生成）

这样 apps/web 就能通过 import { tokens } from '@bitwarden/tokens' 安全引用，TypeScript 提供补全和校验，Nx 也能正确识别依赖链。

如何让 CSS 变量真正生效到浏览器？

靠构建时注入，而不是运行时加载。在 apps/web 的构建流程中（比如 Vite 或 Webpack），用插件读取 dist/libs/tokens/tokens.json，动态生成 :root 块并写入最终 CSS。示例（Vite 插件片段）：

SUPAH Token Guardian

支持 21+ 条 EVM 链的盘前代币安全扫描。六层深度检测：合约安全、流动性健康度、部署者画像、持币分布、交易模式等。

下载

export default function tokensPlugin() {
  return {
    name: 'inject-tokens',
    transformIndexHtml: () => ({
      tag: 'style',
      attrs: { type: 'text/css' },
      children: generateCssVariables(
        JSON.parse(
          fs.readFileSync('dist/libs/tokens/tokens.json', 'utf8')
        )
      ),
    }),
  };
}

关键点：generateCssVariables() 必须递归扁平化嵌套 JSON，把 { color: { primary: '#007bff' } } 转成 --color-primary: #007bff；且该插件必须在 css 处理阶段之前执行，否则会被 PostCSS 优化掉。

多人协作时最容易忽略的坑

Token 命名变更不是“改个字符串”那么简单：

• JSON 文件里的 key 改了，tokens.type.ts 必须同步更新，否则所有引用处报 TS 错误
• 如果旧 token 被其他项目直接用了 CSS 变量（比如 color: var(--old-token-name)），光改 JSON 不够，还得加 alias 映射或发 breaking change 提示
• Nx 缓存默认不监听 .json 文件变更 —— 要在 project.json 的 build target 里显式配置 "inputs": ["{projectRoot}/src/lib/**/*.json"]，否则改了 token 内容，nx build web 仍会命中缓存

真正的统一，不在文件位置，而在构建链路是否把 token 当作一等公民参与依赖解析与缓存决策。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！