【系列主题】Next.js 16 + Turbopack 的暗礁：深入剖析 Tailwind v4 的 CSS 模块解析陷阱

第二篇：Next.js 16 + Turbopack 的暗礁：深入剖析 Tailwind v4 的 CSS 模块解析陷阱

摘要：升级到 Next.js 16 后，Turbopack 成为了默认构建引擎。然而，当它遇到采用全新架构的 Tailwind CSS v4 以及 shadcn/ui 的新动画库时，爆发了难以察觉的模块解析 Bug。本文带你剥丝抽茧，看如何绕过构建工具的底层缺陷。

1. 起因：shadcn/ui 的 Tailwind v4 迁移

shadcn/ui 在适配 Tailwind v4 时，弃用了旧的 @plugin "tailwindcss-animate"，改用了一个全新的 npm 包 tw-animate-css。官方指引非常简单：

1. npm install tw-animate-css
2. 在 globals.css 中加入 @import "tw-animate-css";
   在本地 next dev 一切风平浪静，但一上 Docker，灾难降临。

2. 现象：死活解不开的 Module not found

Error: Turbopack build failed with 1 errors:
./src/app/globals.css:2:2
Module not found: Can't resolve 'tw-animate-css'

排查路径：

• 检查 package.json？有。
• 检查 Docker 的 node_modules？进去看，文件确确实实躺在 node_modules/tw-animate-css/dist/tw-animate.css。
• 猜测是 devDependencies 问题？改成了 dependencies，依然报错。

3. 深挖原理：Turbopack 与 CSS Exports 的不兼容之痛

为什么本地 Dev 没问题，Build 却报错？因为 Dev 和 Build 底层使用的策略不同。

当你在 CSS 中写 @import "tw-animate-css" 时：

1. Webpack (旧版) ：会去 node_modules 里找，按照 package.json 的 main 或 style 字段解析。
2. Turbopack (新版) ：严格遵循 Node.js 最新的 Exports 规范。tw-animate-css 在其 package.json 中使用了条件导出："exports": { ".": { "style": "./dist/tw-animate.css" } }。
3. Bug 所在 ：Next.js 16.1.6 的 Turbopack 在处理纯 CSS 的 @import 时，未能正确识别并解析 npm 包的 exports.style 字段，导致它认为这个包不存在。

4. 失败的反抗：试图禁用 Turbopack

遇到 Turbopack 的 Bug，第一反应是关掉它。查阅文档发现有个环境变量 NEXT_DISABLE_TURBOPACK=1。
坑点 ：在 Next.js 16.1.6 中，这个变量对 next build 完全无效 ！日志依然傲慢地打印着 ▲ Next.js 16.1.6 (Turbopack)。

5. 终极降维打击：在 Docker 层面实施"物理黑客"

既然 Turbopack 不认 node_modules 里的包，那我们就把它变成"本地文件"。但为了避免污染本地 Git 仓库（直接把下载的 css 提交上去很丑陋），我们可以在 Docker 构建时动态拷贝：
第一步 ：修改 globals.css

@import "tailwindcss";
@import "./tw-animate.css"; /* 从包名改为相对路径 */

第二步 ：在 Dockerfile 的 Builder 阶段，build 之前插入拷贝指令

# 阶段 2: 项目构建
...
# 神来之笔：在构建前，把 node_modules 里的 css 偷出来放到源码目录
RUN cp node_modules/tw-animate-css/dist/tw-animate.css ./src/app/tw-animate.css
RUN npm run build

为什么这是最优解？

1. 不侵入本地代码仓库，本地依然通过 npm 包管理。
2. 完美绕过 Turbopack 对 Exports 的解析缺陷。
3. 确保使用的 CSS 版本与 node_modules 安装的版本 100% 一致，不会出现版本脱节。

---