Tailwind CSS v4 必须用 CSS 中的 @theme 规则块配置颜色，tailwind.config.js 的 theme.extend.colors 已失效；需在已导入的 CSS 文件中显式声明色阶对象（键名加引号），深色模式需手动定义 dark: 命名空间。
Tailwind CSS v4 不再使用 tailwind.config.js 配置颜色，必须改用 CSS 文件中的 @theme 规则块。 你照着 v3 的写法去改 config 文件，配置根本不会生效——v4 已彻底移除 JS 配置驱动的主题系统。
为什么 tailwind.config.js 里的 theme.extend.colors 在 v4 中失效
v4 将主题配置完全迁移到 CSS 层，tailwind.config.js 仅保留插件、内容路径、暗色模式策略等非样式类配置。所有颜色、间距、字体尺寸等设计 token 必须通过 @theme 声明，否则 JIT 编译器压根不识别。
- 旧配置（v3）：
theme.extend.colors = { 'brand': '#3b82f6' }→ v4 中被完全忽略 - v4 正确入口：在
src/index.css或其他已导入的 CSS 文件中写@theme { /* 这里 */ } - 错误现象：新增的
bg-brand-500在浏览器中无对应 CSS 规则，开发者工具查不到任何生成样式
@theme 块中如何声明带色阶的自定义颜色
和 v3 类似，单值颜色（如 brand: #3b82f6）只生成基础类（bg-brand），不支持 -500 后缀；要完整色阶，必须显式定义对象结构，且键名必须为字符串（'50'、'500'）。
- 正确写法：
@theme { colors: { 'brand': { '50': '#f0f9ff', '100': '#e0f2fe', '500': '#3b82f6', '900': '#1d4ed8' } } } - 错误写法：
brand: '#3b82f6'（无色阶）、500: '#3b82f6'（缺少外层brand键）、500: ...（数字键未加引号） - 连字符色名必须加引号：
'dark-brand'✅，dark-brand❌（CSS 解析报错）
如何让自定义颜色在深色模式下自动切换
v4 的 @theme 支持嵌套 dark: 命名空间，但需配合 darkMode: 'class' 或 'media' 使用，且不能依赖自动推导——每个变体都得手动定义。
立即学习“前端免费学习笔记（深入）”；
- 启用 class 模式：
module.exports = { darkMode: 'class' }（仍需保留 config 文件，仅用于此开关） - 在
@theme中写：@theme { colors: { 'bg-main': { '50': '#FAFAFA', 'dark': { '50': '#111827', '900': '#030712' } } } } - 使用方式：
bg-bg-main-50 dark:bg-bg-main-dark-50—— 注意dark:下的键名也需显式匹配 - 不支持
dark:bg-main-50这种简写，v4 不做 key 映射，只做命名空间展开
最易忽略的一点：v4 的 @theme 块必须出现在已通过 @import "tailwindcss" 加载的 CSS 文件中，且不能包裹在 @layer 或媒体查询内；否则整个主题声明会被跳过。另外，所有颜色值若引用 CSS 变量（如 var(--color-brand)），变量本身必须在 @theme 之前定义好，顺序不可颠倒。
