← ./articles-ja

Next.jsでroutes-manifest.jsonが見つからない時は並列next buildを先に疑う

nextjsbuilddebuggingciagentsstatic-export

Next.jsで routes-manifest.json が見つからないエラーが出ると、まず設定ミスを疑いたくなります。

Vercelのroot directory、monorepoの出力先、キャッシュ、static export設定。これらは実際によくある原因です。

ただし、もう1つ見落としやすい原因があります。2つの next build が同じ .next/ ディレクトリへ同時に書き込んでいるケースです。

AIコーディングエージェント、並列CI、ローカルのタスクランナー、複数ターミナルを使っているなら、設定を書き換える前にここを確認したほうが早いことがあります。

症状

代表的なエラーは次のようなものです。

Cannot find module '<project>/.next/routes-manifest.json'

または:

The file ".next/routes-manifest.json" couldn't be found.

ファイルが .next/ の中にあるため、「Next.jsが必要な成果物を作れなかった」と見えます。それ自体は間違いではありません。ただし、原因がNext.js設定ではなく、別のビルドプロセスによって .next/ が削除・上書き・中途半端な状態にされた可能性があります。

なぜ並列ビルドで壊れるのか

next build は .next/ ディレクトリを自分の成果物置き場として使います。ビルド中はmanifest、server files、static pages、cacheなどをそこへ書き込みます。

同じプロジェクトフォルダで2つのビルドが走ると、両方が同じ .next/ を触ります。

build A -> .next/ へ書く
build B -> .next/ へ書く

競合は次のように起きます。

  1. build Aが .next/ の準備を始める
  2. build Bも同じ .next/ の準備を始める
  3. 片方が routes-manifest.json を書いている
  4. もう片方が同じ領域を読む、消す、または上書きする
  5. 片方のビルドが「manifestがない」と判断して落ちる

結果として、設定ミスに見えるエラーが出ます。しかし根本原因は、生成物ディレクトリを複数プロセスで共有したことです。

なぜ誤診しやすいのか

routes-manifest.json couldn't be found で検索すると、Vercel設定、monorepo、Turborepo/NXのキャッシュ、output directory設定などが多く出てきます。これらは有効な調査先です。

ただし、AIエージェントや並列作業の文脈では、別の問題が起きます。

たとえば2つのエージェントに別々の実装を任せ、両方が最後に npm run build を実行したとします。この場合、どちらも同じ .next/ に書き込みます。片方は成功し、片方だけ routes-manifest.json 欠落で落ちることがあります。

このとき失敗ログはNext.jsの設定エラーに見えますが、本当の問題はビルドの実行順序です。

確認手順

設定変更の前に、次を確認します。

  • 同じプロジェクトフォルダで別の next build が走っていなかったか
  • エージェント、CI job、npm script、別ターミナルが同時にbuildしていなかったか
  • 生成物を消して、1回だけ npm run build すると通るか
  • 失敗した並列ビルドと、成功した単独ビルドの間にコード変更がないか

PowerShellなら、ローカルでは次のように確認できます。

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

使うshellに合わせて安全な削除コマンドに置き換えてください。重要なのは、.next/ を触るビルドプロセスを1つにすることです。

修正: 最終ビルドを1回にする

AIエージェントを使うなら、ビルド責任を1か所に集めます。

agent A: source filesだけ編集
agent B: source filesだけ編集
orchestrator: 最後に1回だけ npm run build

並列worker全員に npm run build させないのがポイントです。

CIでも同じです。

job A: lint/typecheck
job B: unit tests
job C: build

どうしても複数jobでbuildが必要なら、作業ディレクトリを分けます。

  • 別checkout
  • 別worktree
  • 別artifact directory
  • 別CI workspace

ルールは単純です。sourceの並列チェックはよいが、同じbuild outputへの並列書き込みは避ける。

worktreeで隔離する

各エージェントやCI jobがどうしてもbuildするなら、worktreeを分けます。

git worktree add ../build-a --detach
git worktree add ../build-b --detach

それぞれのworktreeに別々の .next/ が作られるため、共有artifact競合を避けられます。

最後に変更を統合し、メインの作業ディレクトリで1回だけ正式なbuildを走らせます。

static export設定ミスとは別問題

Next.jsのstatic exportでは、robots.ts、sitemap.ts、RSS route handlerなどに force-static が必要になるケースがあります。

これは設定問題です。一方、並列 .next/ 破損は実行順序の問題です。

単独ビルドでも毎回失敗するなら、static export設定、route handler、monorepo設定、キャッシュを調べます。

複数ビルドが重なった時だけ失敗するなら、まずビルドを直列化してください。

static export固有の罠は、Next.jsのoutput: exportで詰まる5つの罠と回避策 で整理しています。

チェックリスト

.next/routes-manifest.json 欠落エラーが出たら、次の順で確認します。

  • 他の next build が走っていなかったか
  • 同じプロジェクトフォルダで並列buildしていないか
  • .next/ と out/ を消して単独buildする
  • 単独buildが通るなら、Next.js設定ではなくworkflowを直す
  • 単独buildでも落ちるなら、設定、monorepo、route、cacheを調べる

この順番にすると、ビルド成果物の競合をアプリケーションコードの問題として直そうとする遠回りを避けられます。

まとめ

routes-manifest.json が見つからないからといって、必ずNext.js設定が壊れているとは限りません。

2つの next build が同じ .next/ に書き込むと、生成物が壊れ、manifest欠落に見えることがあります。修正は、最終ビルドを1回に直列化するか、buildごとにworktreeやworkspaceを分けることです。

Next.js設定を触る前に、まず「同時にbuildしていなかったか」を確認してください。

参考