Docker: build failed の原因と解決策

概要

Dockerイメージのビルド中にエラーが発生し、イメージの作成に失敗した状態です。

エラーメッセージ

ERROR: failed to solve: process "/bin/sh -c npm install" did not complete successfully: exit code: 1

または

COPY failed: file not found in build context or excluded by .dockerignore

原因

Dockerfile構文エラー: コマンドの誤り
ファイル不足: COPYするファイルが存在しない
ベースイメージ問題: イメージが取得できない
ビルドコンテキスト: 必要なファイルが含まれていない

解決策

1. ビルドコンテキストの確認

1
2
3
4
5
# ビルドコンテキストに含まれるファイルを確認
docker build --no-cache -t myapp . 2>&1 | head -20

# .dockerignoreを確認
cat .dockerignore

2. マルチステージビルド

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# ビルドステージ
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# 実行ステージ
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/main.js"]

3. キャッシュの活用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
FROM node:18-alpine
WORKDIR /app

# 依存関係のみ先にコピー（キャッシュ効率向上）
COPY package*.json ./
RUN npm ci --only=production

# ソースコードをコピー
COPY . .
RUN npm run build

4. ベースイメージのタグ固定

1
2
3
4
5
# 悪い例：latest は予測不能
FROM node:latest

# 良い例：バージョンを固定
FROM node:18.19.0-alpine3.19

5. 権限問題の解決

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
FROM node:18-alpine

# 非rootユーザーを作成
RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -D appuser

WORKDIR /app
COPY --chown=appuser:appgroup . .

USER appuser
CMD ["node", "server.js"]

6. ビルド引数の使用

1
2
3
4
5
6
7
ARG NODE_ENV=production
ARG API_URL

ENV NODE_ENV=${NODE_ENV}
ENV API_URL=${API_URL}

RUN npm run build

1
2
3
4
docker build \
  --build-arg NODE_ENV=development \
  --build-arg API_URL=https://api.example.com \
  -t myapp .

7. デバッグ用のビルド

1
2
3
4
5
6
7
8
# 特定のステージまでビルド
docker build --target builder -t myapp:debug .

# ビルドログを詳細に
docker build --progress=plain -t myapp .

# キャッシュを使わない
docker build --no-cache -t myapp .

8. .dockerignore の最適化

# .dockerignore
node_modules
.git
.gitignore
*.md
.env*
dist
coverage
.nyc_output

9. ヘルスチェックの追加

1
2
3
4
5
6
7
8
9
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

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

10. BuildKitの活用

1
2
3
4
5
# BuildKitを有効化
export DOCKER_BUILDKIT=1

# シークレットのマウント
docker build --secret id=npmrc,src=$HOME/.npmrc -t myapp .

1
2
3
4
# syntax=docker/dockerfile:1
FROM node:18-alpine
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci

よくある間違い

WORKDIR を設定せずに相対パスを使用
apt-get update と install を別のRUNで実行
巨大なビルドコンテキスト（node_modulesを含む）
ENTRYPOINTとCMDの違いを理解していない

概要

エラーメッセージ

原因

解決策

1. ビルドコンテキストの確認

2. マルチステージビルド

3. キャッシュの活用

4. ベースイメージのタグ固定

5. 権限問題の解決

6. ビルド引数の使用

7. デバッグ用のビルド

8. .dockerignore の最適化

9. ヘルスチェックの追加

10. BuildKitの活用

よくある間違い

Docker の他のエラー