应将CSS变量按作用域分层管理：设计系统级变量（如--ds-color-error）置于:root，组件级变量（如--card-padding）限于组件选择器内；禁用裸名和重复:root声明，避免继承断链与构建失效。
变量全塞进 :root 就等于埋雷
很多人以为把所有 --color-primary、--spacing-md 全堆在 :root 里是“全局统一”，实际是把变量管理权交给了命名直觉。一旦项目超过 5 个业务模块，就会出现：--text-light 在登录页指“浅灰提示文字”，在后台页却指“深色模式下的白色文字”——语义完全错位。
更麻烦的是构建阶段：Vite 的 CSS 预处理插件（如 postcss-custom-properties）可能提前静态替换变量，而运行时 JS 调用 document.documentElement.style.setProperty('--text-light', '#fff') 就会失效，因为值已被编译掉了。
- 只在
:root放设计系统级变量：基础色、字体族、断点、圆角基数等，命名必须带明确作用域前缀，如--ds-color-error，禁用--red这类裸名 - 组件级变量（如
--card-padding、--modal-z-index）改用@layer component或直接写在组件选择器内，确保作用域收敛 - 禁止在多个 CSS 文件里重复
:root { --x: ... }—— Webpack/Vite 不会合并，后加载的会覆盖先加载的
var(--x) 在嵌套结构里突然失效，不是 bug 是作用域误判
CSS 变量不是 Sass 那种编译时展开，它走 DOM 继承链。父元素没声明 --bg，子元素写 background: var(--bg) 就回退到 unset，DevTools 里显示 “invalid value”，但你根本看不出哪一层断了。
常见误操作：.list-item:hover { --item-bg: #f0f9ff; } 然后 .list-item__content { background: var(--item-bg); } —— hover 状态不触发时，--item-bg 根本不存在，内容区背景就没了。
立即学习“前端免费学习笔记（深入）”；
- 变量声明必须落在能稳定继承的节点上，比如
.list-item { --item-bg: #f0f9ff; }（非 hover 伪类） - 伪元素如
::before能读宿主变量，但content: "icon-" var(--name)是非法语法，只能用 JS 拼接或改用属性选择器 - 调试时别全局搜
--item-bg，直接在 DevTools 选中元素 → Styles 面板 → 点变量名旁的小箭头，跳转到定义处，快且准
拆成 _colors.css、_spacing.css 后反而加载失败
开发者想模块化，把变量按主题拆成多个文件，再用 @import 引入。问题在于：Webpack/Vite 默认不解析 CSS 里的 @import，尤其当它出现在被 cssnano 压缩后的文件里，@import 可能被删掉，或者变量定义顺序错乱 —— _spacing.css 里用了 --ds-unit，但 _unit.css 还没加载。
更隐蔽的坑：你在 main.css 里 @import '_colors.css'，又在 JS 里 import './_colors.css'，结果浏览器收到两份 :root，后者覆盖前者，主题切换瞬间失灵。
- 所有变量集中在一个
variables.css，用<link rel="stylesheet">在 HTML<head>同步加载，确保优先级最高 - 如果用 CSS-in-JS（如 Emotion），变量必须通过
injectGlobal注入，不能指望它自动读取外部 CSS 文件 - 构建工具里禁用
cssnano对变量文件的压缩，或确保postcss-import插件在cssnano之前执行
document.documentElement.style.setProperty 切换主题不生效
调用没报错，但页面颜色纹丝不动。大概率是 CSS 优先级被卡住了：某个组件写了 .card { background-color: #fff !important; }，它比 var(--card-bg) 高得多，变量再怎么 setProperty 都没用。
另一个常见原因是变量名不一致：--theme-bg 和 --bg-theme 看似一样，但主题切换脚本改了一个，CSS 里用的是另一个，DevTools 里查不到定义，只显示 fallback 值。
- 切换前先清空所有可能干扰的
!important，尤其是第三方 UI 库的样式 - 主题变量名必须严格统一，建议用 JSON Schema 管理变量清单，生成 TS 类型 + CSS 文件双校验
- 不要依赖 JS 动态插入 style 标签覆盖，而是用
document.documentElement.setAttribute('data-theme', 'dark')配合属性选择器，更可控
