【Docker初心者】Next.js + TypeScript環境構築で躓いた全エラーと解決法

はじめに

Docker環境でNext.js + TypeScriptの開発環境を構築する際に遭遇したエラーと解決方法を記録します。同じエラーで困っている方の参考になれば幸いです。

完成した設定ファイル

Dockerfile

# nodeのバージョンを明示的に指定
FROM node:18-alpine

# 作業ディレクトリを設定
WORKDIR /app

# package.jsonを先にコピー（Dockerキャッシュ活用）
COPY package*.json ./
RUN npm install

# アプリケーションコードをコピー
COPY . .

# プロダクション用ビルド
RUN npm run build

# ポート番号を明示
EXPOSE 3001

# Next.jsを指定ポートで起動
CMD ["npm", "start", "--", "-p", "3001"]

docker-compose.yml

services:
  app:
    build: .
    ports:
      - "3001:3001"
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    environment:
      - CHOKIDAR_USEPOLLING=true
      - WATCHPACK_POLLING=true
      - NODE_ENV=development
    command: npm run dev -- -p 3001

遭遇したエラーと解決方法

エラー1: プロダクションビルドが見つからない

エラーメッセージ:

Error: Could not find a production build in the '.next' directory. 
Try building your app with 'next build' before starting the production server.

原因:

npm startでプロダクションサーバーを起動しようとした
しかし.nextフォルダがvolumesでホスト側の空フォルダに上書きされた

解決策:

# volumes設定で.nextフォルダを保護
volumes:
  - .:/app
  - /app/node_modules
  - /app/.next  # ← これを追加

または

# 開発モードで起動
command: npm run dev -- -p 3001

エラー2: ポート番号不一致エラー

エラーメッセージ:

app-1  |   - Local:        http://localhost:3000
# しかしブラウザで3001にアクセスして接続できない

原因:

Next.jsはデフォルトで3000ポートで起動
docker-compose.ymlで3001:3001のマッピング設定
ポート番号が一致していない

間違った設定:

EXPOSE 3001
CMD ["npm", "start"]  # ← ポート指定なし

解決策:

EXPOSE 3001
CMD ["npm", "start", "--", "-p", "3001"]  # ← ポートを明示的に指定

エラー3: ファイル変更が反映されない

現象:

コードを変更してもブラウザに反映されない
ホットリロードが動作しない

原因:

DockerコンテナとホストOS間でファイル変更通知が正常に伝わらない
MacやWindowsとLinuxコンテナ間の仕様の違い

解決策:

environment:
  # ファイル監視をポーリング方式に変更
  - CHOKIDAR_USEPOLLING=true    # Next.jsのファイル監視
  - WATCHPACK_POLLING=true      # Webpackのファイル監視
  - NODE_ENV=development        # 開発モード有効化
command: npm run dev -- -p 3001  # 開発サーバーで起動

エラー4: YAML構文エラー

エラーメッセージ:

ERROR: yaml.parser.ParserError: while parsing a block mapping

原因:

# 間違った書き方
services:
  app:
    build:
      - "3001:3001"  # ← buildセクションにportsを書いている

解決策:

# 正しい書き方
services:
  app:
    build: .
    ports:
      - "3001:3001"

エラー5: version廃止警告

警告メッセージ:

WARN[0000] the attribute `version` is obsolete, it will be ignored

原因:

# 古い書き方
version: '3.8'
services:
  app:

解決策:

# 新しい書き方（versionは不要）
services:
  app:

エラー6: node_modulesの競合

現象:

コンテナ起動時にライブラリが見つからない
Module not foundエラーが発生

原因:

ホスト側のnode_modules（Mac/Windows用）とコンテナ内のnode_modules（Linux用）が競合
バイナリファイルの互換性問題

解決策:

volumes:
  - .:/app
  - /app/node_modules  # ← コンテナ内のnode_modulesを保護

エラー7: Git push時のコンフリクト

エラーメッセージ:

! [rejected] main -> main (fetch first)
error: failed to push some refs to 'https://github.com/username/OTHELLO.git'
hint: Updates were rejected because the remote contains work that you do not have locally.

原因:

GitHubでリポジトリ作成時にREADMEを作成
ローカルとリモートで履歴が異なる

解決策:

# 1. マージ方式を設定
git config pull.rebase false

# 2. リモートの変更を取得
git pull origin main --allow-unrelated-histories

# 3. プッシュ
git push origin main

エラー8: Nodeバージョン曖昧指定

現象:

異なる環境で動作が不安定
チーム開発で環境が統一されない

原因:

# 曖昧な指定
FROM node

解決策:

# 明確なバージョン指定
FROM node:18-alpine

設定項目の詳細解説

環境変数の役割

environment:
  # ファイル変更を定期的にチェック（重いが確実）
  - CHOKIDAR_USEPOLLING=true
  
  # Webpack側の監視も同様に設定
  - WATCHPACK_POLLING=true
  
  # 開発モードで詳細エラー表示
  - NODE_ENV=development

volumes設定の重要性

volumes:
  # ホストとコンテナの同期
  - .:/app
  
  # OS依存ファイルの保護
  - /app/node_modules
  
  # ビルド結果の保護
  - /app/.next

ポート設定の統一

# docker-compose.yml
ports:
  - "3001:3001"  # ホスト:コンテナ

# Dockerfile
EXPOSE 3001
CMD ["npm", "start", "--", "-p", "3001"]

成功時の確認方法

1. 正常起動ログ

docker-compose up --build

成功時の表示:

app-1  |   ▲ Next.js 14.2.6
app-1  |   - Local:        http://localhost:3001
app-1  |   ✓ Ready in 701ms

2. ブラウザアクセス

http://localhost:3001 にアクセスしてNext.jsページが表示される

3. ホットリロード確認

ファイルを編集して自動でブラウザが更新される

まとめ

Docker環境でのNext.js開発で重要なポイント：

ポート番号の統一: Dockerfile、Compose、アプリ設定を一致させる
ファイル監視設定: Docker環境ではポーリング方式が必要
ボリューム設定: 必要なフォルダの適切な分離
バージョン明示: 再現可能な環境のための明確な指定

これらのエラーと解決方法を理解することで、Docker環境での開発がスムーズになります。

#Docker #Next.js #TypeScript #環境構築 #エラー解決 #初心者向け