SCSS变量仅编译期存在，无法直接转为运行时CSS变量；必须用#{}插值将Sass变量值导出到:root中的--xxx声明，并通过@media (prefers-color-scheme: dark)显式覆盖深色模式值。
不能直接“转”，只能用 SCSS 生成 CSS 自定义属性声明。 SCSS 变量（如 $primary）在编译后就消失了，浏览器根本看不到；真正起作用的是你在 :root 里写的 --primary 这类 CSS 自定义属性。所谓“批量转”，本质是让 SCSS 帮你把一堆 $ 变量自动输出成对应的 -- 声明。
为什么不能用 @if $theme == 'dark' 控制 :root 变量值
Sass 的 @if 是编译时逻辑，@media (prefers-color-scheme: dark) 是运行时媒体查询——两者阶段不同，无法嵌套联动。你写：
:root {
--color-bg: #ffffff;
}
@if $theme == 'dark' {
:root { --color-bg: #111827; }
}
这段代码编译后只会保留一个 :root 块（取决于 $theme 当前值），根本不会生成媒体查询。要支持系统级深色模式，必须显式写出 @media (prefers-color-scheme: dark)，且它内部只能改 -- 值，不能包含 Sass 函数或条件。
用 map + @each 批量输出 :root 和媒体查询
把主题数据存在 $themes map 里，再用 @each 遍历生成两套变量声明：
立即学习“前端免费学习笔记（深入）”；
-
$themes定义语义化键名（如bg、text-primary），避免硬编码颜色值 - 主
:root输出 light 主题值，@media块内覆盖 dark 主题值 - 所有
#{map-get($theme-map, key)}必须是纯字符串或颜色值，不能带lighten()等函数——Sass 在此处已无上下文
示例：
$themes: (
light: (
bg: #f9fafb,
text-primary: #1f2937,
),
dark: (
bg: #111827,
text-primary: #f9fafb,
)
);
:root {
--bg: #{map-get(map-get($themes, light), bg)};
--text-primary: #{map-get(map-get($themes, light), text-primary)};
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #{map-get(map-get($themes, dark), bg)};
--text-primary: #{map-get(map-get($themes, dark), text-primary)};
}
}
SCSS 变量和 CSS 自定义属性混用的陷阱
常见错误是试图在 Sass 函数中传入 var(--x)，比如：
.btn {
color: lighten(var(--text-primary), 10%); // ❌ 编译失败：lighten() 需要编译期确定的颜色值
background: var(--bg); // ✅ 正确：直接使用
}
记住：
-
$变量只用于组织源码、减少重复、做主题预设 -
--变量才是运行时可读写、可动画、可被 JS 修改的“真变量” - 所有组件样式里必须写
color: var(--text-primary)，而不是color: $text-primary - 如果要用
calc()或过渡效果，确保--值本身是合法单位（如--space-md: 12px），而非颜色
最易被忽略的一点：构建工具（如 PostCSS 插件）可能默认移除未命中条件的 @media (prefers-color-scheme: dark)，导致深色变量不生效——务必检查最终生成的 CSS 文件里是否真实存在该媒体查询块。
