纯 CSS 无法实现一键切换深色模式，必须用 JavaScript 控制 CSS 变量并持久化用户选择；prefers-color-scheme 是只读媒体查询，仅响应系统偏好，不能被手动触发或修改。
纯 CSS 无法实现“一键切换”——必须配合 JavaScript 才能响应用户主动点击操作。 prefers-color-scheme 只读系统偏好，它本身不提供开关能力；所谓“一键”，本质是覆盖系统判断、写入用户显式选择，并同步更新 CSS 变量或 class。
为什么 prefers-color-scheme 不能直接做按钮开关
该媒体查询是只读信号：浏览器根据系统设置自动匹配 @media (prefers-color-scheme: dark) 或 light，你无法用 CSS 触发它变化。用户点“切深色”按钮时，系统偏好可能仍是 light，此时 CSS 媒体查询根本不会生效。
- 只靠 CSS 写
@media (prefers-color-scheme: dark) { ... }，只能响应系统级切换，刷新后还原 - 用户手动切换后页面闪一下（先按系统色渲染，再 JS 注入样式），说明没提前控制变量或 class
- 把
prefers-color-scheme嵌套在 JS 动态插入的 style 标签里？insertRule不支持该媒体查询，会静默失败
正确做法：用 JS 控制 :root 变量 + CSS 变量兜底
核心是让 JS 改变根变量值，CSS 全局用 var(--color-bg) 引用，避免 class 切换引发重排或样式泄漏。
- 初始化时优先读
localStorage.getItem('themeMode')， fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 切换时同时执行：
document.documentElement.style.setProperty('--color-bg', '#121212')和localStorage.setItem('themeMode', 'dark') - CSS 中不要只写
@media (prefers-color-scheme: dark)，而是把所有主题变量都定义在 :root，并用 JS 覆盖——这样即使媒体查询不生效（如旧 Safari），变量仍有效 - 注意变量作用域：
document.body.style.setProperty不会影响var()查找，必须用document.documentElement.style或:root上的样式规则
如何避免深色模式下边框/聚焦 outline 刺眼
深色背景上直接用 #000 边框或 outline: 2px solid #fff 会导致视觉跳脱，尤其 focus 状态。
立即学习“前端免费学习笔记（深入）”；
- 别简单反色：浅色下的
#ccc对应深色不是#333，而是#444或带轻微灰度的#3a3a3a - 聚焦 outline 推荐用
outline: 2px solid var(--focus-ring)，并在 JS 切换主题时一并设--focus-ring: #6200ee（符合 WCAG 对比度） - border-color 建议用 HSL 表达：比如
--border: hsl(210, 8%, 75%)→ 深色下改为hsl(210, 12%, 25%)，比硬写十六进制更易维护明度梯度
用户手动切换时 localStorage 的坑
Safari 私密模式默认禁用 localStorage，直接调用会抛 QuotaExceededError，导致切换失效且无提示。
- 必须包 try/catch：
try { localStorage.setItem(...) } catch { sessionStorage.setItem(...) } - 不要存布尔值如
true，存字符串'dark'/'light'/'auto'，方便后续扩展护眼模式 - 监听系统变化时，仅当
themeMode === 'auto'才执行 JS 变量更新，否则用户显式选择应始终优先 - 服务端渲染（SSR）场景下，首次 HTML 必须含正确
style内联变量，否则首屏仍是系统色，造成明显闪动
最易被忽略的一点：CSS 变量的初始值必须有意义。如果 :root { --color-bg: ; } 留空，后续 JS 设置前所有 var(--color-bg) 都退化为 inherit 或 transparent，页面直接不可用——哪怕只有一行，也要写默认值。
