Tailwind CSS v4 彻底移除对 tailwind.config.js 的支持，Oxide 引擎仅解析 CSS 中的 @import、@theme、@plugin 等指令，JS 配置文件被完全忽略且不报警告。
Tailwind CSS v4 并没有“放弃” JavaScript 配置，而是彻底移除了对 tailwind.config.js 的支持 —— 它不再被读取、不触发警告、也不参与编译流程。你保留这个文件，它就只是个躺在项目里的普通 JS 文件。
为什么 tailwind.config.js 在 v4 中完全失效
Oxide 引擎（v4 的 Rust 核心）根本不解析 JS 文件。它只扫描 CSS 源码，识别 @import 'tailwindcss'、@theme、@plugin 等 CSS at-rules。旧版依赖的 PostCSS 插件链已删除，@tailwind base 这类指令也静默忽略 —— 不报错，但样式就是不生成。
- 如果你还在用
@tailwind base，必须全部替换成@import 'tailwindcss'，且该语句需出现在所有@theme之前 -
content字段被废弃：Oxide 内置 glob 扫描器自动覆盖src/**/*.{js,ts,jsx,tsx,html,vue}，非标准路径（如.md或自定义组件目录）需手动加到@import后的content参数里，例如：@import 'tailwindcss' content('./src/**/*.md'); - 插件不再通过 JS 数组注册，改用
@plugin "daisyui"写在 CSS 文件顶部；若插件未提供 CSS-at-rule 接口（比如某些老版自定义插件），将无法在 v4 中使用
@theme 能配什么、不能配什么
@theme 是纯静态声明，仅接受 CSS 变量语法，不支持 JS 表达式、函数调用或变量引用（calc()、var(--x) 在 @theme 块内无效）。它只影响当前 CSS 文件作用域内的工具类生成。
- 支持的键有限：目前仅
--color-*、--spacing-*、--font-size-*、--border-radius-*、--breakpoint-*等基础 theme 项 - 颜色必须用 OKLCH 格式（如
--color-primary-500: oklch(60% 0.3 280)），HEX / RGB / HSL 会被跳过 -
plugins、darkMode、prefix等全局配置项不可在@theme中设置；prefix改为@import 'tailwindcss' prefix(tw)方式传参 -
@theme inline可用于跨 scope 引用变量，但仅限同一文件内已声明的变量，且不能形成循环引用
常见错误现象与定位思路
最典型的问题是：改了颜色变量，bg-primary-500 类没生成，或者热更新后样式不刷新。
立即学习“Java免费学习笔记（深入）”；
- 检查
@theme是否写在@import 'tailwindcss'之前 —— 顺序反了，变量不会被注入 - 确认变量名符合命名规范：
--color-、--spacing-等前缀不能错，且连字符后必须跟合法标识符（不能含大写字母或下划线） - 打开浏览器开发者工具，在 Styles 面板里搜
--color-primary-500，看是否真的被注入到:root或对应 scope；如果没出现，说明@theme未被 Oxide 解析（常见于语法错误或位置错误） - Vite 用户务必检查
vite.config.js中是否注册了tailwindcss()插件，否则@import语句根本不会被处理
真正容易被忽略的是：v4 的 CSS-first 不是“多一种选择”，而是强制约束 —— 它把配置权从运行时 JS 移到了编译时 CSS，换来的是微秒级热重载和零构建瓶颈，但也意味着你不能再靠 JS 动态计算色阶、拼接 class 名、或基于环境变量切换主题逻辑。那些事得交给运行时 CSS 变量或状态管理库去做，而不是指望 Tailwind 编译器。
