darkMode 必须在 tailwind.config.js 顶层显式配置为 'class'，否则深色模式类不会生成；切换时只能操作 document.documentElement，防闪白需内联 IIFE 脚本于 head 中，组件内所有颜色类须手动添加 dark: 前缀。
darkMode 配置必须写在 tailwind.config.js 顶层
不显式写 darkMode: 'class'，dark: 类根本不会生成——不是失效，是压根没进 CSS 文件。Tailwind v3+ 不再默认启用深色模式支持，漏掉这个字段等于关掉整套能力。
常见错误包括：darkMode: true、darkMode: 'dark'、把配置塞进 theme.extend 或 plugins 里。正确写法只能是：
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./src/**/*.{js,ts,jsx,tsx}"],
darkMode: 'class', // ✅ 必须是顶层字段
theme: {
extend: {},
},
plugins: [],
}配完立刻验证：检查生成的 CSS 文件里有没有 .dark\:bg-gray-800 这类规则。没有？说明配置没生效，别往下写了。
切换逻辑必须操作 document.documentElement
Tailwind 只检查 元素是否有 dark 类。给 加 dark 类完全无效，尤其在 Vue 3 + Vite/SSR 场景下，会直接触发 hydration mismatch 错误，控制台报 Hydration failed because the server-rendered HTML did not match the client-rendered content。
立即学习“前端免费学习笔记（深入）”；
初始化和切换都必须用：
document.documentElement.classList.add('dark')document.documentElement.classList.remove('dark')document.documentElement.classList.toggle('dark')
不能用 document.body，哪怕你看到别人这么写——那是错的，只是浅层没暴露问题。
从零开始编排 SpringBoot+Vue 全栈项目工作流，适用于新建全栈项目或完整脚手架请求，触发后依次调用 product‑spec‑builder（需求调研）等模块。
防闪白脚本要内联在 且早于 CSS
用户打开页面瞬间先渲染浅色样式，JS 后执行才加 dark 类，中间这段延迟就是“闪白”。DOMContentLoaded 或 onMounted 都太晚了，必须抢在浏览器开始绘制前完成判断和类名设置。
最小可行方案（直接贴进 ）：
(( ) => {
try {
const saved = localStorage.getItem('theme')
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const shouldDark = saved === 'dark' || (saved !== 'light' && prefersDark)
document.documentElement.classList.toggle('dark', shouldDark)
} catch {}
})()注意三点：
- 必须是 IIFE，不能包裹在任何事件监听器里
- 必须放在
内联，不能抽成外部 JS 文件（加载有延迟） - Vue 3 的
onMounted里做切换，只适合补救或降级逻辑，不能替代这个脚本
Vue 3 组件中 dark: 类要手动补全
Tailwind 不会自动推断深色下的颜色是否可读。比如 text-gray-700 在深色背景上可能灰得看不见，必须显式写成 dark:text-gray-300。
常见遗漏点：
- 所有带颜色的工具类都要检查是否加了
dark:前缀（bg-、text-、border-、placeholder-等） -
hover:和dark:组合时，推荐统一用dark:hover:bg-gray-700，顺序不影响功能但提升可读性 - 图标 SVG 的
fill或stroke颜色也要用dark:fill-gray-400控制
最麻烦的是表单控件：原生 <input type="checkbox"> 的样式无法用 dark: 直接覆盖，得配合 @layer components 或插件如 @tailwindcss/forms 手动重置。
