<p>Tailwind CSS v4 的 Oxide 引擎不解析 tailwind.config.js，仅通过 CSS 中的 @import "tailwindcss"、@theme、@custom-variant 等原生 at-rule 读取配置；theme.extend 失效因 JS 配置被完全跳过，颜色等必须用带 --color- 前缀的 OKLCH 格式声明于 @theme 中，且 @import 必须严格写为 @import 'tailwindcss'; 并置于 CSS 文件最顶部。</p>
因为 Tailwind CSS v4 的 Oxide 引擎根本不解析 tailwind.config.js，它只扫描 CSS 文件里的 @import "tailwindcss"、@theme、@custom-variant 等原生 at-rule —— 配置语义已从 JS 对象移回 CSS 本身，不是“抛弃”，而是归位。
为什么 tailwind.config.js 里的 theme.extend 不再生效
Oxide 引擎在构建阶段完全跳过 JS 文件，不执行、不解析、不报错。哪怕你写了 theme.extend.colors.primary = '#3b82f6'，只要没在 CSS 里声明 @theme { --color-primary: #3b82f6; }，bg-primary 就不会生成。
-
@theme是标准 CSS at-rule，必须出现在合法 CSS 上下文中；JS 里写它会被当作注释或语法错误 - 变量名必须带前缀：
--color-primary✅，--primary❌，--my-color❌ - OKLCH 色彩空间下，
--color-primary-500必须是oklch(65% 0.25 270)格式；HEX 或 RGB 值会被跳过，导致primary-400/primary-600类缺失
@import "tailwindcss" 为什么必须写对且放最前
这是 Oxide 引擎识别整个样式系统的唯一入口。写错一个字符，基础类（如 flex、text-lg）就全丢，且无任何报错提示。
- 必须用单引号：
@import 'tailwindcss';✅，@import "tailwindcss";❌，@import 'tailwindcss'❌（缺分号） - 必须放在 CSS 文件最顶部，不能被
@layer包裹，也不能在@plugin后面 - 如果项目还残留
postcss.config.js中的tailwindcss()插件，会导致重复解析或冲突，必须彻底移除
删掉 tailwind.config.js 后哪些功能会静默失效
看似删了就能跑，但以下情况会导致样式漏生成、变体不触发、插件不加载，且 IDE 和 CLI 都不会报错。
立即学习“前端免费学习笔记（深入）”；
-
dark:变体失效：v4 移除了内置darkMode: 'class'，必须手动加@custom-variant dark (&:where(.dark, .dark *));，否则dark:bg-black完全不产出 - content 扫描路径丢失：自动检测只覆盖标准结构（如
./src/**/*.{js,jsx,ts,tsx}），遇到.astro、.svelte、服务端拼接字符串（className={base + ' ' + variant}）就会漏类 - 插件不生效：旧写法
plugins: [require('@tailwindcss/forms')]在 JS 配置中完全无效；必须用@plugin "@tailwindcss/forms"写进 CSS，且 npm 安装的是 v4 兼容版
VSCode 智能提示为什么突然不工作了
不是插件坏了，是路径没对上。VSCode 插件默认仍找 tailwind.config.js，删掉它后必须手动设置 "tailwindCSS.experimental.configFile" 指向你的主 CSS 文件（如 src/index.css），否则所有类名补全、颜色预览、主题变量跳转都会失效。
最容易被忽略的是作用域隔离：你在 src/components/Button.css 里写的 @theme，不会影响 src/layout/Header.css；想全局生效，就得统一写进主入口 CSS，且顺序不能错 —— 这不是配置遗漏，是 CSS 本身的语义约束。
