Tailwind CSS v4 主题配置唯一入口是 CSS 文件中的 @theme 块，必须置于 @import "tailwindcss" 之后且不可嵌套；颜色须以带引号键名的对象语法定义色阶，如 "500": "#3b82f6"，不支持 JS 配置或单值简写。
Tailwind CSS v4 改用 CSS 文件配置主题，tailwind.config.js 不再用于颜色定义；直接写入 @theme 块即可生效，但必须注意语法结构和作用域限制。
tailwind.config.js 在 v4 中已失效
v4 彻底移除了 JS 配置文件对主题的控制能力。如果你还在 tailwind.config.js 里写 theme.extend.colors，这些配置会被完全忽略——不是“不生效”，而是根本没被读取。构建时不会报错，但新颜色 class 永远不会生成。
- 旧项目升级后，需删除或注释掉
tailwind.config.js中所有theme相关配置 - v4 的主题入口唯一且明确：CSS 文件中的
@theme规则块 - 仍保留
tailwind.config.js仅用于非主题类配置（如content、darkMode、plugins）
@theme 块必须放在 @import "tailwindcss" 之后
@theme 是 CSS 规则，不是 JS 对象，位置错误会导致解析失败或静默丢弃。它必须紧跟在 @import "tailwindcss" 后面，且不能嵌套在任何其他规则内（比如 @layer 或媒体查询中）。
- ✅ 正确顺序：
@import "tailwindcss"; @theme { /* 颜色定义 */ } - ❌ 错误示例：
@layer utilities { @theme { ... } }—— 不被识别 - ⚠️ 注意：如果使用了
@import "tailwindcss/base"等分项导入，@theme必须放在所有@import之后，且仅出现一次
自定义颜色必须用对象语法声明色阶
v4 的 @theme 不支持单值简写。写 brand: #3b82f6 只会生成 bg-brand，而 bg-brand-500 依然无效——和 v3 一样，它不会自动推导梯度。
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确写法：
brand: { 50: "#f0f9ff", 100: "#e0f2fe", 500: "#3b82f6", 900: "#0c4a6e" } - ❌ 错误写法：
brand: "#3b82f6"（无色阶）、brand: { 500: "#3b82f6" }（缺少引号，CSS 解析失败） - ⚠️ 所有键名必须是带引号的字符串：
"50"、"500"，不能是数字字面量50 - 十六进制值必须带
#，RGB/HSL 值也需符合 CSS 语法（如rgb(59, 130, 246)）
颜色名含连字符必须加引号，且不能出现在顶层 key
CSS 不允许顶层 key 使用连字符（如 dark-blue），否则解析器会当作减法运算。但 v4 允许你在嵌套结构里用引号包裹含连字符的子键——前提是它不在 @theme 直接子级。
- ✅ 可行：
brand: { "light-blue": "#bfdbfe", "dark-blue": "#1e3a8a" } - ❌ 报错：
"dark-blue": { "50": "#f0f9ff" }（顶层 key 不能带连字符） - ? 推荐方案：用语义化前缀替代，如
brandLightBlue→ 生成 class 为bg-brand-light-blue-500 - 所有颜色名最终都会被转为 kebab-case class 名，无需手动处理命名转换
v4 的 @theme 是纯 CSS 上下文，没有 JS 运行时、无法 import/require、不支持变量计算——所有颜色值必须硬编码或通过 CSS 变量间接引用。如果你依赖动态色盘或 JS 侧复用（比如 Chart.js），得单独维护一份 TS/JS 颜色定义，和 @theme 内容保持手动同步。
