Tailwind CSS v4 未弃用 JS 配置文件，仍完全支持 tailwind.config.js；但默认推荐并深度集成 CSS-first 方式，即通过 @config 和 @layer 在 CSS 中声明静态配置，仅限 theme 下 colors、spacing 等基础项，且作用域限于当前文件。
Tailwind CSS v4 并没有弃用 JS 配置文件 —— 它依然完全支持 tailwind.config.js，但默认推荐并深度集成了一种更轻量、更可控的 CSS-first 配置方式：通过 @layer 和 @config 在 CSS 文件中声明配置。
为什么你会看到“JS 配置被弃用”的误解
这源于官方文档对新工作流的强调，以及 CLI 默认生成的 starter 项目已不再创建 tailwind.config.js。实际是「零配置优先」策略升级：只要没显式需要 JS 动态逻辑（比如基于环境切换配色方案），就鼓励把配置沉到 CSS 层。
- 常见错误现象：
npm run dev启动后自定义颜色不生效，查了半天发现tailwind.config.js被删了，但没补上 CSS 中的@config - 真实使用场景：组件库封装、设计系统交付、微前端子应用独立主题 —— 这些场景下 CSS 配置比 JS 更易打包隔离、更少依赖构建链路
- 关键区别：
tailwind.config.js仍可存在且优先级更高；但一旦你用了@config，它只影响当前 CSS 文件作用域内的@apply和工具类生成，不污染全局
@config 怎么写？哪些配置项支持？
@config 是 Tailwind v4 新增的 CSS at-rule，语法接近 JS 对象字面量，但仅接受静态值（无函数、无变量引用、无表达式）。
- 支持的配置项有限：目前仅
theme下的colors、spacing、fontSize、borderRadius等基础键，不支持plugins或content - 写法示例（放在
src/styles/tokens.css中）：
@config {
theme: {
colors: {
primary: '#3b82f6',
danger: '#ef4444'
},
spacing: {
'3.5': '0.875rem'
}
}
}
- 注意：
@config必须出现在@tailwind utilities之前，且同一 CSS 文件中只能出现一次 - 性能影响：CSS 解析阶段即完成配置合并，跳过 JS 模块加载与运行，冷启动快约 120–200ms（实测 vite + large project）
JS 配置还没死，但它现在更像“高级模式开关”
当你需要以下能力时，tailwind.config.js 仍是唯一选择：
Wjs Uploading Video
下载
将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。
立即学习“前端免费学习笔记（深入）”；
- 动态生成 theme（如读取
design-tokens.json并 map 成 color scale） - 条件启用插件（
process.env.NODE_ENV === 'development' ? require('tailwindcss-debug-screens') : null） - 自定义
content路径或正则匹配逻辑（尤其在 monorepo 中跨包扫描） - 与 PostCSS 插件链深度耦合（例如注入 design token 变量到
:root）
此时要注意兼容性：v4 的 tailwind.config.js 格式未变，但若同时用了 @config，JS 配置会作为 baseline，CSS 中的 @config 会 shallow merge 覆盖对应字段 —— 不是深合并，同名 key 直接替换。
容易踩的坑：CSS-first 不等于“不用 JS 配置”
最常被忽略的是作用域和优先级规则：
-
@config只对同一文件内后续的@layer utilities和@apply生效；跨文件不继承，也不影响tailwind.config.js中定义的工具类 - 如果你在
A.css写了@config { theme: { colors: { foo: 'red' } } }，但在B.css里@apply bg-foo，会报错 ——bg-foo未生成 - CLI 构建时不会警告缺失的
@config，只会静默回退到默认 theme，调试时需检查生成的 CSS 是否含预期工具类（如搜索.bg-primary）
真正复杂的点不在语法，而在于团队协作时如何约定配置下沉边界：哪些 token 放 CSS、哪些放 JS、哪些该抽成 design token 包 —— 这部分没有自动工具，靠规范和 lint 规则卡口。
