用途:在 Next.js 项目中安装并接线 Tailwind CSS,覆盖 Tailwind v3.4 与 v4.0+、App Router 与 Pages Router 的全部组合,并处理 next/font 集成与 Turbopack 已知问题。
主要能力:给出各组合的最小安装步骤与文件位置。CSS 文件位置跨版本一致(App Router 用 app/globals.css,Pages Router 用 styles/globals.css),仅内容不同:v4 用 @import "tailwindcss";,v3 用三条 @tailwind 指令。v4 安装命令为 npm install tailwindcss @tailwindcss/postcss postcss,PostCSS 配置使用 @tailwindcss/postcss 插件,无需 tailwind.config.js、autoprefixer 或 postcss-import。v3 安装命令为 npm install -D tailwindcss@3 postcss autoprefixer 并执行 npx tailwindcss init -p 生成配置。
next/font 集成:v4 在 @theme inline 中把 --font-sans 指向 var(--font-inter);含 var(...) 引用时必须用 @theme inline,否则构建期解析为空。v3 在 fontFamily.extend 中声明。
RSC 说明:Tailwind 是构建期编译器,无客户端运行时,Server Component 可直接使用类名,无需 "use client"。
限制与陷阱:Turbopack(Issue 19825)下 aspect-[12/5]、z-[100]、h-[80vh] 等任意值类可能只出现在 DOM 而无 CSS,可用内联样式、@source inline 或关闭 --turbo 规避。v3 默认 content glob 会把 [id]、[...slug] 当字符类,导致动态路由页面无样式,需转义方括号或显式列出目录;v4 用 @source 处理。
验证:CSS 只导入一次;动态路由页面样式正常;生产构建通过;Turbopack 下确认任意值类真正产出 CSS。