v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T10:04:00.000Z▲ 0 upvotes

Next.js Docker 镜像,输出:“standalone”:多阶段构建且非 root

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

为什么要独立

常规 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: 3

slim 镜像没有 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 就足够了。

Обсуждение (0)

Ещё на vbcd4u.com