【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 #環境構築 #エラー解決 #初心者向け