必须将 Tailwind 的 darkMode 设为 'media' 才能使 dark: 前缀响应系统 prefers-color-scheme；否则 dark:bg-gray-800 等样式不生效，且需确保系统开启深色模式或 DevTools 正确模拟。
直接用 dark: 前缀配合 prefers-color-scheme 媒体查询即可生效，但必须先在 tailwind.config.js 中启用 darkMode: 'media'，否则 dark:bg-gray-800 这类写法完全不会生成对应 CSS。
darkMode 必须设为 'media' 才能响应系统偏好
默认配置下 darkMode 是 'class'（靠手动加 dark class 切换），它和系统设置无关。要让 Tailwind 自动读取 prefers-color-scheme，必须显式改配置：
module.exports = {
darkMode: 'media', // ✅ 关键行
theme: {
extend: {
colors: {
// 可选：为深色模式微调颜色
gray: {
900: '#111827',
800: '#1f2937',
}
}
}
}
}
-
darkMode: 'media'启用后，Tailwind 会为每个带dark:的工具类生成一条@media (prefers-color-scheme: dark)规则 - 不用额外写 CSS 或 JS 监听逻辑，浏览器原生支持，兼容性覆盖 Chrome 87+、Firefox 96+、Safari 14+
- 如果同时用了
darkMode: 'class'和darkMode: 'media'，后者优先级更高——但不能同时设两个值
dark: 工具类只作用于深色模式下的元素
dark: 是变体前缀，不是独立 class，它必须和具体工具类组合使用，比如：
-
bg-white dark:bg-gray-900→ 浅色模式白底，深色模式灰黑底 -
text-gray-800 dark:text-gray-200→ 浅色模式深灰字，深色模式浅灰字 -
border-gray-200 dark:border-gray-700→ 边框随模式自动变色
注意：dark: 不会改变元素是否渲染，也不会触发重排，只是条件性应用样式。
立即学习“前端免费学习笔记（深入）”；
常见错误：深色样式不生效的三个原因
遇到 dark:bg-gray-800 没效果，大概率是以下之一：
- 配置漏了
darkMode: 'media'，或拼写错误（如写成darkmode或'Media'） - 开发时没在系统设置里开启深色模式（macOS 设置 → 外观；Windows 设置 → 个性化 → 颜色 → 选择模式）
- 浏览器 DevTools 里没启用模拟（Chrome DevTools → ⚙️ Settings → Preferences → Rendering → Emulate CSS media feature prefers-color-scheme）
与 class 方式共存时需注意层级冲突
如果你项目里已用 darkMode: 'class'（比如靠按钮切换主题），又想保留系统偏好 fallback，可以手动监听并同步 class：
if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
document.documentElement.classList.add('dark')
}
但此时要注意：dark: 规则仍由 darkMode: 'media' 控制，而 class 规则由 darkMode: 'class' 控制——两者不能混用同一配置。最稳妥的做法是只选一种模式，避免规则互相覆盖。
真正容易被忽略的是：深色模式下字体对比度是否达标。即使颜色变了，text-gray-500 dark:text-gray-400 这种写法在深色背景上可能只有 2.8:1 对比度，不满足 WCAG AA 标准。务必用浏览器的无障碍检查工具验证。
