直接修改 :root 变量可全局换色，但须确保所有颜色均用 var(--primary-color) 替换，且无 JS 硬编码、内联样式或第三方库绕过；需手动替换 background-color、color、border-color、box-shadow、outline-color、伪元素 ::before/::after、SVG 的 fill/stroke、表单状态样式及第三方库未启用变量支持的部分；加载顺序须在框架 CSS 后，变量名拼写准确、无 !important、语法规范；JS 切换应通过 setAttribute('data-theme', 'dark') 触发 CSS 选择器重定义，而非仅 setProperty。
直接改 :root 里的变量值就能全局换色，但前提是所有用到颜色的地方都已替换成 var(--primary-color)，且没有 JS 硬编码、内联样式或第三方库绕过变量链。
哪些地方必须手动替换为 var()
浏览器不会自动扫描旧样式去替换颜色值。你得逐个检查并替换以下位置的硬编码颜色：
-
background-color、color、border-color、box-shadow、outline-color中的#3b82f6或blue等写死值 -
::before和::after伪元素中的background和color—— 尤其是图标类装饰，极易遗漏 -
svg标签内的fill和stroke，必须显式写成fill: var(--primary-color)，否则不响应 - 表单控件的状态样式：
input:focus、select:disabled、button:active、textarea:hover - 第三方 UI 库（如 Ant Design、Element Plus）内部 class 若未开启 CSS 变量支持，则不会响应你的
--primary-color
:root 覆盖必须满足的加载顺序和语法条件
Bootstrap、Tailwind 等框架编译后的 CSS 文件里，:root 已声明默认变量。你自定义的覆盖必须「后加载、拼写准、无语法错」：
- 你的
:root块必须放在框架 CSS 文件之后，比如在<head>中排在bootstrap.min.css下方 - 变量名必须完全匹配：Bootstrap 5.3 是
--bs-primary，不是--primary或--bs-color-primary - 不能加
!important：--bs-primary: red !important整行会被浏览器忽略 - 冒号后要空格，结尾要分号，大小写敏感 ——
--Brand-Color无效，--brand-color才合法 - 避免被更高优先级选择器覆盖，比如
.theme-dark :root会压过普通:root
JS 切换时为什么 style.setProperty 没反应
很多人调用 document.documentElement.style.setProperty('--brand-color', '#e63946') 后页面没变化，问题不在方法本身，而在作用域和触发逻辑：
立即学习“前端免费学习笔记（深入）”；
-
style.setProperty()只修改style属性上的变量，无法触发动态主题切换所需的[data-theme="dark"] :root重定义逻辑 - 正确做法是设置属性：
document.documentElement.setAttribute('data-theme', 'dark')，让 CSS 选择器自己接管变量重赋值 - 若用了
localStorage记住偏好，务必等 DOM 加载完成再读取并设置，否则首屏渲染会先按默认主题 - 频繁调用
setProperty改多个变量会触发多次重排重绘，建议一次性设完，而不是循环调用
容易被忽略的“边缘但高频”失效点
换肤失败往往不出现在主按钮或标题上，而是卡在这几个地方：
- SVG 图标颜色（尤其是通过
background-image: url("data:image/svg...")内联的，fill无法继承变量） - 伪元素中用
content: "●"配合color显示的标记点 - 内联
style属性（如<div style="color: #333">），它优先级高于var() - 第三方组件（如图表库 ECharts、地图库 Leaflet）的 canvas 渲染层，CSS 变量对其完全无效
- 使用了
color-mix()或hwb()等新函数但未提供 fallback，旧浏览器直接退成透明或默认色
