Vue 3.4+ 中 v-bind() 绑定 CSS 变量必须写在 <style module> 里，因为仅该标签支持将响应式变量自动注入 CSSOM；普通 <style> 或 <style scoped> 下 v-bind() 会被编译器忽略，不生成 CSS 自定义属性。
Vue 3.4+ 中 v-bind() 绑定 CSS 变量为什么必须写在 <style module> 里？
因为只有 <style module> 的作用域 CSS 才支持 v-bind() 声明的响应式变量自动注入到当前组件的 CSSOM 中。普通 <style> 或 <style scoped> 下，v-bind(color) 会被忽略——编译器压根不解析它，也不会生成对应的 CSS 自定义属性。
常见错误现象：v-bind() 写对了，但浏览器开发者工具里完全看不到对应 CSS 变量，元素上也没生效。十有八九是没用 module 属性。
-
<style module>是硬性前提，缺它不可 - 变量名必须是合法的 CSS 标识符（不能含空格、破折号开头等），否则编译报错
Invalid CSS custom property name - 绑定的 JS 变量需是响应式（
ref/computed/reactive的属性），否则值变化不会触发 CSS 变量更新
v-bind() 在 <style module> 中的写法和限制
语法很简单：直接在 <style module> 里写 color: v-bind(color);，但背后有几条隐形规则：
- 只能出现在声明块内（即
{}里），不能用于选择器、@media条件或嵌套规则中 - 不支持表达式，只接受一个响应式变量名，如
v-bind(theme.primary)会报错；必须先解构或映射成顶层变量：const primary = computed(() => theme.value.primary) - 类型必须可转为 CSS 字符串（
number会自动加px，string原样输出，null/undefined输出空字符串，可能引发样式断裂） - 若变量初始为
undefined，首次渲染时该 CSS 变量值为空，建议设默认值：const color = ref('#333')
<style module>
.text {
color: v-bind(color);
font-size: v-bind(fontSize);
--bg-hue: v-bind(hue);
background: hsl(v-bind(hue), 70%, 60%);
}
</style>
如何让 v-bind() 变量在子组件或全局样式中复用？
Module 级 CSS 变量默认只作用于当前组件的 <style module>，无法被子组件直接继承或引用。想跨组件共享，得手动“导出”：
vue-composition-api-best-practices
下载
Vue 3 组合式 API 与 最佳实践，涵盖代码组织、useXxx 模式、组合式函数设计、Store 集成、响应式优化及功能抽取。
立即学习“前端免费学习笔记（深入）”；
- 用
defineExpose暴露变量供父组件读取（仅限父子通信场景） - 更通用的做法：把需要共享的变量同步到 document.documentElement 上：
document.documentElement.style.setProperty('--primary-color', color.value) - 注意副作用：这种方式脱离了模块作用域，需自行管理生命周期（
onUnmounted清理），否则多个组件反复 set 同一变量会导致竞态 - 如果只是给子组件传主题色，推荐用 provide/inject + CSS 变量组合，比纯
v-bind()更可控
为什么改了响应式数据，CSS 变量没更新？
不是 Vue 响应失效，而是你可能踩中了这几个典型坑：
- 变量是通过
toRef或toRefs解构的，但原对象没用reactive包裹（比如用了普通对象），导致解构后失去响应性 - 在
setup()外部修改了ref值，但没用.value赋值（例如写成color = '#f00'而非color.value = '#f00'） - CSS 中写了
!important，覆盖了动态变量的层叠优先级 - 使用了
Object.freeze()或markRaw()包裹变量，阻止了响应式代理建立
最简单的验证方式：在 template 里加个 {{ color }}，看它是否随操作实时变化。如果模板里变了而样式没变，基本锁定在 CSS 写法或作用域问题上。
