Next.js Docker 镜像,输出:“standalone”:多阶段构建且非 root
为什么要独立
常规 Next.js 映像会复制整个 node_modules 以及 devDependency、源和构建缓存。使用 output: 'standalone' Next.js,在构建时会跟踪服务器实际需要的文件,并将它们与最小的 server.js 一起放入 .next/standalone 中。只有这个、静态和 public 最终出现在最终图像中。
// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
output: "standalone",
};
export default nextConfig;在单一存储库中,添加 outputFileTracingRoot 以及存储库根目录的路径,否则跟踪将找不到相邻文件夹中的包。
Dockerfile
# syntax=docker/dockerfile:1
FROM node:22-bookworm-slim AS base
ENV NEXT_TELEMETRY_DISABLED=1
WORKDIR /app
# 1. Только зависимости — слой кэшируется, пока не меняется lock-файл
FROM base AS deps
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
# 2. Сборка
FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ARG NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
RUN npm run build
# 3. Рантайм
FROM base AS runner
ENV NODE_ENV=production \
PORT=3000 \
HOSTNAME=0.0.0.0
COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
USER node
EXPOSE 3000
CMD ["node", "server.js"]解决方案分析:
- 三个阶段。 编译器、开发依赖项和源代码仍处于中间阶段,不会出现在最终映像中。
- `--mount=type=cache` 在同一台计算机上的构建之间保留 npm 缓存。这是一个 BuildKit 函数,因此
# syntax行位于开头。 - `HOSTNAME=0.0.0.0`.
server.js监听此变量的地址。如果没有它,服务器可以绑定到容器名称,转发的端口将响应连接失败。 - 静态数据单独复制。
.next/standalone不包含.next/static和public- 这是第一次构建后 CSS 和 JS 出现 404 的常见原因。 - `USER node`. 官方节点镜像已经有一个非特权用户
node(uid 1000)。不必创建您自己的文件,但必须从--chown复制文件,否则该进程将无法写入.next/cache以进行 ISR 和图像优化。
环境变量:构建和运行时
NEXT_PUBLIC_* 变量在 next build 期间被替换到客户端 JavaScript 中。使用 docker run 传输它们已经太晚了 - 捆绑包已包含来自程序集的值或为空。因此,它们在构建器阶段会经历 ARG。
相反,服务器机密(DATABASE_URL、API 密钥)不应包含在映像中。不要将它们作为 ARG 传递,也不复制 .env - 在启动时设置它们:
docker run -d --env-file /etc/myapp/prod.env -p 127.0.0.1:3000:3000 myapp:1.4.0
并且一定要.dockerignore,否则COPY . .会将不必要的东西拖到程序集上下文中,包括秘密:
node_modules .next .git .env* *.log coverage
PID 1 并停止容器
以 PID 1 运行的 Node 进程不会接收信号的标准内核行为。如果应用程序没有 SIGTERM 处理程序,docker stop 将等待超时(默认情况下为 10 秒)并通过 SIGKILL 终止进程,从而终止活动请求。一个简单的解决方案是 init 进程:
# compose.yml
services:
web:
image: myapp:1.4.0
init: true
env_file: /etc/myapp/prod.env
ports:
- "127.0.0.1:3000:3000"
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
interval: 30s
timeout: 5s
retries: 3slim 镜像没有 curl,因此 healthcheck 是在 Node 本身中编写的:全局 fetch 在 Node 18 及更高版本中可用。
图像和清晰度
在 Next.js 15 中,sharp 自动与 next start 连接并处于独立模式;无需手动安装。如果您仍然看到有关缺少 Sharp 的警告,请检查构建和运行时是否在同一平台上:为 glibc 编译的二进制文件不适用于 Alpine (musl),反之亦然。因此,在该示例中,所有阶段都来自一张基本图像。
如何检查结果
docker build -t myapp:test --build-arg NEXT_PUBLIC_SITE_URL=https://example.com . docker image ls myapp:test # размер образа docker run --rm myapp:test id # uid=1000(node), не root docker run --rm myapp:test ls -la .next # владелец node
要分析层中哪些内容占用了空间,dive 工具很方便。如果最终图像出乎意料地大,它通常包含整个 node_modules:检查运行程序中是否没有 COPY . .。
常见错误
Error: EACCES写入.next/cache时 - 文件在没有--chown的情况下复制。- 该网站可以运行,但没有样式 - 他们忘记复制
.next/static。 NEXT_PUBLIC_*在浏览器中为空 - 在运行时传输,而不是在汇编期间传输。- 使用 Apple Silicon 在 Mac 上构建,在 amd64 服务器上运行 - 您需要
docker buildx build --platform linux/amd64,否则本机模块的架构错误。
当不需要独立时
如果部署转到 Vercel 或具有自己的程序集的其他平台,则此设置不会提供任何信息。对于静态导出(output: 'export'),根本不需要服务器 - 带有静态的 nginx 就足够了。