🤖

Claude Code で Next.jsビルドエラー!? 原因は NODE_ENV=development だった

に公開
Next.js
Node.js
開発環境
トラブルシューティング
Claude
tech

はじめに

Next.jsプロジェクトをClaude Codeで開発していたところ、興味深い現象に遭遇しました。

私のローカル環境ではpnpm buildが成功するのに、Claude Codeで実行すると失敗する。

CIも通っているし、コードに問題はないはず...🤔

調査の結果、Claude Code環境で自動的に設定されているNODE_ENV=developmentにより、より厳格なビルドチェックが行われていたことがわかりました。

同じ現象に遭遇した方や、AI開発ツールを使っている方の参考になればと思い、調査過程と学びを共有します。

※記事に技術的な誤りや不正確な記述がありましたら、コメント等でご指摘いただけると幸いです🙇

発生した現象

症状

Claude Code環境でpnpm buildを実行すると、以下のエラーが発生：

⚠ You are using a non-standard "NODE_ENV" value in your environment.
This creates inconsistencies in the project and is strongly advised against.
Read more: https://nextjs.org/docs/messages/non-standard-node-env

TypeError: Cannot read properties of null (reading 'useContext')
    at t.useContext (...)
    ...

> Export encountered errors on following paths:
	/foo/page: /foo
	/bar/page: /bar
	...

環境ごとの挙動の違い

環境 pnpm build 結果
ローカルターミナル ✅ 成功 ビルド完了
GitHub Actions CI ✅ 成功 テスト・ビルドともにパス
Claude Code ❌ 失敗 useContextエラー

「コードは同じなのに、なぜClaude Codeだけ？」

この疑問から調査が始まりました。

原因調査

ステップ1: 仮説「NODE_ENVが影響しているのでは？」

Next.jsはNODE_ENVの値によってビルド動作が変わります：

  • 未設定 or production: 本番モードでビルド（静的最適化、プリレンダリング）
  • development: 開発モードの動作が一部混在し、より厳格なチェックが行われる

もしかして環境ごとにNODE_ENVが違うのでは？

ステップ2: NODE_ENVの確認

仮説を検証するため、各環境でNODE_ENVを確認してみました。

ローカルターミナル:

$ echo "NODE_ENV=${NODE_ENV:-未設定}"
NODE_ENV=未設定

Claude Code環境:

$ echo "NODE_ENV=${NODE_ENV:-未設定}"
NODE_ENV=development

原因発見！

Claude Code環境ではNODE_ENV=developmentが自動的に設定されていました。

ステップ3: 検証

仮説を検証するため、ローカル環境で意図的にNODE_ENV=developmentを設定してビルドしてみました：

$ NODE_ENV=development pnpm build
⚠ You are using a non-standard "NODE_ENV" value in your environment.
TypeError: Cannot read properties of null (reading 'useContext')
...

再現成功！ やはりNODE_ENV=developmentが影響していました。

解決方法

Claude Code環境での対処法

NODE_ENVを明示的に解除してからビルドを実行：

$ unset NODE_ENV && pnpm build
✓ Compiled successfully
✓ Generating static pages
✓ Finalizing page optimization

成功！ 🎉

または、productionを明示的に指定：

$ NODE_ENV=production pnpm build

NODE_ENVはどこで設定されているのか？徹底調査

ところでこれは「どこで設定されているんだ？」という疑問を持ち（「自分がどこかで間違って設定しているのかも」という不安もあり）、できる限り調査しました。

ステップ1: package.jsonの確認

{
  "scripts": {
    "build": "next build"  // ✅ NODE_ENVの指定なし
  }
}

結果: ビルドスクリプトには環境変数の設定なし。

ステップ2: .envファイルの確認

.env.localを確認しましたが、NODE_ENVの記述はありませんでした。

結果: 問題なし。

ステップ3: Claude Code設定ファイルの確認

.claude/settings.jsonと.claude/settings.local.jsonを確認：

{
  "model": "...",
  "permissions": { ... }
  // 環境変数の設定なし
}

結果: 環境変数の設定は見つからず。

ステップ4: process.env.NODE_ENVのログ出力

最終手段として、next.config.mjsに直接ログを追加：

console.log("🔍 NODE_ENV during build:", process.env.NODE_ENV)

ビルドを実行した結果：

$ pnpm build

> next build

⚠ You are using a non-standard "NODE_ENV" value in your environment.
🔍 NODE_ENV during build: development
  ▲ Next.js 14.2.31
  ...

判明！ビルド開始時点で既にNODE_ENV=developmentが設定されていました。

結論

