【系列主题】从 Docker 构建失败看依赖隔离：多阶段构建的“隐形陷阱”

【系列主题】：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 包。

typescript 复制代码

// ❌ 错误写法 (依赖外网)
import { GeistSans } from 'next/font/google';
// ✅ 正确写法 (依赖本地 node_modules)
import { GeistSans as geistSans } 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，确保一次安装成功：

dockerfile 复制代码

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