transition必须写在基础状态规则里，不能只放在.dark-theme类中；否则默认态无过渡声明，切换时会瞬间跳变导致闪屏，正确做法是将transition声明置于默认样式中并确保两端属性值明确可计算。
transition 必须写在基础状态规则里，不能只放在 dark 类中
浏览器只会对「从一个明确值变到另一个明确值」的属性做平滑过渡。如果 transition 只写在 .dark-theme 里，那默认状态下没有过渡声明，切换时就会瞬间跳变——这就是“闪屏”的直接原因。
正确做法是把 transition 放在默认样式（即未加主题类时）中：
body {
background-color: #ffffff;
color: #333333;
transition: background-color 0.4s ease, color 0.4s ease;
}
<p>body.dark-theme {
background-color: #121212;
color: #e0e0e0;
}- 所有参与过渡的属性（如
background-color、color、border-color）必须在默认态和.dark-theme态都定义具体值 - 避免用
transparent或inherit作为其中一端，它们可能导致过渡失效或行为不可控 - 推荐时长范围：300–450ms；
ease-in-out比ease更柔和，适合主题切换
CSS 变量本身不能被 transition 直接过渡
如果你用 :root + @media (prefers-color-scheme: dark) 管理颜色变量，然后在样式中写 background-color: var(--bg-color)，会发现切换时没有过渡效果——因为 CSS 变量的更新是原子性的，transition 不作用于变量名，只作用于最终计算出的属性值。
解决路径只有两个：
立即学习“前端免费学习笔记（深入）”；
- 放弃变量，直接在
body和body.dark-theme中写死颜色值（最简单、最可靠） - 保留变量，但把
transition搬到每个实际使用变量的元素上，并确保两端都是可动画的颜色值（如#ffffff↔#121212），而非变量引用 - 不推荐用
@property做变量过渡：兼容性差（Chrome ≥ 101，Safari 不支持），且需额外注册语法，增加维护成本
data-theme 切换比 @media 更可控，但 CSS 选择器优先级要写对
用户手动切换主题时，@media (prefers-color-scheme: dark) 完全失效——它只响应系统设置。真正起效的是基于 [data-theme="dark"] 的覆盖规则，但很多人写错位置：
[data-theme="dark"] :root {
--bg-color: #121212;
--text-color: #e0e0e0;
}这不行。:root 是伪类，无法被属性选择器前置修饰。正确写法是：
/* 默认变量 */
:root {
--bg-color: #ffffff;
--text-color: #333333;
}
<p>/<em> 用户强制设为深色时覆盖 </em>/
[data-theme="dark"] {
--bg-color: #121212;
--text-color: #e0e0e0;
}</p><p>body {
background-color: var(--bg-color);
color: var(--text-color);
transition: background-color 0.4s ease, color 0.4s ease;
}-
[data-theme="dark"]必须作用于<html>元素（即document.documentElement），否则无法影响:root下的变量继承 - 不要混用
@media和[data-theme]控制同一组样式，优先级和触发时机容易打架 - 手动切换后记得同步更新
<meta name="color-scheme">，否则原生表单控件（如<input>）不会跟着变
监听系统主题变化必须用 addEventListener，不能只靠初始 matchMedia.matches
window.matchMedia('(prefers-color-scheme: dark)').matches 只返回当前快照，不响应后续变化。用户在页面开着时切系统主题，网页毫无反应，除非刷新。
必须显式监听：
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
function handleColorSchemeChange(e) {
const newTheme = e.matches ? 'dark' : 'light';
// 仅当用户没手动选过主题时，才按系统偏好更新
if (!localStorage.getItem('theme')) {
document.documentElement.dataset.theme = newTheme;
}
}
mediaQuery.addEventListener('change', handleColorSchemeChange);
// 初始调用一次，确保加载时也对齐
handleColorSchemeChange({ matches: mediaQuery.matches });- 监听回调里一定要检查
localStorage是否存在用户偏好，否则手动选择会被系统设置覆盖 - 别漏掉初始调用——
addEventListener不会回溯已发生的匹配状态 - 错误写法：
mediaQuery.addListener(...)已废弃；'prefers-dark-scheme'是无效媒体查询关键字
过渡是否生效，最终取决于你有没有让浏览器看到「起点值」和「终点值」之间的明确映射。变量、媒体查询、dataset 三者混用时，最容易忽略的是：CSS 层叠顺序、初始化时机、以及哪些值真的能被动画引擎识别。
