纯CSS无法修复后台暗黑模式问题，因@media只响应系统偏好，不支持手动切换、localStorage持久化及SSR首屏一致；必须用JS同步设置data-theme、重定义:root变量、调用update()并声明color-scheme。
纯 CSS 无法修复后台系统中因 JS 主动干预、框架耦合或 SSR 不一致导致的暗黑模式切换问题——@media (prefers-color-scheme: dark) 只能被动响应系统偏好，不处理用户手动切换、localStorage 持久化、服务端首屏主题注入等关键环节。
为什么 @media (prefers-color-scheme: dark) 在后台系统里基本失效
后台系统通常有明确的用户操作入口（如顶部“? 切换暗色”按钮），且需记住上次选择。而媒体查询是只读快照：它在页面加载时检查一次系统设置，之后完全不响应任何运行时变化。
- 用户点按钮切暗色 → 系统仍是亮色 →
@media规则不触发 - 刷新页面 → localStorage 有
"dark"，但 CSS 没读取它 → 回退到系统偏好 - Next.js / Vue SSR 首屏渲染时，
window.matchMedia未定义 → 服务端吐出亮色 HTML，客户端再 JS 覆盖 → 闪屏
data-theme 类必须配合 :root 变量重声明才生效
CSS 自定义属性不会监听 HTML 属性变更。仅执行 document.documentElement.setAttribute('data-theme', 'dark')，var(--bg-surface) 的值仍为初始浅色值。
- 所有暗色变量必须显式写在
html[data-theme="dark"] :root块内，例如：html[data-theme="dark"] :root { --bg-surface: #1a1a1a; --text-primary: #e0e0e0; } - 不能只靠
.dark类 + 组件内覆盖，否则第三方组件（如 Ant Design 表单）颜色不变 - Bootstrap 5.3+ 用户必须调用
bootstrap.Theme.getOrCreateInstance().update()，否则 CSS 变量不重算
后台系统必须声明 color-scheme: light dark，否则原生控件错乱
这个声明不改变你的 CSS，但它强制浏览器用系统暗色渲染 <input> 边框、<select> 箭头、滚动条、<canvas> 默认边框等——后台表单密集，漏掉这行会导致一半 UI 在深灰背景上显示亮白边框，对比刺眼。
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
立即学习“前端免费学习笔记（深入）”；
- 必须写在
:root或html上，不能只写在body或组件里 - 旧版 Safari（iOS 13.2 以下）不支持，但现代后台系统可安全启用
- 若用 Tailwind，需确认
theme.extend.colorScheme已配置，且html标签有对应 class
SSR/CSR 混合场景下，闪屏的根因和唯一解法
闪屏不是 CSS 写得慢，而是首屏 HTML 主题与 JS 加载后主题不一致。浏览器先按服务端输出渲染，再被 JS 覆盖。
- Next.js：在
getServerSideProps中读取请求头Sec-CH-Prefers-Color-Scheme或 cookie，注入data-theme到html标签 - Nuxt：用
app.html模板 +useRequestEvent()获取偏好，避免依赖window - 纯前端后台：在
<head>内联 JS 同步读取localStorage.getItem('theme')，立即设data-theme，不等DOMContentLoaded
最易被忽略的是：所有主题变量必须在 CSS 文件末尾集中定义，且 html[data-theme="dark"] :root 块必须位于所有默认 :root 之后——顺序错，就全白忙活。
