【系列主题】：Next.js 16 容器化部署深水区踩坑实录
第一篇：从 Docker 构建失败看依赖隔离：多阶段构建的“隐形陷阱”
摘要：在将 Next.js 项目从本地开发迁移到 Docker 多阶段构建时，外部依赖拉取失败和devDependencies丢失是两大高频问题。本文将深入剖析 Docker 构建缓存、网络隔离与 Node.js 依赖管理的冲突，并提供一套无感的 Dockerfile 编写范式。
1. 背景与痛点
我们的项目基于 Next.js 16、Prisma 和 shadcn/ui。为了适应最终 1核2G 的低配生产服务器，采用了“高配服务器 Docker 多阶段构建 +standalone模式输出”的架构。
但在执行docker build时，接连遭遇：
next/font/google拉取超时导致构建中断。- 明明安装了的 CSS 依赖，在构建阶段提示
Module not found。
2. 坑位一：被 GFW 与容器网络双重绞杀的 Google Fonts
现象：本地运行正常，一旦打入 Docker 镜像，构建卡死或报网络错误。
原理：Next.js 的next/font/google在编译时，会向 Google 的 CDN 发起请求下载字体文件。在 Docker 构建的沙箱环境中，不仅受制于宿主机的网络环境（如国内被墙），还可能因为 DNS 解析差异导致失败。
解决方案：将外部运行时请求降级为本地编译时依赖。shadcn/ui 默认使用的Geist字体提供了本地 npm 包。
// ❌ 错误写法 (依赖外网)import{GeistSans}from'next/font/google';// ✅ 正确写法 (依赖本地 node_modules)import{GeistSansasgeistSans}from"geist/font/sans";同时在 Dockerfile 的依赖安装阶段确保geist被正确安装。
3. 坑位二：--omit=dev导致的“幽灵依赖”
现象：在 Dockerfile 的deps阶段执行了npm install --omit=dev，导致后续构建阶段报错找不到 TypeScript、Tailwind 等工具。
原理：很多开发者为了减小镜像体积，会在第一阶段加上--omit=dev。但忽略了 Next.js 的next build强依赖devDependencies（比如typescript、postcss、tailwindcss）。
正解：在多阶段构建中，第一阶段的产物只是给第二阶段（Builder）用的，不应该在第一阶段裁剪依赖。最终的体积控制应该交给 Next.js 的output: 'standalone'，它会自动剥离不需要的devDeps。
4. 坑位三：多次npm install引发的依赖覆盖
现象：为了安装特定版本的包，在 Dockerfile 中先写了RUN npm install geist tw-animate-css --save，接着又写了RUN npm install，结果包还是丢了。
原理：第二次npm install会根据当前的package-lock.json重新构建依赖树。如果本地提交的package.json里没有这两个包，第二次安装会无情地将它们删掉。
终极方案：利用 Node.js 脚本在安装前动态篡改package.json，确保一次安装成功：
COPY package.json package-lock.json* ./ # 动态注入依赖，防止漏提代码 RUN node -e "const fs=require('fs');const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));pkg.dependencies=Object.assign({},pkg.dependencies||{},{'geist':'^1.3.1','tw-animate-css':'^1.4.0'});fs.writeFileSync('package.json',JSON.stringify(pkg,null,2));" RUN npm install --no-audit --no-fund
