tailwind css v4 已弃用 tailwind.config.js，改用 @theme 规则在主 css 入口（如 src/index.css）中声明主题变量；@theme 必须位于 @import "tailwindcss" 之后、其他规则之前，变量名禁用连字符，值须为 oklch/rgb/hsl 格式，且主题切换依赖 css 层级而非 js 注入。
tailwind.config.js 在 v4 中已弃用
Tailwind CSS v4 不再使用 tailwind.config.js 管理主题变量，改用原生 CSS 的 @theme 规则。如果你还在项目里留着这个文件并往 theme.extend.colors 里塞 var(--primary)，构建会通过但颜色不响应切换——因为 v4 的解析器压根不读它。
正确入口只有一个：src/index.css（或你项目的主 CSS 入口）。
@theme 规则必须写在 @import 后、其他规则前
@theme 是 v4 新增的原生 at-rule，作用是把 CSS 变量声明“接入” Tailwind 的主题系统，让 text-primary、bg-primary 这类工具类能自动参与色阶推导和变体生成（比如 hover 版本会自动变暗）。
顺序错了就失效：
- ✅ 正确：
@import "tailwindcss";→@theme { ... }→ 其他 CSS - ❌ 错误：把
@theme写在@layer utilities之后，或包裹在@layer base里 - ⚠️ 注意：
@theme里的变量名不能带连字符（如--primary-color），推荐用下划线或驼峰（--primaryColor）
变量值必须是 oklch / rgb / hsl 格式，不能是 hex
v4 要求 @theme 中的颜色变量必须是可计算的色彩空间格式，否则无法生成 hover/focus 等变体。写 --primary: #3b82f6 看似正常，但构建时会跳过色阶推导，导致 hover:bg-primary 和 bg-primary 渲染成同一个色值。
安全写法：
-
--primary: oklch(0.55 0.27 262);（推荐，支持亮度/色度独立调节） -
--primary: rgb(59, 130, 246);（兼容性好） --primary: hsl(215, 92%, 60%);- ❌ 避免：
--primary: #3b82f6、--primary: var(--fallback)
data-theme 切换时变量覆盖要靠 CSS 层级，不是 JS 注入
运行时切换主题，靠的是 CSS 选择器优先级，不是 document.documentElement.style.setProperty()。后者只能影响纯 CSS 规则（如 .text-dynamic { color: var(--primary); }），对 Tailwind 工具类无效。
正确做法：
- 在
@theme外定义默认值：:root { --primary: oklch(0.55 0.27 262); } - 用属性选择器覆盖：
[data-theme="dark"] { --primary: oklch(0.3 0.2 262); } - JS 切换只需一行：
document.documentElement.dataset.theme = 'dark' - ⚠️ 注意：
[data-theme]必须写在:root后面，且不能被@media包裹，否则层级不足
真正容易被忽略的点：v4 的 @theme 不支持嵌套或条件逻辑，所有主题分支都得平铺写死；如果设计系统有超过 3 套主题，CSS 文件会迅速变长——这时候该考虑拆出单独的 themes.css 并用 @import 引入，但导入语句仍需紧贴 @import "tailwindcss" 后面。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
