CSS无变量作用域机制，所谓“未定义变量”实为自定义属性未声明或JS读取返回undefined；需结合Chrome DevTools检查计算值回退、验证作用域匹配，并用PostCSS插件在构建时预警缺失变量。
CSS 本身没有变量作用域或运行时检查机制，undefined 不是 CSS 的概念——你看到的“未定义变量”实际是 CSS 自定义属性（--my-color）被引用但未声明，或在 JavaScript 中读取时返回 undefined。这类问题无法靠纯 CSS 工具发现，必须结合浏览器 DevTools 和 JS 检查逻辑。
Chrome DevTools 中快速定位未声明的 CSS 自定义属性
浏览器不会报错，但会静默忽略无效的 var(--xxx) 引用。关键看计算值是否回退到初始值：
- 打开 Elements 面板，选中元素 → Styles 标签页
- 找到含
var(--xxx)的声明（如color: var(--text-primary);） - 若右侧显示
color: initial或color: inherit（且无 fallback），说明--text-primary未在任何作用域中定义 - 点击该属性名，DevTools 会高亮所有匹配的
:root、.class等作用域，帮你确认是否遗漏声明
JavaScript 读取 CSS 变量时返回 undefined 的排查方法
当你用 getComputedStyle(el).getPropertyValue('--foo') 得到空字符串，或 el.style.getPropertyValue('--foo') 返回 undefined，原因通常是：
-
getComputedStyle只读全局生效的变量，若变量定义在未匹配的选择器内（如.dark-mode --foo但元素没加dark-mode类），结果为空 -
element.style只读内联样式设置的变量，不包含来自 CSS 文件或:root的值 - 变量名拼写错误：CSS 中是
--bg-color，JS 里写成--bg-colour或漏了双短横线 - 执行时机过早：脚本运行时 DOM 还没加载完，或 CSS 尚未解析，建议用
DOMContentLoaded或requestAnimationFrame延迟读取
用 PostCSS 插件在构建阶段提前暴露缺失变量
开发阶段靠人工检查容易遗漏，可在构建流程中加入静态检查：
立即学习“前端免费学习笔记（深入）”；
- 安装
postcss-custom-properties（官方插件）并启用preserve: false，它会在编译时报出未定义变量的警告 - 更严格可用
postcss-css-variables配合validate选项，对每个var(--x, fallback)检查--x是否存在 - 注意：这些插件只检查同一文件或已
@import的 CSS，跨文件未 import 的变量仍会漏检
真正难发现的是动态生成的变量名（比如 var(--theme-${mode})），这种只能靠 JS 运行时断点 + getComputedStyle 手动验证，工具无能为力。
