不能跳过官方升级工具，必须用 @tailwindcss/upgrade 处理配置和类名变更，否则会漏掉 jit 模式启用、@import 语法切换、defaulttheme 移除等关键改动。

直接结论：不能跳过官方升级工具，必须用 @tailwindcss/upgrade 处理配置和类名变更，否则会漏掉 JIT 模式启用、@import 语法切换、defaultTheme 移除等关键改动。

为什么 @tailwindcss/upgrade 不可跳过

v4 的底层构建机制已彻底转向 JIT-only 模式，且废弃了大量 v3 的配置项和语法。手动改配置极易遗漏以下隐性变更：

• defaultTheme 引用在 v4 中完全无效，但不会报错，只会导致 theme 扩展失效
• @tailwind base/components/utilities 必须替换为 @import "tailwindcss"，否则 PostCSS 插件无法识别
• 自定义插件（如 @tailwindcss/forms）需改用 @plugin 指令写法，旧的 plugins: [] 数组方式不再生效
• v4 默认启用 content 路径的 glob 通配符优化，若未更新 tailwind.config.js 中的路径格式，会导致类名未被扫描

执行 npx @tailwindcss/upgrade 的实操要点

该命令不是“一键完成”，而是分阶段提示你确认或干预。重点关注以下三类输出：

CSS婚礼策划服务机构宣传网站模板

CSS婚礼策划服务机构宣传网站模板是一款适合提供婚礼策划和婚庆服务机构宣传网站模板下载。提示：本模板调用到谷歌字体库，可能会出现页面打开比较缓慢。

下载

• 当提示 Remove defaultTheme import?：选 y，v4 不再导出该对象，保留会导致构建失败
• 当提示 Replace @tailwind directives with @import?：选 y，它会把 @tailwind base 等替换成 @import "tailwindcss" 并自动补上 @plugin 行
• 当提示 Update content paths to use glob syntax?：选 y，例如将 ./src/**/*.{js,ts} 改为 ./src/**/*.{js,ts,jsx,tsx}，否则 JSX/TSX 文件中的类名不会被提取

升级后必须验证的两个硬性检查点

工具跑完不等于迁移成功，这两个地方出错最隐蔽、复现成本最高：

• postcss.config.js 中插件顺序必须是 '@tailwindcss/postcss' 在前，autoprefixer 在后；顺序颠倒会导致 @plugin 指令不生效
• tailwind.config.js 中的 content 字段值必须是字符串数组，不能是单个字符串（v3 允许，v4 会静默忽略）
• 如果项目用了自定义字体（如 Inter），检查 @layer base 中的 @font-face 是否仍被 @tailwind base 覆盖——v4 的 @import "tailwindcss" 不再自动包含 base 层，需显式保留

最常被忽略的是 content 字段类型校验和 postcss.config.js 插件顺序。哪怕其他都对，这两处错一个，就会出现“样式写了但没生效”的情况，且控制台无任何错误提示。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！