皮肤切换的本质是通过给html元素添加class来批量替换CSS变量值，所有皮肤变量需定义在:root中且命名一致，JS仅操作document.documentElement.className并存入localStorage，消费端必须使用var()引用变量才能生效。
皮肤切换的本质是变量值的批量替换
CSS 变量（:root 中定义的 --color-primary、--bg-base 等）本身不带“皮肤”概念，所谓“多套皮肤”，就是为同一组变量名提供多组不同取值。切换皮肤 = 切换某一层级 CSS 作用域下的变量值，最稳妥的方式是通过给 <html> 或 <body> 添加 class 来触发不同皮肤的变量定义。
- 不要在 JS 中逐个修改
document.documentElement.style.setProperty()—— 维护成本高、易漏、无法利用 CSS 层叠和继承 - 避免用
@media或prefers-color-scheme自动切换代替手动切换逻辑 —— 它们解决的是系统偏好适配，不是用户主动选择 - 所有皮肤变量必须定义在相同作用域（推荐
:root），且命名完全一致，仅值不同
如何组织皮肤 CSS 并确保无冲突
把每套皮肤写成独立的 class 规则块，全部放在全局样式表中，靠 class 选择器优先级覆盖默认值。例如：
:root {
--color-primary: #007bff;
--bg-base: #ffffff;
}
html.skin-dark {
--color-primary: #0d6efd;
--bg-base: #1a1a1a;
}
html.skin-blue {
--color-primary: #0dcaf5;
--bg-base: #f0f9ff;
}
- 必须用
html.xxx而非.xxx—— 避免被局部 class 意外覆盖，保证全局生效 - 所有皮肤规则必须写在默认
:root之后，否则会被覆盖 - 不要用
!important—— CSS 变量不支持!important，写了也无效 - 变量名保持语义化（如
--text-secondary），别用--dark-bg-1这类绑定具体皮肤的命名
JS 切换时该操作哪个节点、存哪里
切换只需改 document.documentElement.className，同时把当前皮肤名存在 localStorage 里，刷新后还原：
function switchSkin(name) {
document.documentElement.className = `skin-${name}`;
localStorage.setItem('preferred-skin', name);
}
// 页面加载时读取
const saved = localStorage.getItem('preferred-skin') || 'default';
document.documentElement.className = saved === 'default' ? '' : `skin-${saved}`;
- 不要用
classList.add()/remove()—— 多皮肤共存会导致 class 堆积，比如skin-dark skin-blue，后者不会覆盖前者 - 如果默认皮肤不需要 class，就让
className = ''，而不是留一个skin-default—— 减少冗余 - 注意 SSR 场景：服务端渲染时无法读
localStorage，需配合data-属性或服务端注入初始 class
为什么有些颜色没变？检查这三处
常见“切换了但没生效”的原因往往不在 JS 或变量定义，而在消费端：
立即学习“前端免费学习笔记（深入）”；
- 组件内写了硬编码颜色（如
color: #007bff）—— 必须替换成color: var(--color-primary) - 用了简写属性（如
background: #fff url(...) no-repeat）—— 如果只换背景色，url(...)会丢失，应拆成background-color和background-image单独控制 - 某些第三方组件库内联了 style（如 Ant Design 的
style="color: rgb(0, 123, 255)"）—— 这类无法被 CSS 变量接管，需通过其主题配置 API 或 CSS 覆盖
皮肤切换不是“设个变量就完事”，关键在消费侧是否真正依赖变量。变量定义再整齐，只要某个按钮还写着 #333，它就不会跟着变。
