CSS变量命名规范:推荐使用Kebab-case的原因

在CSS自定义属性（常称为CSS变量）的使用中，有一个看似简单但至关重要的规则：变量名必须以两个连字符--开头，且仅支持小写字母加连字符（kebab-case）格式。例如，--btn-primary-bg合法，而--userName或--user_name完全无效，浏览器会直接忽略。

CSS变量名必须用--前缀，不支持驼峰或下划线

这不是风格建议，而是语法强制要求。CSS规范明确规定，自定义属性名必须以--开头，后续部分必须是“标识符”。此标识符不能包含大写字母、空格、点号或括号等字符。因此，--user-name是唯一正确的写法。

如果误用了--mainColor或--header_bg，会怎样？在开发者工具中，它们通常被标记为“无效属性”。控制台可能不报错，但样式不会生效，后续使用var(--header_bg)时，只会返回默认的initial值，问题十分隐蔽。

• --后面的第一个字符不能是数字，所以--1col-layout非法。
• 连字符-是原生CSS唯一允许的分隔符，且前后必须有字母或数字（例如--btn-primary，--btn-）。
• 大小写敏感：--Text和--text被视为两个不同变量，但只有全部小写的--text符合规范并可被解析。

kebab-case与HTML/CSS生态天然对齐

为何推荐kebab-case？因为它并非特立独行，而是与整个前端生态保持一致。观察CSS类名、HTML属性、伪类选择器（如:first-child）、自定义HTML元素（如），无一例外采用小写加连字符风格。CSS变量沿用此惯例，是最省力、最自然的选择。

举例：若编写按钮组件，HTML中为，对应CSS可能是.btn--primary { background: var(--btn-primary-bg); }。变量名和类名结构完全对应，排查样式问题时一目了然。

• 避免混用：不要在同一个项目中同时出现--btnPrimaryBg（非法）和--btn-primary-bg（合法），后者是唯一可行路径。
• 工具链友好：PostCSS插件、CSS-in-JS库（如Emotion）默认按kebab-case解析变量。若使用其他风格，需额外配置转换逻辑，增加复杂度。
• 开发体验：VS Code等编辑器对--xxx-yyy-zzz格式变量提供语法高亮和自动补全，而对驼峰写法可能“视而不见”。

与JavaScript交互时的大小写转换陷阱

当通过JavaScript动态操作CSS变量时，常见陷阱会出现。JS使用getComputedStyle或style.setProperty读写变量，此时传入的变量名必须严格匹配CSS中声明的字符串形式。

问题是，JavaScript本身的变量命名不支持连字符，所以必须用字符串字面量传递：

element.style.setProperty('--text-color', '#333'); //  字符串字面量
element.style.setProperty('--textColor', '#333'); //  CSS端根本不存在此变量

容易踩坑的地方在于，开发者有时会试图在JS中用驼峰命名变量，再转换到CSS：

• const textColor = '--text-color'; —— 正确，用字符串封装。
• const textColor = '--textColor'; —— 错误，CSS无法识别。
• 从JS主题对象解构时硬套驼峰：const { primaryColor } = theme; → setProperty('--primaryColor', primaryColor) → 结果样式失效。

文件名、URL、类名、变量名统一用kebab-case是最小认知成本方案

在前端项目中，一个视觉模块常横跨多个层面：CSS文件可能叫header-nav.css，HTML中类名是class="header-nav"，JS操作的变量是--header-nav-height，甚至路由URL也是/header-nav。若全部统一使用kebab-case，开发者无需在不同上下文间进行任何脑内格式转换，认知负担降到最低。

从性能和兼容性角度看，命名风格影响微乎其微。但从维护成本看，差异巨大。假设某天需要全局替换某个主题色，若命名统一，只需搜索一次--header-nav即可精准命中所有相关变量、类和文件。若混用了headerNav、header_nav、header-nav等多种风格，则需进行多轮搜索替换，既低效又易错。

真正复杂的情况常出现在团队协作和历史遗留项目中。例如，老项目可能已存在--BGColor这种不符合规范的写法，它可能依赖特定构建工具“悄悄修复”才可运行。一旦升级浏览器版本或切换打包工具，这些变量可能突然失效。遇到此情况，先别急着修改变量名，首要任务是确认它是否真的被CSS引擎成功解析并应用。