Next.js buildエラーの原因と解決方法|初心者向け完全ガイド

Next.jsでプロジェクトを開発していると、ビルド時に予期しないエラーが発生することがあります。本記事では、Next.js buildエラーの主な原因から解決手順まで、初心者向けに詳しく解説します。

Next.js buildエラーとは
Next.js buildエラーの主な原因
Next.js buildエラーの解決手順
一般的な解決コード例
よくある間違いと対処法
トラブルシューティングチェックリスト
まとめ

Next.js buildエラーとは

Next.jsのnpm run buildまたはyarn buildコマンド実行時に発生するエラーです。開発環境では正常に動作していても、本番環境のビルド時にエラーが出ることが多くあります。これは、開発モードと本番モードで実行される処理が異なるためです。

Next.js buildエラーの主な原因

1. TypeScriptの型エラー

Next.jsは開発時にTypeScriptの型チェックを実行します。開発環境では型エラーを無視して実行される場合もありますが、ビルド時には厳密にチェックされます。

2. ESLintルール違反

プロジェクトに.eslintrcの設定がある場合、ビルド時にESLintによるチェックが実行されます。ルール違反があるとビルドが失敗します。

3. 外部パッケージの互換性問題

インストールしたnpmパッケージがNext.jsのバージョンと互換性がない場合、ビルドエラーが発生します。

4. 環境変数の不足

ビルド時に必要な環境変数が設定されていないと、エラーが発生することがあります。

5. ファイルパスの問題

WindowsとmacやLinuxではファイルパスの表記方法が異なり、これが原因でビルドエラーが発生することがあります。

Next.js buildエラーの解決手順

ステップ1: エラーメッセージの確認

まずは、ターミナルに表示されるエラーメッセージを詳しく読みましょう。エラーメッセージには、問題の原因と発生した行番号が記載されています。

npm run build
# または
yarn build

エラーメッセージの最後の部分を見ると、「error in」という表記で問題があるファイルが示されます。

ステップ2: TypeScriptエラーの確認

エラーメッセージに「Type error」と表示されている場合は、TypeScriptの型定義に問題があります。以下のコマンドで、型チェックを単独で実行できます。

npx tsc --noEmit

このコマンドで詳細な型エラーを確認し、ファイルの型定義を修正します。

ステップ3: ESLintエラーの確認

ESLintが原因の場合は、以下のコマンドで詳細を確認できます。

npx eslint . --ext .ts,.tsx,.js,.jsx

表示されるルール違反を修正するか、.eslintrcの設定を調整します。

ステップ4: node_modulesの再インストール

パッケージの依存関係が破損している可能性があります。以下の手順で解決することがあります。

rm -rf node_modules
rm package-lock.json  # npm使用時
npm install

Yarnを使用している場合は、yarn.lockを削除してからyarn installを実行します。

ステップ5: キャッシュのクリア

Next.jsのキャッシュが原因でエラーが発生することもあります。

rm -rf .next
npm run build

一般的な解決コード例

例1: TypeScript型エラーの修正

以下は、Reactコンポーネントで型エラーが発生している例と、その修正方法です。

// ❌ エラーが発生するコード
const MyComponent = ({ name }) => {
  return <div>{name}</div>;
};

// ✅ 修正後のコード
interface Props {
  name: string;
}

const MyComponent = ({ name }: Props) => {
  return <div>{name}</div>;
};

export default MyComponent;

例2: 非同期処理のエラー処理

getStaticPropsやgetServerSidePropsで発生しやすいエラーと修正方法です。

// ❌ エラーが発生するコード
export async function getStaticProps() {
  const res = await fetch('https://api.example.com/data');
  const data = await res.json();
  
  return {
    props: {
      data,
    },
  };
}

// ✅ 修正後のコード
export async function getStaticProps() {
  try {
    const res = await fetch('https://api.example.com/data');
    if (!res.ok) throw new Error('API error');
    
    const data = await res.json();
    
    return {
      props: {
        data,
      },
      revalidate: 60, // ISR設定
    };
  } catch (error) {
    return {
      notFound: true,
      revalidate: 10,
    };
  }
}

例3: 環境変数の設定

環境変数が原因でビルドエラーが発生する場合の対処法です。

// .env.local ファイルを作成
NEXT_PUBLIC_API_URL=https://api.example.com
DATABASE_URL=postgresql://user:password@localhost/dbname

// pages/api/example.ts
export default function handler(req, res) {
  const apiUrl = process.env.NEXT_PUBLIC_API_URL;
  const dbUrl = process.env.DATABASE_URL;
  
  if (!apiUrl) {
    return res.status(500).json({ error: 'Missing API URL' });
  }
  
  res.status(200).json({ success: true });
}

例4: next.config.jsの設定

next.config.jsでビルド設定を調整する例です。

/** @type {import('next').NextConfig} */
const nextConfig = {
  // TypeScriptエラーを無視する場合（非推奨）
  typescript: {
    ignoreBuildErrors: true,
  },
  
  // ESLintエラーを無視する場合（非推奨）
  eslint: {
    ignoreDuringBuilds: true,
  },
  
  // 画像最適化設定
  images: {
    domains: ['example.com'],
  },
  
  // リダイレクト設定
  async redirects() {
    return [
      {
        source: '/old-path',
        destination: '/new-path',
        permanent: true,
      },
    ];
  },
};

module.exports = nextConfig;

よくある間違いと対処法

間違い1: next.config.jsの構文エラー

next.config.jsに構文エラーがあるとビルルが失敗します。JavaScriptの基本的な構文を確認してください。

// ❌ 間違い：セミコロンやカンマの忘れ
const nextConfig = {
  typescript: {
    ignoreBuildErrors: true
  } // ← カンマがない
  eslint: {
    ignoreDuringBuilds: true,
  },
};

// ✅ 正しい書き方
const nextConfig = {
  typescript: {
    ignoreBuildErrors: true,
  },
  eslint: {
    ignoreDuringBuilds: true,
  },
};

module.exports = nextConfig;

間違い2: サーバーサイドコードの混在

クライアントサイドのコンポーネントにサーバーサイドの機能を書くとエラーになります。

// ❌ 間違い：クライアントコンポーネントでDBを直接使用
export default function Page() {
  const users = db.query('SELECT * FROM users'); // エラー
  
  return <div>{users.map(u => u.name)}</div>;
}

// ✅ 正しい書き方：getStaticPropsを使用
export async function getStaticProps() {
  const users = await db.query('SELECT * FROM users');
  
  return {
    props: { users },
    revalidate: 60,
  };
}

export default function Page({ users }) {
  return <div>{users.map(u => u.name)}</div>;
}

間違い3: 相対パスの誤り

ファイルのインポートパスが誤っていてもビルド時に検出されます。

// ❌ 間違い
import { Button } from '../../../components/Button';

// ✅ パスエイリアスを使用
// tsconfig.json に設定を追加
{
  \"compilerOptions\": {
    \"baseUrl\": \".\",
    \"paths\": {
      \"@components/*\": [\"components/*\"],
      \"@lib/*\": [\"lib/*\"]
    }
  }
}

// こう書く
import { Button } from '@components/Button';

間違い4: 未使用の変数やインポート

ESLintのルールによっては、未使用の変数でビルドが失敗します。

// ❌ 未使用の変数
const MyComponent = ({ name, unused }) => {
  return <div>{name}</div>;
};

// ✅ 不要な変数を削除
const MyComponent = ({ name }: { name: string }) => {
  return <div>{name}</div>;
};