Tailwind v4 的 PostCSS 插件已迁移，Vite 项目如何修复构建报错
译注：本文翻译自 dev.to 文章《Fix: Tailwind PostCSS Plugin Has Moved (Vite + React)》，原文发布于 2026 年 9 月 27 日。原文链接见文末。
问题现象
如果你的 Vite + React + TypeScript 项目在构建时抛出 PostCSS 报错，提示 tailwindcss 被"直接当作 PostCSS 插件使用"，那么根本原因通常是：项目安装的是 Tailwind CSS v4，但 postcss.config.js 仍按 v3 的写法配置。
自 Tailwind CSS v4.0 起，PostCSS 插件已迁移到独立的 @tailwindcss/postcss 包中。在 Vite 项目里，官方推荐的修复方式是彻底放弃 PostCSS 路径，改用专用的 @tailwindcss/vite 插件。关键在于：只选一条集成路径，不要两条同时启用。
典型报错信息如下：
[plugin:vite:css] [postcss] It looks like you're trying to use `tailwindcss` directly
as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to
continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss`
and update your PostCSS configuration.这是一个构建期的 PostCSS 失败，而非运行时错误。只要它存在，页面根本无法到达浏览器，无论是 npm run dev 还是 npm run build 都会在 Vite 处理 CSS 入口时立即报错。
为什么会发生
在 Tailwind CSS v3 中，tailwindcss npm 包本身兼任 PostCSS 插件——直接在 postcss.config.js 里写 tailwindcss: {} 即可工作。官方 v4 升级指南明确指出：
"在 v3 中，
tailwindcss包是一个 PostCSS 插件，但在 v4 中，PostCSS 插件位于专用的@tailwindcss/postcss包中。"
这一拆分发生在 Tailwind CSS v4.0（首个稳定版）。核心 tailwindcss 包变为构建工具无关，各集成方式——PostCSS、Vite、独立 CLI——分别移入独立包（@tailwindcss/postcss、@tailwindcss/vite、@tailwindcss/cli）。如果 postcss.config.js 仍以 tailwindcss 作为插件键，而安装的又是 tailwindcss@4，PostCSS 会找到一个不再暴露 PostCSS 插件接口的包，从而抛出上述错误。
同一升级路径上还有第二个陷阱：@tailwind base;、@tailwind components;、@tailwind utilities; 三个指令在 v4 中已废弃。Vite 安装指南将它们统一替换为一行：
@import "tailwindcss";只修复 PostCSS 配置却保留旧的 @tailwind 指令，会撞上另一个独立的构建失败——这不是可有可无的细节，而是必须单独处理的一步。
修复步骤
对 Vite 项目而言，最快的修复是停止用 PostCSS 处理 Tailwind，改用专用 Vite 插件，完全按官方安装文档操作。
1. 移除基于 PostCSS 的 Tailwind 包与配置
npm uninstall @tailwindcss/postcss postcss autoprefixer如果 postcss.config.js（或 postcss.config.mjs）存在的唯一理由就是 Tailwind，直接删除整个文件。若该文件还配置了与 Tailwind 无关的自定义 PostCSS 插件，则只从 plugins 对象中移除 tailwindcss/@tailwindcss/postcss 和 autoprefixer 条目。Tailwind v4 内部已处理自动前缀，因此升级到 v4 后 autoprefixer 无论如何都是多余的。
2. 安装核心包与 Vite 插件
npm install tailwindcss @tailwindcss/vite3. 在 vite.config.ts 中注册 Vite 插件
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
react(),
tailwindcss(),
],
})4. 替换全局 CSS 中的旧指令
@import "tailwindcss";删除 @tailwind base;、@tailwind components; 和 @tailwind utilities;——它们在 v4 中不再是有效的入口点。
5. 重启开发服务器
npm run dev配置正确后错误仍存在，常见原因是 Vite 依赖缓存过期。若仍失败，清除 node_modules/.vite 后重启。
验证修复
- 运行
npm run build，[plugin:vite:css] [postcss]错误应消失。 - 确认
postcss.config.js已不存在（或若为其他插件保留 PostCSS，则不再引用tailwindcss/@tailwindcss/postcss）。 - 打开编译后的页面，确认 Tailwind 工具类（如
text-3xl font-bold）正常渲染样式，而非无样式的纯 HTML。 - 运行
npm ls tailwindcss @tailwindcss/vite查看实际并列安装的版本。 - 直接检查
package.json：@tailwindcss/postcss不应再出现在dependencies或devDependencies中，残留的postcss或autoprefixer条目也不应存在，除非项目其他部分确实需要 PostCSS。 - 若修改时开发服务器仍在运行，请完全停止（不要依赖热重载）后重启，或传入
--force清除 Vite 依赖缓存。Vite 将预打包依赖缓存在node_modules/.vite，重新打包仅由 lockfile 变更、patches 文件夹变更、vite.config.ts中相关字段或NODE_ENV变化触发，单独编辑postcss.config.js并不会触发。
不同框架的差异
专用 Vite 插件适用于 Vite 项目，但并非通用：
| 环境 | 推荐方案 |
|---|---|
| Vite（Rollup 系，React/Vue/Svelte/SolidJS/SvelteKit） | 使用 @tailwindcss/vite，无需 PostCSS 配置 |
| Next.js | 内部运行自己的 PostCSS 管线，无 Vite 插件选项，保留 @tailwindcss/postcss |
| Create React App / 纯 PostCSS 管线（webpack、esbuild） | 同 Next.js，使用 @tailwindcss/postcss |
| 有意留在 Tailwind v3 | 显式锁定版本 npm install -D tailwindcss@3，v3 的 PostCSS 配置不变 |
Next.js 的 postcss.config.mjs 写法如下：
export default {
plugins: {
'@tailwindcss/postcss': {},
},
}此处移除 postcss-import 和 autoprefixer 同样安全——按同一升级指南，Tailwind v4 内部处理导入与厂商前缀。
如果项目同时存在带 tailwindcss() 的 Vite 配置和带 @tailwindcss/postcss 的 PostCSS 配置，这种重复本身就是 bug：Tailwind 会通过两条不同管线处理 CSS 两次，这也解释了为何即便安装了 @tailwindcss/postcss，构建仍报告插件迁移错误——因为 PostCSS 分支仍与 Vite 分支并行接线。
小结
Tailwind v4 的架构变更之所以具有破坏性，正因为它触及的是构建管线而非工具类本身。最安全的顺序始终是：选定一种集成方式（Vite 插件或 PostCSS 插件），彻底移除另一种，然后再更新 CSS 入口语法。