ビルドエラーの読み方：失敗ログのどこを見るか

入門 | 8分 で読める | 2026.07.10

公式ドキュメント
開発ツールデバッグ

今回やること

npm run buildが失敗した時に、長いログから最初に直す場所を見つけます。

最後の失敗表示ではなく、最初の具体的で対処可能なエラーを探します。

ビルドログの具体的な診断と後続の失敗表示を分け、示されたソースファイルの場所と直前を確認して一件ずつ直し再実行する図

この記事では次の手順を練習します。

  1. 実行したコマンドを確認する
  2. 最初の具体的な診断を探す
  3. ファイル名と行番号を見る
  4. 原因と後続エラーを分ける
  5. 1件だけ直して同じコマンドを再実行する

例として使うログ

次のログを読んでみましょう。

> sample-app@1.0.0 build
> astro build

src/pages/index.astro:4:20
Cannot find module '../components/Button.astro'

Build failed with 1 error
npm ERR! command failed
npm ERR! exit code 1

下のexit code 1は失敗した結果です。原因の候補は、その上にあるCannot find moduleです。

Step 1：失敗したコマンドを確認する

先頭付近で、何を実行して失敗したかを確認します。

> astro build

同じnpm run buildでも、内部ではAstro、TypeScript、Viteなど別のtoolが動きます。toolが分かると、公式資料や検索語を絞れます。

package.jsonのscriptsも確認します。

npm pkg get scripts.build

Step 2：最初の具体的な診断を探す

ログを上から追い、次のような具体的な文を探します。

  • Cannot find module
  • Type ... is not assignable
  • Unexpected token
  • Permission denied
  • JavaScript heap out of memory

警告ではなく、error、failed、ファイルpathを手がかりにします。

Step 3：ファイル名と行番号を見る

例では次の場所が示されています。

src/pages/index.astro:4:20

これは通常、4行目・20文字目付近です。指定行だけでなく、直前のimportや括弧も見ます。

sed -n '1,10p' src/pages/index.astro

エラー位置は「toolが異常に気づいた場所」であり、「間違いを書いた場所」とは限りません。

Step 4：原因と結果を分ける

1つの原因から複数の後続エラーが出ることがあります。

Cannot find module '../components/Button.astro'
Failed to compile page
Build failed
Command exited with code 1

まずmoduleを見つけられない原因を確認します。後ろ3行を別々の不具合として直す必要はありません。

最初の診断最初に確認する場所
module not foundimport文字列、実際のpath、ファイル名
type mismatch期待する型、実際の値、型定義
syntax error指示行の直前、括弧や引用符
permission denied実行主体、対象path、権限
out of memory入力規模、生成loop、memory使用量

Step 5：直前の変更を見る

buildが以前は成功していたなら、直前の差分を確認します。

git status --short
git diff

無関係な変更まで戻さず、エラーのpathと差分が重なる場所から見ます。

Step 6：1件直して再実行する

原因候補を一度に全部変えません。importの大文字小文字が違うなら、そこだけ直して同じcommandを再実行します。

npm run build

最初のエラーが消えたら、次に現れた最初のエラーへ進みます。この繰り返しで原因と修正の対応を保てます。

成功を確認する

修正後に、最初と同じcommandを実行します。

npm run build

成功条件は次の3つです。

  • exit codeが0
  • 最初の具体的なエラーが消えた
  • build成果物が生成された

よくあるつまずき

最後の行だけ検索する

exit code 1だけでは原因を絞れません。最初の具体的な診断を検索します。

型エラーをanyで消す

表示を消しても仕様のずれは残ります。期待する型と実際の値を比べます。

複数箇所を同時に直す

どの変更で直ったか分からなくなります。1件ずつ再実行します。

練習

次のログで、最初に確認する3点を書いてください。

src/components/Card.tsx:18:7
Type 'string | undefined' is not assignable to type 'string'
Build failed
exit code 1

確認基準は次のとおりです。

  1. Card.tsxの18行目付近を見る
  2. undefinedになる入力経路を確認する
  3. 必須のstringなのか、未設定を許す仕様なのか確認する

exit code 1を直接直そうとしていなければ正しい方向です。

まとめ

  • 失敗commandを確認する
  • 最初の具体的な診断を探す
  • ファイル、行、直前の文脈を見る
  • 原因と後続エラーを分ける
  • 1件だけ直し、同じcommandを再実行する

次のステップ

原因候補を記録する時はエラー調査テンプレートを使ってみましょう。

参考リソース

おすすめ記事

← 一覧に戻る
PR
PR
PR
PR