深色模式生效的关键是CSS选择器匹配+已定义规则+层叠顺序，需用:root变量统一管理主题色并同步localStorage与系统偏好。
class 属性本身不能“动态切换”，真正起作用的是 CSS 选择器配合 JavaScript 控制
很多人以为直接操作 class 属性就能让深色模式自动生效，其实不然。HTML 的 class 只是字符串容器，它本身不触发样式变化；真正生效的是 CSS 中已定义的对应规则（比如 .dark .btn），以及浏览器对这些规则的重新计算。所以关键不是“有没有 class”，而是“有没有匹配的 class + 对应的 CSS 规则 + 正确的层叠顺序”。
实操建议：
立即学习“前端免费学习笔记（深入）”；
anything-to-html
下载
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 把深色模式的样式统一写在
.dark或.theme-dark这类顶层 class 下，例如：.dark body { background: #1e1e1e; color: #e0e0e0; } .dark .card { background: #2d2d2d; border-color: #444; } - 避免用
!important覆盖默认样式，容易导致后续维护混乱；优先靠选择器权重和声明顺序控制 - 不要只给
<body>加 class，确保根元素（如<html>）也有，方便 :root 变量注入
必须配合 :root CSS 变量才能实现真正的主题一致性
纯 class 切换颜色值容易遗漏、难维护。现代深色模式适配的核心是 CSS 自定义属性（--color-bg、--color-text 等），它们能被 JavaScript 动态修改，也能被 CSS 规则批量响应。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 在
:root中定义默认（浅色）变量，在.dark :root中覆盖为深色值 - 所有组件样式都使用
var(--color-bg)，而不是硬编码#ffffff - JavaScript 切换时只需改
document.documentElement.classList.toggle('dark')，变量会自动重算 - 注意：CSS 变量不继承，但可被后代选择器读取；如果子元素需要独立主题逻辑，用
inherit或额外 class 控制
localStorage + class 切换必须在 DOM 加载完成后执行，否则会闪屏
页面首次加载时，如果 JS 在 CSS 后执行，浏览器会先按默认主题渲染一次，再切到深色，造成白/黑屏闪烁（FOUC）。这不是 bug，是渲染流程决定的。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 把主题判断逻辑提前到
<head>内的内联 script 中，或使用document.documentElement.classList.add('dark')同步执行 - 读取
localStorage.getItem('theme')后立即应用 class，不要等DOMContentLoaded - 配合
prefers-color-scheme做 fallback：若 localStorage 为空，读系统偏好；否则以 localStorage 为准 - 服务端渲染（SSR）场景下，需在 HTML 模板中直接输出对应 class，彻底避免客户端闪屏
toggleDark() 函数里别漏掉 localStorage 和媒体查询监听的同步更新
用户手动点击切换后，仅改 DOM class 是不够的。如果不存 localStorage，刷新就回退；如果不监听系统偏好变更，系统设置改了页面却不动。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 切换函数中必须包含：
localStorage.setItem('theme', newTheme); document.documentElement.classList.toggle('dark', newTheme === 'dark'); - 用
window.matchMedia('(prefers-color-scheme: dark)')监听系统变化，并在回调中调用同一套切换逻辑 - 避免重复监听：检查
matchMedia返回对象是否已有addEventListener绑定 - 移动端 Safari 对
matchMedia的支持较晚（iOS 14+），旧版本需降级为仅依赖 localStorage
--color-bg 只写在 .dark 规则里，结果非 dark 状态下该变量未定义，var(--color-bg, #fff) 的 fallback 会被频繁触发，导致颜色不可控。变量必须在 :root 中声明默认值，再在 .dark :root 中覆盖。 
