← ./articles-ja

環境依存バグはコード修正から始めない

debuggingwindowsnodejsnextjsworkflow

開発中にエラーが出ると、まずコードを直したくなります。

しかし、Windows、OneDrive、Node.js、Next.jsの組み合わせでは、コードが原因ではない失敗もよくあります。環境変数、ファイル同期、ビルド成果物の競合、エディタの型解決など、実装とは別の層で壊れることがあります。

環境依存バグでは、コード修正から始めると遠回りになります。先に「本当にコードが悪いのか」を切り分けます。

環境依存バグの典型例

環境依存バグには、いくつか分かりやすい形があります。

たとえば次です。

  • next build は通るのに next dev だけCSSで落ちる
  • tsc は通るのにVS Codeだけ型エラーを出す
  • あるPCではnpm installできるのに、別PCではdevDependenciesが入らない
  • ビルドは成功表示なのに、最後にプロセスがクラッシュする
  • .next/routes-manifest.json が突然見つからない

これらは、すべてアプリコードのバグとは限りません。むしろ、環境や実行手順が原因のことがあります。

個別の症状がすでに分かっている場合は、狭い記事から入るほうが早いです。next dev だけCSSで落ちるなら next devだけCSSが壊れる原因はNODE_ENV=productionだった、npm install --save-dev 後にdevDependenciesが見えないなら npm installでdevDependenciesが入らない時はNODE_ENV=productionを疑う、.next/routes-manifest.json が欠けるなら Next.jsでroutes-manifest.jsonが見つからない時は並列next buildを先に疑う を確認してください。

まず再現条件を固定する

最初にやることは、再現条件の固定です。

次をそのまま記録します。

Command:
Working directory:
Shell:
Node version:
npm version:
NODE_ENV:
OneDrive path:
Error output:

特に NODE_ENV は見落としやすいです。NODE_ENV=production が混ざると、開発サーバーやnpm installの挙動が変わります。

PowerShellなら次で確認できます。

$env:NODE_ENV
node -v
npm -v
Get-Location

エラー本文だけでなく、実行したシェルと作業ディレクトリも残します。Windowsでは、PowerShell、Git Bash、cmdでクォートや変数展開が変わるためです。

「片方だけ壊れる」は環境を疑う

次のように片方だけ壊れる場合は、環境差分を疑います。

next build: pass
next dev: fail

または次です。

npx tsc --noEmit: pass
VS Code Problems: fail

この状態でコードを書き換えると、通っていた経路まで壊すことがあります。

まずは「壊れる経路」と「壊れない経路」の違いを見ます。

  • 読んでいる設定ファイルは同じか
  • 実行時の環境変数は同じか
  • TypeScriptのバージョンは同じか
  • ビルド成果物を共有していないか
  • OneDrive同期中のフォルダに高頻度書き込みしていないか

差分が見つかるまでは、コード修正を保留します。

ビルド成果物の競合を避ける

AIエージェントや複数ターミナルで作業していると、同時に next build を走らせることがあります。

これは危険です。同じ .next/ に複数プロセスが同時に書くと、一方が生成中のファイルをもう一方が読みに行き、存在しないファイルとして失敗することがあります。

症状だけ見ると、設定ミスやNext.jsのバグに見えます。

Cannot find module '.next/routes-manifest.json'

しかし原因が並列ビルドなら、コードを直しても解決しません。最後に1つのプロセスでクリーンビルドするのが確認方法です。

Remove-Item -Recurse .next, out
npm run build

削除対象は必ずプロジェクト内のビルド成果物に限定します。広いパスに対して再帰削除をかけないようにします。

OneDrive配下では書き込み先を見る

WindowsでOneDrive配下にプロジェクトがある場合、node_modules、.next、dist のような高頻度書き込みディレクトリが同期とぶつかることがあります。

すべてを外へ出せるとは限りませんが、少なくとも次は確認します。

  • node_modules がOneDrive同期対象に直置きされていないか
  • junctionで外部ディレクトリへ逃がしているか
  • ビルド中にOneDriveが同期エラーを出していないか
  • クラッシュ後に古い成果物を成功扱いしていないか

特に dist や out の鮮度確認は大切です。ビルドが落ちたのに古い成果物が残っていると、成功したように見えます。

OneDrive配下のNode.jsプロジェクトで node_modules が絡む場合は、OneDrive上のNode.js開発はnode_modulesをjunctionで外へ逃がす も合わせて確認すると、同期由来の問題を切り分けやすくなります。

コードを直すのは切り分け後

環境依存の可能性を潰したあとで、初めてコードを直します。

良い順序は次です。

  1. エラーをそのまま保存する
  2. コマンド、シェル、環境変数、作業ディレクトリを記録する
  3. 通る経路と落ちる経路を比較する
  4. ビルド成果物や同期の競合を除外する
  5. 最小再現でコード起因か確認する
  6. 必要な最小差分だけ直す

この順序にすると、「推測で直したら別の場所が壊れた」という失敗を減らせます。

AIに頼む時の依頼文

AIエージェントに調査させる場合は、最初から修正を頼まないほうがよい場面があります。

たとえば次のように依頼します。

next devだけCSS parse errorになる。next buildは通る。
まずコード変更せず、環境変数、Next.js設定、dev/build差分を調査して。
原因候補と検証コマンドを出してから、必要なら最小修正して。

これでAIがいきなりCSSやwebpack設定を書き換えるリスクを下げられます。

まとめ

環境依存バグは、コード修正から始めないほうが安全です。

片方のコマンドだけ壊れる、特定の端末だけ壊れる、ビルド成果物が突然欠ける、といった症状では、環境変数、シェル、OneDrive、並列ビルド、エディタの型解決を先に見ます。

原因の層を間違えなければ、修正は小さく済みます。逆に、環境の問題をコードで回避しようとすると、動いていた実装まで不安定になります。