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 ベースのイメージ（フルサイズの約900MBに対して約100MB）
• ビルドと実行環境を分離するマルチステージビルド
• node_modules 用の BuildKit キャッシュマウント
• 本番環境用の依存関係のみをインストール
• 非 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分
• 2回目以降のビルド（パッケージに変更がない場合）：約10～20秒
• 2回目以降のビルド（パッケージに変更がある場合）：約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	非常に低

エージェント向けの最適化

コンテキスト	コマンド	目的
高速な再ビルド	DOCKER_BUILDKIT=1 docker build --target build .	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 install ではなく npm ci を使用します（再現可能なビルド）
• 開発用と本番用の依存関係を分けます
• 非 root ユーザーとして実行します
• 本番環境ではマルチステージビルドを使用します
• package.json をソースコードとは別のレイヤーに配置します
• node_modules やテストを除外するために .dockerignore を追加します

詳細な例、高度なパターン、ベストプラクティスについては、REFERENCE.md を参照してください。

関連スキル

• container-development - 一般的なコンテナーのパターン、マルチステージビルド、セキュリティ
• go-containers - Go 固有のコンテナー最適化
• python-containers - Python 固有のコンテナー最適化