Tailwind CSS v4 的 CSS-first 配置将核心样式生成逻辑移至 CSS 文件，通过 @theme、@config、@utility 等指令声明主题、断点和工具类；tailwind.config.js 仅保留 content 扫描与插件加载功能，不再参与类名生成。
Tailwind CSS v4 的 CSS-first 配置不是“替代 JS 配置”，而是把核心样式生成逻辑从 tailwind.config.js 移到了 CSS 文件里；如果你还靠 JS 文件配颜色、断点或暗色模式，那些配置大概率不会生效——因为 Oxide 引擎压根不读它。
为什么自定义颜色写了但 bg-primary 不生成？
根本原因是：v4 的样式生成只扫描 CSS 源码中的 @theme 指令，不解析 tailwind.config.js 里的 theme.extend.colors。
-
@theme必须写在@import "tailwindcss"之后、且同一 CSS 文件中（跨文件不生效） - 变量名必须带标准前缀：
--color-primary✅，--primary❌ 或--my-color❌ - 值支持 HEX/RGB/HSL，但 OKLCH（如
oklch(0.62 0.15 274)）才能触发自动明度阶梯生成 - 哪怕你保留
tailwind.config.js并写了theme.extend.colors.primary: '#3b82f6'，只要没在 CSS 里声明@theme { --color-primary: #3b82f6; }，bg-primary就不会被生成
如何用 @config 声明基础主题项？
@config 是 v4 新增的 CSS at-rule，语法像 JS 对象字面量，但只接受静态值——不能有函数、不能引用 CSS 变量、不能拼字符串。
- 支持项有限：
theme.colors、theme.spacing、theme.fontSize、theme.borderRadius等基础键 - 不支持
plugins、content、darkMode—— 这些仍得靠tailwind.config.js -
@config必须出现在@import "tailwindcss"之前，顺序错等于没写 - 作用域仅限当前 CSS 文件，适合组件库隔离主题，不影响全局
暗色模式、响应式断点、自定义工具类怎么配？
v4 把这些能力全部迁移到 CSS 层，不再依赖 JS 插件或配置项。
立即学习“前端免费学习笔记（深入）”；
- 暗色模式默认启用，无需
darkMode: "class"；通过[data-theme="dark"]或@media (prefers-color-scheme: dark)触发，dark:bg-gray-800开箱即用 - 响应式断点直接用
@theme { --breakpoint-sm: 480px; }声明，会自动映射为sm:变体 - 自定义工具类用
@utility，支持嵌套（&:hover）、响应式（@lg）、暗色（@dark），例如：@utility sr-only { @apply absolute w-1 h-1 p-0; }
VSCode IntelliSense 和构建工具常见失效原因
VSCode 插件罢工、Vite 静默跳过 Tailwind 处理，通常不是插件坏了，而是路径或顺序没对上。
- VSCode 的 Tailwind IntelliSense 插件默认找
tailwind.config.js，删了它就得在设置里显式指定"tailwindCSS.experimental.configFile"指向主 CSS 文件（如src/styles/main.css） - Vite / Next.js 若未识别到含
@import "tailwindcss"的入口 CSS，会静默跳过所有 Tailwind 处理 -
tailwind.config.js若存在，仍控制 CLI 的content扫描范围和插件加载（如daisyui），但它不参与text-primary是否生成的判断
最容易被忽略的是：@theme 和 @config 的作用域限制、变量命名前缀强制要求、以及它们与 tailwind.config.js 的职责边界——JS 文件只管“扫哪些文件”和“装哪些插件”，CSS 文件才真正决定“生成哪些类”。
