必须在脚本加载后立即执行matchMedia监听，置于<head>顶部内联script中，读取初始状态并初始化data-theme；用themeMode状态隔离自动与手动切换逻辑；编辑器需穿透Shadow DOM或提升样式权重；localStorage存取须严格校验字符串值。
matchMedia监听系统偏好必须在脚本加载后立刻执行
编辑器首次渲染前，系统暗色设置可能已经生效，但若等到DOMContentLoaded才注册监听，会错过初始状态，导致首屏亮色、闪一下再变暗——用户感知就是“错乱一帧”。
实操建议：
- 把
window.matchMedia("(prefers-color-scheme: dark)")调用和addEventListener写在内联<script>中，放在<head>最顶部（早于任何 CSS 或外部 JS） - 立即读取
mediaQuery.matches，并用document.documentElement.dataset.theme = mediaQuery.matches ? "dark" : "light"初始化 - 保存
mediaQuery实例引用，后续手动切换时调用mediaQuery.removeEventListener，避免重复绑定
手动切换必须隔离自动逻辑，用 themeMode 状态控制
用户点一次“切深色”，结果 2 秒后又因系统监听器触发变回亮色——这是没隔离自动与手动行为的典型表现。
关键不是禁用监听，而是引入明确的状态标识：
立即学习“前端免费学习笔记（深入）”；
- 定义
let themeMode = "auto"（可选值："auto"/"light"/"dark"） - 初始时按
localStorage.getItem("theme") || (系统匹配结果 ? "dark" : "light")设值，并写入localStorage - 按钮点击后：设
themeMode = "dark"，移除mediaQuery监听，再执行document.documentElement.dataset.theme = "dark" - 加一个「恢复自动」按钮，重置
themeMode为"auto"，并重新绑定mediaQuery
编辑器组件样式必须穿透 Shadow DOM 或提升选择器权重
CodeMirror、Monaco、ProseMirror 等编辑器常把内容渲染在 Shadow Root 里，或用高权重内联样式覆盖主题。此时仅改html[data-theme="dark"]对它们无效。
常见失效点和对策：
- Shadow DOM 内部不继承外部
:root变量，需用adoptedStyleSheets动态注入主题 CSS，或在 Shadow Root 初始化时手动设置style.setProperty() - 行号、工具栏、弹窗等 UI 组件往往独立维护 class，不能只靠全局
data-theme；需统一注入主题上下文（如 React Context 或自定义事件），让各模块响应变更 - CSS 规则必须带足够权重：用
html[data-theme="dark"] .cm-line，别只写.dark .cm-line；若用 Tailwind，得配合dark:前缀 +data-theme属性双重控制
localStorage 存值必须做 null 判断，且不能存布尔
localStorage.getItem("theme")返回null而非undefined，直接赋给dataset.theme会导致data-theme="null"，CSS 选择器[data-theme="dark"]完全不匹配。
正确写法只有这一种模式：
- 读取：
const saved = localStorage.getItem("theme"); document.documentElement.dataset.theme = saved === "dark" || saved === "light" ? saved : "light"; - 写入：
localStorage.setItem("theme", "dark")—— 永远用字符串，不用JSON.stringify或布尔 - 别忘了同步更新
<meta name="color-scheme" content="light dark">的content属性，否则地址栏、表单控件颜色仍为亮色
#000或style.color="black"的旧组件——它们得一个个找出来，改成var(--text-primary)，否则再完善的切换逻辑也白搭。 
