最可靠方式是用@media (prefers-color-scheme: dark)配合:root中的CSS变量；必须先在:root定义明亮模式默认值，再用媒体查询覆盖暗色值，否则未匹配时变量未定义导致样式失效。
直接用 @media (prefers-color-scheme: dark) 配合 :root 变量，是最轻量、最可靠、浏览器原生支持的方案；别写 class 切换逻辑来模拟它，除非你明确需要手动覆盖系统偏好。
为什么不能把 CSS 变量定义在 @media 里再全局用
CSS 变量作用域是“声明处生效”，@media 块内定义的变量只在该块内部有效。写成这样是无效的：
:root {
--bg: #fff;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #1e1e1e; /* ✅ 正确：重设顶层 :root 的变量 */
}
.card {
--card-bg: #2d2d2d; /* ❌ 错误：这个 --card-bg 在外部无法访问 */
}
}必须把所有基础变量先在顶层 :root 中声明，默认值为浅色；深色规则只能是“重写”，不是“新增”。
- 变量名必须完全一致，否则不会覆盖
- 不要只改部分变量（比如改了
--bg却漏掉--border），组件会混用明暗色值 - 嵌套过深的 fallback（如
var(--a, var(--b, #000))）在低端设备上可能延迟计算
@media (prefers-color-scheme: dark) 必须单独、顶层、后置
它不提升选择器优先级，只靠层叠顺序生效。如果写在默认样式前面，或者被包裹在其他媒体查询里，就会失效：
立即学习“前端免费学习笔记（深入）”；
@media (max-width: 768px) {
@media (prefers-color-scheme: dark) { /* ❌ 旧版 Safari 直接忽略 */
:root { --bg: #121212; }
}
}正确写法是独立、顶层、且放在所有默认样式之后：
:root {
--bg: #ffffff;
--text: #333333;
--border: #e2e8f0;
}
/* ✅ 必须放在这之后 */
@media (prefers-color-scheme: dark) {
:root {
--bg: #121212;
--text: #e0e0e0;
--border: #334155;
}
}- 用 DevTools 的 Styles 面板检查：切换系统主题后，目标规则是否被划掉（未匹配）
- 若没划掉但颜色没变，大概率是选择器权重不够，或被
!important/ inline style 压制 - 不要给
:root加!important，否则 JS 后续更新变量会失效
如何避免首屏闪动和 SSR 场景下的白屏问题
服务端无法读取客户端系统偏好，Next.js/Nuxt 等框架首屏必然按默认主题输出 HTML，等 JS 执行 window.matchMedia 后才补上深色类——这个间隙就是闪动来源。
- 关键变量必须内联在
<head>的<style>中，不能外链加载 - HTML 根元素同步注入
data-color-scheme="dark"属性（服务端根据 User-Agent 或 hydration 逻辑） - 对
body或大面积色块加transition: background-color 0.2s, color 0.2s缓动（但慎用，可能引发重排） - 所有
var()调用必须带 fallback：background: var(--bg, #ffffff)，防止变量未定义时样式崩塌
第三方组件库的颜色错乱怎么修
Ant Design、Chakra UI、Mantine 这些库通常靠 JS 注入 class 或修改 :root 变量来切主题，和你的 @media 规则直接冲突。
- 统一入口：用更具体的选择器覆盖，比如
[data-theme="dark"] .ant-btn - 必要时在外层加 wrapper，并用
[data-theme="dark"] > .wrapper提升优先级 - 检查文档是否要求额外引入深色主题 CSS 文件（如 Chakra UI 的
css-reset补丁） - 禁用组件库的自动检测（如
useColorMode({ ssr: true })），改用你自己的:root变量体系
真正难的不是写对那几行 @media，而是让整套变量体系在 SSR、JS hydration、用户手动切换、系统偏好变更之间保持状态一致——变量本身没状态，状态全靠你用 localStorage + 内联 style + data- 属性协同维持。