プロジェクト内の設定ファイルには一切NODE_ENVの指定がなく、通常のターミナルでも設定されていないことから、Claude Code本体がシェル環境として自動的に設定している可能性が高いです。（と思われます！）

NODE_ENV=productionに変更できないの？

「じゃあexport NODE_ENV=productionで永続的に変更できるのでは？」と思い、試してみました。

$ export NODE_ENV=production && echo "設定後: $NODE_ENV"
設定後: production

成功！...と思いきや、別のコマンドを実行すると：

$ echo "確認: $NODE_ENV"
確認: development

戻ってる！ 😱

Claude Codeは各Bashコマンド実行ごとに新しいシェルセッションを起動しているようで、その都度NODE_ENV=developmentを初期化しているようです。

つまり：

  • ❌ export NODE_ENV=productionだけでは永続的に変更できない
  • ✅ コマンド内で毎回指定する必要がある
  • ✅ またはunset NODE_ENV && ...で一時的に解除

おまけ：エラーは本当に問題だったのか？

ここまでで「Claude Code環境でビルドを成功させる方法」は分かりました。

最後に、そもそもこのエラーは本当に修正すべき問題なのか？ にも目を向けます。

useContextエラーの詳細

発生していたエラーはTypeError: Cannot read properties of null (reading 'useContext')でした。
ReactコンポーネントでuseContext()が実行されたけれど、Context Providerが存在しない状態を意味します。

なぜproductionでは起きないのか？

このエラーは、Next.jsの以下の挙動の違いによるものでした：

本番ビルド（NODE_ENV未設定/production）:

  • asyncデータフェッチを検出すると動的レンダリングと判断
  • プリレンダリングをスキップ
  • Contextは実行時に正しく初期化される
  • エラーなし ✅

開発ビルド（NODE_ENV=development）:

  • より厳格にプリレンダリングを試みる
  • ビルド時にContextの評価を試みる
  • この時点ではProviderが存在しない
  • エラー発生 ❌

調査結果

実際のコードを確認したところ：

  • ✅ Providerは適切に配置されている
  • ✅ 環境による条件分岐なし
  • ✅ すべてのClient Componentに'use client'あり
  • ⚠️ 開発ビルド時のみプリレンダリングで厳格チェック

結論: これは設計ミスではなく、NODE_ENV=developmentによる厳格なチェックが、実運用では発生しない状態を検出しているだけのようです。

Claude CodeのNODE_ENV=developmentは実は有益？

当初は「なんでここでだけビルドが失敗する？」と困惑しましたが、システムさえわかっていれば、これはこれで機能として有益な面もあります。

開発体験の向上

Claude CodeがNODE_ENV=developmentを設定していると思われる理由：

  • ホットリロードの有効化
  • 詳細なエラーメッセージ
  • デバッグ情報の出力
  • ソースマップの生成

潜在的な問題の早期発見

NODE_ENV=developmentでのnext buildは、以下のような潜在的な問題を顕在化させる可能性があります：

  • Server/Client Componentsの境界が不適切
  • React Contextの依存関係の問題
  • 動的レンダリングへの暗黙的な依存

より厳格なビルドチェックとして機能しているとも言えます。

本番環境で問題が起きる前に、開発段階で気づけるのは大きなメリットです。

今後の運用方針

この特性を理解した上で、以下のように運用を決めました：

Claude Code環境でビルド確認する場合

通常のビルド（問題検出モード）：

pnpm build  # エラーが出たら設計を見直すきっかけに

本番相当のビルド確認：

unset NODE_ENV && pnpm build

ローカル環境での確認

通常通り：

pnpm build

CI/CDでの最終確認

GitHub Actionsなどで自動チェック（NODE_ENVは未設定なので本番モードビルド）

まとめ

  • Claude Code環境ではNODE_ENV=developmentが自動設定されているようです
  • プロジェクトファイルには設定がなく、Claude Code本体がデフォルトで設定している可能性
  • 各コマンド実行ごとに初期化されるため、永続的な変更はできないようです
  • より厳格なビルドチェックが行われ、潜在的な設計問題を発見できるかもしれません
  • unset NODE_ENV && next buildで本番相当のビルド確認が可能です
  • AI開発ツールの「制約」は、「品質向上の機会」でもあるかもしれません

最初は「なぜエラーが出るんだ」と困惑しましたが、結果的にコードの品質を見直す良いきっかけになりました。

AI開発ツールならではの特性を理解して活用することで、より堅牢なアプリケーション開発ができそうです。

同じ現象に遭遇した方の参考になれば幸いです！

関連リンク:

Discussion