CSS变量在CSS Modules中无法被JS动态读取，因Modules会将--color-primary等变量名哈希化（如--color-primary_foo123），而JS仍按原名访问，导致静默失效；解决办法是将变量声明移至全局CSS文件或用:export导出静态值。
CSS变量在CSS Modules中无法被JS动态读取
CSS Modules会把:root里的--color-primary这类变量名也进行哈希化（如变成--color-primary_foo123），但JS里用getComputedStyle或element.style.setProperty仍按原名访问，自然拿不到值。这不是“报错”，而是静默失效。
常见现象：你在Button.module.css里写了:root { --bg: #007bff; }，然后在组件里el.style.setProperty('--bg', 'red')，页面毫无反应。
- 根本原因：CSS Modules默认对所有选择器和自定义属性名做局部作用域处理，
--*也被当成“类名”转义了 - 解决办法：把变量声明移到全局CSS（如
index.css）中，或用:export导出变量名（但仅限字符串值，不支持动态计算） - 注意：
:export只能导出静态值，比如primaryColor: #007bff;，不能写primaryColor: var(--bg);
使用:export时无法引用其他CSS变量
:export是CSS Modules提供的伪类，用于把CSS值暴露给JS，但它不解析var()函数，只做字面量导出。
示例：如果写:export { theme: var(--color-theme); }，JS里拿到的是字符串"var(--color-theme)"，不是实际计算后的颜色值。
立即学习“前端免费学习笔记（深入）”；
- 必须手动在JS中调用
getComputedStyle(document.documentElement).getPropertyValue('--color-theme')再赋值 - 更稳妥的做法是：全局CSS定义变量 → JS读取 → 通过props或context注入组件，绕过CSS Modules的变量层
- Webpack 5+用户可配合
css-loader的modules.exportLocalsConvention配置，但依然不解决var()解析问题
React中用className + CSS变量组合时样式丢失
当你在CSS Modules文件中这样写：.button { background-color: var(--bg); }，而--bg定义在另一个模块或全局未生效，DevTools里会显示background-color: var(--bg)但计算值为initial（即透明/默认色）。
- 检查顺序：CSS变量必须在使用前已声明，且作用域覆盖到当前元素（
:root最安全） - CSS Modules不会自动合并多个
:root块，后加载的会覆盖前一个，容易导致变量被意外重写 - 推荐做法：所有主题变量统一放在
src/index.css中，用import './index.css'确保最先加载
服务端渲染（SSR）下CSS变量初始值不可靠
Next.js或Remix等框架中，若CSS变量依赖客户端JS设置（如暗色模式切换），服务端生成的HTML里style标签还没执行，var(--mode)会回退到浏览器默认值（通常是unset），造成首屏闪动。
- 解决方案：在
_document.tsx或Document组件中，用getInitialProps读取请求头或cookie判断主题，内联<style>:root { --mode: dark; }</style> - 避免在CSS Modules中依赖JS运行时才设置的变量做关键布局（比如
width: calc(100vw - var(--sidebar-width))） - 真正需要动态响应的场景，优先用CSS-in-JS库（如
styled-components的ThemeProvider）或useEffect+document.documentElement.style手动同步
最易被忽略的一点：CSS Modules本身不提供变量作用域隔离能力，它只是类名转换工具；所谓“CSS变量冲突”，本质是开发者误以为--x能像.x一样被模块化——而实际上所有--*都是全局的，哈希化只是假象，一旦跨模块引用就立刻暴露问题。
