CSS.registerProperty是唯一赋予CSS自定义属性类型语义的方式，必须在Chromium中通过JS同步调用；纯CSS变量如--my-var: 10px本质为字符串，不支持类型校验与插值动画，仅注册后才具备syntax约束、initialValue校验、inherits控制及transition/@keyframes支持。
CSS.registerProperty 是唯一能真正赋予 CSS 自定义属性“类型语义”的方式，但必须在 Chromium 浏览器中运行，且不能用 HTML 声明，只能通过 JS 同步调用。
为什么直接写 --my-var: 10px 不够用
纯 CSS 变量（:root { --size: 10px; }）本质是字符串容器。浏览器不验证值是否合法，也不支持基于类型的插值动画——比如 transition: --size 0.3s 会静默失效，因为 "10px" → "20px" 被当作两个不可插值的字符串处理。
只有通过 CSS.registerProperty 显式声明 syntax 和 initialValue，浏览器才把它当“真属性”对待，支持动画、继承控制和语法校验。
CSS.registerProperty 的必需参数与常见错误
调用时漏掉任何一项都会导致注册失败或降级为普通变量：
立即学习“前端免费学习笔记（深入）”；
-
name必须带双短横线前缀，如'--radius'；写成'radius'或'--radius--'都无效 -
syntax不能为空字符串；若想接受任意值，用'*'，但这样就失去类型约束；常用值包括'<length>'、'<color>'、'<angle>' -
initialValue必须符合syntax类型，比如syntax: '<color>'时写initialValue: '123'会报错并跳过注册 -
inherits默认为true，但多数自定义属性（如主题色、尺寸）应设为false，避免意外继承污染子元素
正确示例：
CSS.registerProperty({
name: '--primary-color',
syntax: '<color>',
inherits: false,
initialValue: '#3b82f6'
});
注册时机比你想象中更关键
注册必须发生在 CSS 使用该变量之前，否则浏览器解析样式时会忽略类型信息，只当普通字符串处理：
- 不要把注册脚本放在
<body>底部——DOM 渲染可能已开始，:root中的--primary-color已被解析完毕 - 推荐在
<head>中用<script defer>加载，确保 DOM 构建完成前注册完成 - 避免在
window.onload或DOMContentLoaded里注册——太晚，样式已计算完毕 - 如果变量用于
@keyframes或paint()，更要提前注册，否则动画帧或绘制逻辑无法识别类型
兼容性兜底和调试技巧
Firefox 和 Safari 完全不支持 CSS.registerProperty，调用会直接抛 TypeError: CSS.registerProperty is not a function：
- 务必用
if ('registerProperty' in CSS)包裹注册逻辑，否则旧浏览器会中断 JS 执行 - 注册后可通过
getComputedStyle(document.documentElement).getPropertyValue('--primary-color')检查是否生效；若返回空字符串，大概率是注册失败或时机不对 - Chrome DevTools 的 Elements 面板里，已注册属性会在“Computed”标签下显示为带类型标识（如
color），未注册则只显示原始字符串值 - 动画失效时优先检查：是否用了
@property（CSS 规则写法）？那是另一套语法，仅限 Chrome 110+，且和CSS.registerProperty互斥，不能混用
最易被忽略的一点：注册本身不触发重绘，已存在的元素不会自动响应新类型；需要手动触发一次样式变更（比如改个无关的 opacity）才能让浏览器重新评估变量插值能力。
