今回やること
ビルドエラーは、ログが長く見えるため初心者には怖く見えます。
ビルドエラーは、全部を上から読むのではなく、最初に壊れた場所を探します。
この記事では、npm run build が失敗した時に、どこを見るかを整理します。
Step 1: 最後だけ見ない
ビルドが失敗すると、最後に次のような表示が出ることがあります。
Command failed with exit code 1
これは「失敗した」という結果であって、原因ではありません。
見るべきなのは、その少し上にある具体的なエラーです。
Cannot find module '../components/Button.astro'
最後の行だけで判断せず、最初に具体的なエラーが出た場所まで戻ります。
Step 2: ファイル名と行番号を探す
多くのビルドエラーには、ファイル名や行番号が含まれます。
src/pages/index.astro:12:8
これは、src/pages/index.astro の12行目付近に問題があるという意味です。
まず確認すること:
- ファイル名
- 行番号
- エラー文
- 直前に変更した箇所
Step 3: 原因と結果を分ける
ログには、原因と結果が混ざります。
例:
Failed to resolve import "../components/Hero.astro"
Could not build page /index.html
Build failed
この場合、原因は Failed to resolve import です。Build failed は結果です。
| ログ | 役割 |
|---|---|
| Failed to resolve import | 原因 |
| Could not build page | 影響 |
| Build failed | 結果 |
エラー調査では、原因に近い行を探します。
Step 4: よくある種類
| エラー | よくある原因 |
|---|---|
| Cannot find module | importパス違い、ファイル名違い |
| Unexpected token | 文法ミス、Markdownの崩れ |
| Property does not exist | 型やデータ構造の不一致 |
| Invalid frontmatter | Markdown先頭の設定ミス |
| ENOENT | ファイルが存在しない |
同じエラー文でも、プロジェクトによって原因は変わります。まず該当ファイルを開き、直近の変更を見るのが近道です。
Step 5: Markdown記事でよくあるエラー
情報保管庫のようなMarkdown記事では、frontmatterのミスがよくあります。
---
title: "記事タイトル"
tags: ["HTML", "CSS"
date: "2026-07-10"
---
この例では、tags の ] が不足しています。
また、コードフェンスの閉じ忘れもよくあります。
```js
console.log("hello");
## 次の見出し
この場合、見出しまでコード扱いになってしまいます。
Step 6: 直前の変更から見る
ビルドが急に落ちた場合、原因は直前の変更にあることが多いです。
git diff
確認すること:
- 追加したファイル
- 変更したimport
- 変更したfrontmatter
- 画像パス
- 設定ファイル
全部を疑うより、直前に触った範囲から狭めます。
実践メモ: ビルドログは「失敗した結果」ではなく「最初に壊れた場所」を探す読み物です。
まとめ
ビルドエラーでは、最後の Build failed ではなく、最初に出た具体的なエラー、ファイル名、行番号を見ます。
原因と結果を分け、直前の変更範囲から確認すると、長いログでも落ち着いて読めます。
