Tailwind CSS v4自定义配置失效的根本原因是Oxide引擎默认不解析tailwind.config.js，只识别CSS文件中的@config和@theme块；必须在主CSS中显式声明@config（静态对象字面量）、正确放置@theme（位于@import之后），并确保content路径覆盖所有含类名文件，否则colors、spacing等扩展均不生效。
Tailwind CSS v4 升级后自定义配置失效，根本原因不是“配置写错了”，而是配置加载机制变了——v4 默认跳过 tailwind.config.js，只认 CSS 文件里的 @config 和 @theme 块。你保留了旧配置文件，但引擎根本没读它。
为什么 tailwind.config.js 里写的 colors / spacing 全都不生效
v4 的 Oxide 引擎默认不解析 JS 配置。即使文件存在且语法正确，只要没在 CSS 主入口中显式声明 @config，所有主题扩展（如 colors.my-blue）和断点修改都会被忽略。
- 开发时看着有样式？那是 Vite/Next.js 插件在 fallback 模式下偷偷读了 JS 文件——但生产构建会彻底跳过它
- 检查你的主 CSS（如
src/style.css）是否在@import "tailwindcss"之前写了@config -
@config必须是静态对象字面量：不能调用函数、不能引用var(--color)、不能拼字符串，例如{ colors: { 'my-blue': '#1e40af' } }合法，{ colors: { ...defaultTheme.colors } }非法
@theme 块必须放在 @import "tailwindcss" 之后
@theme 是运行时可变的主题声明区，但它依赖 @import 加载的基础引擎。顺序错位会导致整个主题块被忽略，且无任何警告。
- 错误顺序：
@theme { /* ... */ } @import "tailwindcss"→ 主题不注册 - 正确顺序：
@import "tailwindcss"; @theme { /* ... */ } -
@theme中的颜色、间距等值会覆盖@config，但两者都必须出现在同一 CSS 文件中；跨文件引入的@theme不会被识别 - 暗黑模式变体（
dark:）不再从tailwind.config.js读darkMode，而完全依赖content扫描到的dark:类名来触发生成——漏扫就等于没这个变体
动态类名和第三方库的类仍需 safelist，哪怕用了 @config
@config 只控制“生成哪些工具类”，不改变 PurgeCSS 的扫描逻辑。如果你的自定义色类（如 bg-my-blue）没出现在 content 覆盖的源码文本中，照样被删。
立即学习“前端免费学习笔记（深入）”；
- 确保
content数组包含所有含类名的路径，例如 Vue 项目要加"./src/**/*.{vue,ts,js}"，不能只写.js - JSX 中
className={`bg-${theme}-500`}这种写法，源码里没有完整类名，必须进safelist：safelist: [/bg-[a-z]+-500/] - 第三方库（如 DaisyUI）内部用了你的自定义色？得把它的 dist 路径也加进
content，例如"./node_modules/daisyui/dist/**/*.js" - Vite 用户注意：
content字段仍需保留在tailwind.config.js中（哪怕其他配置都挪到 CSS），否则插件无法传递扫描路径
最易被忽略的一点：VSCode 的 Tailwind IntelliSense 插件默认只监听 tailwind.config.js，当你把配置全迁到 CSS 后，它会停止提示——必须手动在设置里指定 "tailwindCSS.experimental.configFile" 指向你的主 CSS 文件。
