SCSS变量无法运行时切换，仅在编译期被替换为静态值；真正支持动态主题的是CSS自定义属性（如--primary-color），SCSS仅用于结构化生成var(--xxx)语句并配合JS通过data-theme或setProperty控制其值。
SCSS变量本身不能“一键切换”主题——它在编译时就被替换成固定值，运行时无法修改。真正能动态切换的，是 CSS 自定义属性（--primary-color），而 SCSS 的作用是帮你更安全、更结构化地生成这些 CSS 变量。
为什么不能直接用 SCSS 变量做运行时切换
SCSS 是预处理器，所有 $primary-color 在构建阶段就编译成具体颜色值（比如 #409eff），最终输出的 CSS 里根本不存在变量。用户点击按钮时 JS 想改 $primary-color？不可能，它早已消失。
常见错误现象：
– 写了 $theme: 'dark' 并在 SCSS 里 @if $theme == 'dark'，结果切换主题没反应
– 在 Vue 组件里绑定 :style="{ '--primary-color': theme.primary }"，但样式仍不更新（因为 SCSS 没参与运行时）
- SCSS 变量只用于开发期组织代码、减少硬编码、支持主题预设生成
- 真正响应式切换必须靠 CSS 自定义属性 + JS 控制
document.documentElement - 混淆两者会导致“改了变量但页面不变”的典型调试困境
正确做法：用 SCSS 生成多套 :root CSS 变量
把 SCSS 当作“变量工厂”，为每套主题生成对应的 CSS 自定义属性声明。例如：
立即学习“前端免费学习笔记（深入）”；
// themes/default.scss
:root {
--bg-color: #ffffff;
--text-color: #333333;
--primary-color: #409eff;
}
// themes/dark.scss
:root.dark {
--bg-color: #1a1a1a;
--text-color: #f5f5f5;
--primary-color: #79bbff;
}
关键点：
– 不要用 @mixin themeify 包裹整个样式块（容易污染全局、难调试）
– 每个主题文件只负责声明 :root 或 :root.xxx 下的变量，保持职责单一
– 所有组件样式统一用 var(--bg-color)，不写死颜色值
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 构建时引入全部主题文件（如
@import './themes/*.scss'），打包后 CSS 包含所有主题规则 - JS 只需切换
document.documentElement.classList.add('dark')，浏览器自动匹配对应 :root 规则 - 避免在 SCSS 中用
map-get动态查值——那仍是编译时行为，对运行时无效
UniApp / 小程序环境的兼容性注意点
微信小程序基础库 ≥2.7.0 支持 CSS 变量，但 H5 和 App 端表现一致，小程序端需额外验证：
- 不要用
document.documentElement.style.setProperty()直接设变量——小程序中可能不触发重绘 - 优先用 class 切换（
document.documentElement.classList.toggle('dark')），更稳定 - 避免在
scoped样式中覆盖:root变量（Vue 单文件组件中<style scoped>会加属性选择器，破坏 :root 作用域） - uni-app 的
vue.config.js或vite.config.ts需确保 SCSS 全局注入（通过css.preprocessorOptions.scss.additionalData）
主题持久化与初始化逻辑别漏掉
用户切完主题刷新页面又回默认色？这是最常被跳过的一步。
初始化时必须读取 localStorage，并同步设置 class：
const savedTheme = localStorage.getItem('theme') || 'light';
document.documentElement.setAttribute('data-theme', savedTheme);
// 注意：这里用 data-theme 而非 class，和 :root[data-theme="dark"] 规则对应
容易踩的坑：
– 在 Vue mounted 钩子中才读取 localStorage → 页面闪白/闪黑
– 用 class 切换但 CSS 规则是 :root[data-theme="dark"] → 完全不生效
– 没监听系统偏好（window.matchMedia('(prefers-color-scheme: dark)')），导致和系统设置冲突
真正的“一键切换”不是技术魔术，而是把 SCSS 当脚手架、CSS 变量当开关、JS 当扳手——三者各司其职，少一个环节都会卡在半路。
