首屏主题错误本质是变量注入晚于HTML渲染，而非CSS变量写错；必须在服务端或<head>内联JS中提前设置document.documentElement.dataset.theme，确保首屏直出即带data-theme属性，避免“白→黑”闪屏。
首屏主题错误本质是变量注入时机晚于HTML渲染
不是CSS变量写错了，而是它根本没在浏览器开始绘制前就位。Nuxt的SSR首屏HTML已经生成并发送到客户端，此时:root变量还没加载——浏览器只能用默认值或继承值渲染，等JS执行完才补上深色变量，于是出现“白→黑”闪屏。
常见表现：首屏加载瞬间是浅色，0.3秒后跳成深色；iOS Safari尤其明显；服务端直出的<html>标签上没有data-theme="dark"属性。
- 必须在
<head>最顶部用<link rel="stylesheet">引入含:root声明的CSS文件，不能靠import或<style scoped> - Nuxt 3中禁用
css: ['~/assets/css/variables.css']这种配置——它会把CSS插入到所有样式之后，大概率被组件库覆盖 - 如果使用
useHead动态注入CSS，变量一定晚于首屏HTML，无效 - 检查
public/index.html是否手动写了<style>:root { ... }内联样式，这是最稳的兜底方式
localStorage读取发生在DOM ready之后导致闪回
你在onMounted里读localStorage.getItem('theme')再设document.documentElement.dataset.theme，但此时页面早已渲染完毕。用户看到的就是“先亮后暗”。
真正有效的初始化必须在<script>执行阶段完成，早于任何<div>解析。
立即学习“前端免费学习笔记（深入）”；
- 在
public/index.html的<head>里加一段内联JS：window.localStorage.getItem('theme') === 'dark' && document.documentElement.setAttribute('data-theme', 'dark') - 不要用
document.addEventListener('DOMContentLoaded', ...)——太晚了 - 若用Nuxt插件，必须设
ssr: false且enforce: 'pre'，否则仍走服务端流程 - 验证方法：打开DevTools → Elements → 看
<html>标签是否从一开始就有data-theme="dark"
Nuxt的CSS注入顺序破坏了:root变量优先级
你定义的--theme-bg-primary被Element Plus或Vant的:root块覆盖了——不是变量名错了，是它的CSS文件在HTML里<link>得更靠后。
浏览器按CSS解析顺序决定变量值，后出现的同名:root直接赢。
- 用Network面板确认
variables.css是否排在element-plus/dist/index.css之前加载 - 在
nuxt.config.ts中删掉所有css: [...]配置，改用<link>硬编码在public/index.html里 - 避免在
app.vue的<style>里写:root——Nuxt会把它打包进组件CSS，失去全局性 - 查构建产物：打开
dist/_nuxt/xxx.css，搜索:root，确认你的变量是否被拆散或重复定义
第三方组件库的变量作用域不匹配
Vant 4读:root下的--van-primary-color，但你的:root[data-theme="dark"]规则权重不够，或者库内部用了.van-button { --van-primary-color: ... }局部重写，绕过了全局变量。
这不是Nuxt特有问题，但Nuxt的模块化加载让冲突更隐蔽。
- 打开DevTools → Elements → 选一个
<van-button>→ Computed → 搜索--van-primary-color，看值来源是哪条规则 - 正确覆盖写法是：
html[data-theme="dark"] { --van-primary-color: #3a86ff; }，不是.van-button { --van-primary-color: ... } - 禁用
!important：它会让后续JS调用document.documentElement.style.setProperty()完全失效 - 确认Vant文档是否启用
provideTheme选项——有些版本需显式开启CSS变量支持
:root声明。任何依赖JS、组件生命周期或构建时注入的方式，在首屏场景下都天然滞后。 
