在基于 CSS 自定义属性和 HTML class 切换暗色/亮色模式的网站中，若 JavaScript 在 DOM 加载完成后才应用主题类，会导致页面首次渲染时短暂显示默认样式，即“闪白”或“闪黑”现象（FOUC）。本文提供一种简单可靠的解决方案：将主题初始化逻辑提前至 中同步执行。
在基于 css 自定义属性和 html class 切换暗色/亮色模式的网站中，若 javascript 在 dom 加载完成后才应用主题类，会导致页面首次渲染时短暂显示默认样式，即“闪白”或“闪黑”现象（fouc）。本文提供一种简单可靠的解决方案：将主题初始化逻辑提前至 `
` 中同步执行。
要彻底避免主题切换过程中的Flash of Unstyled Content（FOUC），关键在于确保 元素在浏览器开始解析并渲染 之前，就已经具备正确的主题 class（如 lightMode 或 darkMode）。当前代码中，updateColorMode() 被挂载在 document.onreadystatechange 的 'complete' 阶段执行——此时整个 DOM 已构建完毕、CSS 已加载、甚至部分 HTML 内容可能已被绘制，因此 :root 的默认样式（无 class 时的 --background 和 --text）必然先短暂生效，造成视觉闪烁。
✅ 正确做法：将主题初始化逻辑移入 ，并以同步、阻塞方式运行。
具体实现如下：
-
在
中内联一个简短的<script></script>块（不依赖模块加载器），立即读取 localStorage 或媒体查询，并直接设置 class：
<!-- 其他 meta、link 标签 -->
<script>
// 同步检测并应用初始主题（在任何 CSS 渲染前执行）
(function() {
const root = document.documentElement;
let mode = 'light'; // 默认回退值
// 优先检查 localStorage
if (typeof localStorage !== 'undefined') {
const saved = localStorage.getItem('colorMode');
if (saved === 'dark' || saved === 'light') {
mode = saved;
} else if (saved === 'auto') {
mode = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}
} else {
// 无 localStorage 时降级为系统偏好
mode = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}
root.classList.add(`${mode}Mode`);
// 可选：为 SSR/SEO 友好性，也可同时设置 data-theme 属性
root.setAttribute('data-theme', mode);
})();
</script>
-
保留原有模块化逻辑，但仅用于后续交互更新（如用户手动切换、系统偏好变更监听等）。此时
updateColorMode()不再承担“首屏主题设置”职责，而是专注响应式更新，可安全保留在DOMContentLoaded或模块导入后调用。
⚠️ 注意事项：
- ❌ 避免使用
import或async/defer脚本加载主题初始化逻辑——它们无法保证在 HTML 解析早期执行； - ✅ 内联脚本无需等待 DOM，浏览器解析到即执行，能确保
class 在首个渲染帧前就位； - ✅ 若使用服务端渲染（SSR）或静态站点生成器（如 Astro、Next.js），更推荐在服务端根据请求头或默认策略直接注入 class，实现零客户端 JS 闪动；
- ✅ 为增强可维护性，可在 CSS 中添加
transition: background-color 0.2s, color 0.2s缓解切换突兀感（但不能解决 FOUC 根源）。
总结：FOUC 的本质是样式应用时机晚于首次渲染。通过将初始主题判定逻辑前置到 内联脚本中，我们绕过了事件循环与模块加载延迟，让浏览器从第一行 HTML 开始就拥有正确的上下文样式，从而实现真正无缝的主题加载体验。
