nodejs-containers

Node.js 容器优化

使用 Alpine 变体、多阶段构建和 Node.js 专属依赖管理模式，构建经过优化的 Node.js 容器镜像。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 container-development……
构建 Node.js 专属 Dockerfile	通用多阶段构建模式
优化 Node.js 镜像大小	与语言无关的容器安全
在容器中处理 npm/yarn/pnpm	Docker Compose 配置
处理原生模块构建	非 Node.js 容器优化

核心专长

Node.js 容器的挑战：

• node_modules 目录较大（100-500MB）
• 完整基础镜像包含构建工具（约 900MB）
• 需要分离开发依赖和生产依赖
• 包管理器各不相同（npm、yarn、pnpm）
• 原生模块需要构建工具

核心能力：

• 基于 Alpine 的镜像（约 100MB，而完整镜像约 900MB）
• 通过多阶段构建分离构建和运行时
• 使用 BuildKit 缓存挂载缓存 node_modules
• 仅安装生产依赖
• 配置非 root 用户

优化的多阶段模式（Node 服务）

推荐的模式可将镜像大小控制在约 100-150MB：

# Dependencies stage - production only
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Build stage - includes devDependencies
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runtime stage - minimal
FROM node:20-alpine
WORKDIR /app

# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -u 1001 -S nodejs -G nodejs

# Copy dependencies and built app
COPY --from=deps --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=build --chown=nodejs:nodejs /app/dist ./dist
COPY --chown=nodejs:nodejs package.json ./

USER nodejs
EXPOSE 3000

HEALTHCHECK --interval=30s CMD node healthcheck.js || exit 1

CMD ["node", "dist/server.js"]

BuildKit 缓存挂载（最快的构建）

# syntax=docker/dockerfile:1

FROM node:20-alpine AS build
WORKDIR /app

# Cache mount for npm cache
RUN --mount=type=cache,target=/root/.npm \
    --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    npm ci

COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]

构建性能：

• 首次构建：约 2-3 分钟
• 后续构建（软件包未更改）：约 10-20 秒
• 后续构建（软件包有更改）：约 30-60 秒

包管理器模式

npm

COPY package*.json ./
RUN npm ci --only=production
RUN npm cache clean --force

yarn

COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile --production
RUN yarn cache clean

pnpm

RUN npm install -g pnpm
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod
# pnpm creates smaller node_modules with hard links (20-30% smaller)

性能影响

指标	完整 Node（900MB）	Alpine（350MB）	多阶段（100MB）	改进
镜像大小	900MB	350MB	100MB	减少 89%
拉取时间	3m 20s	1m 10s	25s	快 87%
构建时间	4m 30s	3m 15s	2m 30s	快 44%
重建（使用缓存）	2m 10s	1m 30s	15s	快 88%
内存使用量	512MB	256MB	180MB	减少 65%

安全影响

镜像类型	漏洞	大小	风险
node:20 (Debian)	45-60 个 CVE	900MB	高
node:20-alpine	8-12 个 CVE	350MB	中
Alpine 多阶段构建	4-8 个 CVE	100MB	低
Distroless Node	2-4 个 CVE	120MB	极低

Agentic 优化

场景	命令	用途
快速重建	DOCKER_BUILDKIT=1 docker build --target build .	仅构建构建阶段
检查大小	docker images app --format "table {{.Repository}}\t{{.Size}}"	比较大小
分析层	docker history app:latest --human --no-trunc | head -20	查找较大的层
依赖审计	docker run --rm app npm audit --production	检查漏洞
清除缓存	docker builder prune --filter type=exec.cachemount	清除 BuildKit 缓存
本地测试	docker run --rm -p 3000:3000 app	快速本地测试

最佳实践

• 使用 Alpine 变体以缩小镜像
• 使用 npm ci，而非 npm install（确保构建可复现）
• 分离开发依赖和生产依赖
• 使用非 root 用户运行
• 在生产环境中使用多阶段构建
• 将 package.json 与源代码分层处理
• 添加 .dockerignore，排除 node_modules、测试文件

如需查看详细示例、高级模式和最佳实践，请参阅 REFERENCE.md。

相关技能

• container-development - 通用容器模式、多阶段构建和安全
• go-containers - Go 专属容器优化
• python-containers - Python 专属容器优化