在 :root 中声明全局 CSS 变量需包裹于 :root { } 选择器内，变量名以 -- 开头，推荐按语义分组；不可在顶层、@import 后或无选择器的 @layer 中直接声明，否则无效；暗色模式通过 @media 或 [data-theme] 覆盖 :root 变量实现；嵌套引用 var() 须避免循环依赖与未定义引用。
如何在 :root 中声明全局 CSS 变量
所有 CSS 变量（自定义属性）必须显式写在某个选择器内，:root 是最常用、也最符合“全局”语义的位置——它等价于 html 元素，但优先级更高，且能被所有后代元素继承。
常见错误是直接在 CSS 文件顶层写 --color-primary: #007bff，这会完全无效，浏览器直接忽略。
- 变量名必须以
--开头，比如--spacing-md，不能是color-primary - 推荐把设计令牌按语义分组，比如颜色、间距、圆角、字体大小，用注释隔开
- 避免在
:root里写依赖 JS 动态计算的值；CSS 变量本身不执行 JS，只做静态声明或后续覆盖
:root {
/* 颜色 */
--color-primary: #007bff;
--color-text: #333;
<p>/<em> 间距 </em>/
--space-xs: 4px;
--space-sm: 8px;
--space-md: 16px;
}</p>
为什么不能在 @layer 或 @import 后直接写变量
CSS 变量不是规则，而是自定义属性，它的作用域由声明位置决定。即使你用 @layer base 包裹 :root，变量依然生效；但如果你把变量写在 @import 语句之后、又没包在选择器里，它就丢失了上下文。
典型翻车场景：把变量塞进 theme.css 并用 @import 'theme.css' 引入，结果变量没生效——因为导入文件里漏了 :root { ... } 外层包裹。
-
@import只是加载内容，不改变语法作用域规则 -
@layer控制级联顺序，不影响变量是否被识别 - 只要变量不在合法选择器内部，哪怕在
@layer块里也会被丢弃
如何让 CSS 变量支持暗色模式切换
靠媒体查询 + :root 覆盖是最轻量、兼容性最好的方式。不要试图用 JS 批量 setProperty，那会绕过 CSS 自然继承和性能优化。
注意：@media (prefers-color-scheme: dark) 的匹配时机是页面加载和系统设置变更时，变量更新是同步的，无需额外监听。
- 确保暗色版变量在明色版之后声明，否则会被覆盖
- 不要在
body.dark这类类名上重复定义整套变量，容易遗漏或冲突 - 如果项目需手动切换主题，可用
html[data-theme="dark"]替代媒体查询，逻辑更可控
:root {
--color-bg: #fff;
--color-text: #333;
}
<p>@media (prefers-color-scheme: dark) {
:root {
--color-bg: #1a1a1a;
--color-text: #eaeaea;
}
}</p>
变量值里写 var(--other) 时为什么有时不生效
CSS 变量支持嵌套引用，但仅限于声明时的静态解析。一旦出现循环引用（A 用 B，B 又用 A），或父级未定义就被子级引用，浏览器会静默 fallback 到继承值或初始值（通常是 unset）。
典型表现是元素颜色/尺寸突然消失或回退到浏览器默认值，开发者工具里变量显示为 “invalid” 或划掉。
- 检查依赖链是否成环，用 DevTools 的 Computed 面板看最终计算值
- 避免在
:root内部跨组引用，比如先用--space-md定义--card-padding，再反过来用--card-padding定义--space-md - 函数如
calc()内使用var()是安全的，但别在var()的 fallback 参数里再嵌套var()
变量的“全局性”其实只是作用域足够宽，不是魔法。真正容易被忽略的是：它没有模块化隔离，也没有编译期校验——写错名、拼错 --、漏掉 :root，都不会报错，只会沉默失效。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
