[備忘録] Docker環境で発生した node_modules 破損エラーについて

概要

Docker環境でポートフォリオのページを作成中、docker compose logs -f web でログ確認したところ、
Cannot find module '/app/node_modules/vite/dist/node/chunks/dist.js' および npm warn tar TAR_ENTRY_ERROR ENOENT が大量に発生していた。

そのため、node_modules の破損・不整合が疑われる状態だった。

影響

Viteの起動が失敗し、ローカルホストを開いたところインターネットサーバーエラーが発生した。

発生したエラーの原因について

web サービスが ./frontend:/appをマウントしており、/app/node_modulesがホスト側状態の影響を受ける構成だった。
(ホストとコンテナの node_modules を分離できておらず、依存参照先が混在しやすい不安定な構成だった)
その結果、node_modules が壊れた状態になった

ホストとコンテナについて
• ホスト : 今回の作業環境 (/Users/.../frontend)
• コンテナ : Dockerで起動している隔離環境

ホストとコンテナで同じnode_modulesを実質共有・上書きし合うと、OS差分やタイミング差で壊れやすくなる

修正内容

今回はdocker-compose.yamlファイルを下記の内容で修正したのち、
docker compose up -d web コマンドで立ち上げ直した。
その後、npm run dev コマンドを実行することでローカルホストの画面を確認した。

修正箇所

• web.volumes に web_node_modules:/app/node_modulesを追加
• volumes に web_node_modules を追加
• web.command を npm ci から npm install に変更

docker-compose.yaml

〜〜省略〜〜
  web:
    image: node:24-alpine
    working_dir: /app
    volumes:
      - ./frontend:/app
    　// 追記
      - web_node_modules:/app/node_modules
    ports:
      - "5173:5173"
    // 変更
    command: sh -c "npm install && npm run dev -- --host 0.0.0.0 --port 5173"
    environment:
      VITE_PROXY_TARGET: "http://api-nginx"

volumes:
  dbdata:
  // 追記
  web_node_modules:

ボリュームについて

ボリューム:
コンテナ外に保持される永続ストレージのこと。
node_modules のようにコンテナ内で使いたいデータを安定保持できます。

services.web.volumes : webコンテナにボリュームを使う指定
ルート直下の volumes : Docker管理ボリュームの定義場所(名前の宣言)

修正内容の解説

web.volumes に web_node_modules:/app/node_modulesを追加

• node_modules をコンテナ専用ボリュームに分離できる
• ホスト側 node_modulesの破損やOS差分の影響を受けにくくなる

volumes に web_node_modules を追加

• 専用ボリュームを明示定義し、再起動後も整合した依存を維持しやすくする

web.command を npm ci から npm install に変更

• 今回は lockfile 不整合/欠落が混在していたため、ci だと失敗しやすかった
• install で依存解決を行い、まず起動安定を優先した

npm ciとnpm installコマンドの違い
• npm install : package.jsonを基に、npmでパッケージをインストールする。
• npm ci : package-lock.jsonを基に、npmでパッケージをインストールする。

※ 参考
https://qiita.com/yutoun/items/e580bcad5e73ccc81390