Next.js の rewrite を基礎から応用まで完全解説

Next.js を使っていると、next.config.ts に登場する rewrites という設定を目にすることがあります。

こうした断片的な説明はよく見かけますが、次のような内容まで整理されている情報はあまり見かけません。

この記事では、Next.js の rewrite を 基礎 → 仕組み → 実務的なメリット → 設計上の注意点 → 削除という判断まで、順を追って解説します。

Next.js の rewrite の概要

rewrite は、URL を変えずに、サーバー側で別の URL にリクエストを転送する仕組みです。

リダイレクトとは違って、クライアントに見せずに裏側で交通整理をして、別の場所にアクセスするとも言い換えられます。

つまり、Next.js が リバースプロキシの役割を担います。

rewrite と redirect との違い

ここは混同されやすいポイントなので、先に整理します。

rewrite は 「内部転送」、redirect は「外部転送」と覚えると理解しやすいです。

rewrite の基本的な書き方

// next.config.ts
export default {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'http://localhost:8000/api/:path*',
      },
    ];
  },
};

// next.config.ts
export default {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'http://localhost:8000/api/:path*',
      },
    ];
  },
};

この設定により、クライアントから/api/users/にアクセスがあると、実際には以下にリクエストが投げられます。

http://localhost:8000/api/users/

http://localhost:8000/api/users/

つまり、sourceはクライアントがアクセスするURLであり、destinationは「Next.jsサーバー」が内部的に転送する先になります。

/:path* は ワイルドカードで、後続のパスをそのまま渡します。

rewrite が動作する仕組み

rewrite のリクエストの流れは次のとおりです。

クライアントは 「Next.js にアクセスした」という認識のままです。

また、rewrite が同一オリジン扱いになる理由については、 Next.js サーバーが代理で通信するため、次の二段構えになるからです。

その結果、次のような利点が生まれます。

rewrite を使うメリット

rewriteを使う場合、いくつかメリットがあります。

クライアント側の実装がシンプルになる

次のように、相対パスでAPIを呼べるのは大きなメリットです。

fetch('/api/agencies/');

fetch('/api/agencies/');

これにより、環境ごとのURL切り替えが不要になり、.envを意識しないでよくなります。

Docker 構成との相性が良い

Next.js とバックエンドが Docker 内で動いている場合、次のような内部ネットワーク名はブラウザから見られません。

http://backend:8000

http://backend:8000

rewrite を使えば、ブラウザはNext.jsにだけアクセスをし、Next.jsが内部ネットワーク経由で接続するという構図が成り立ちます。

CORS を考えなくて済む

rewrite は 同一オリジン扱いになるので、次のようなCORSを考えなくて済みます。

応用：環境分岐を含む rewrite 設定

実務では、以下のような構成がよく見られます。

async rewrites() {
  const isProduction =
    process.env.NEXT_PUBLIC_APP_ENV === 'production';

  const apiUrl = isProduction
    ? 'http://backend_kanteiman:8030'
    : 'http://localhost:8000';

  return [
    {
      source: '/api/:path*',
      destination: `${apiUrl}/api/:path*`,
      basePath: false,
    },
    {
      source: '/__auth_api__/:path*',
      destination: `${apiUrl}/auth/:path*`,
      basePath: false,
    },
  ];
}

async rewrites() {
  const isProduction =
    process.env.NEXT_PUBLIC_APP_ENV === 'production';

  const apiUrl = isProduction
    ? 'http://backend_kanteiman:8030'
    : 'http://localhost:8000';

  return [
    {
      source: '/api/:path*',
      destination: `${apiUrl}/api/:path*`,
      basePath: false,
    },
    {
      source: '/__auth_api__/:path*',
      destination: `${apiUrl}/auth/:path*`,
      basePath: false,
    },
  ];
}

この設計でできることは、次のとおりです。

設計としては筋が通っています。

「rewrite を使わないという」判断

rewrite はあくまで 選択肢の一つです。

以下のような構成では、rewrite は不要になります。

実際に、次のようなことが起きがちです。

つまり、「動くけど、理解しづらい構成」になりがちという問題点もあります。

そのため、次のような設計も健全といえます。

rewrite を使うべきかどうかの判断基準

rewrite が向いているケースは、例えば次のとおり。

逆に、次のような場合にはrewriteを使わないほうが良いです。

まとめ

• rewrite は Next.js のプロキシ機能
• URL を変えずに内部転送できる強力な仕組み
• CORS 回避や Docker 構成で特に有効
• しかし 使わない判断も正解
• 実際に使われていない rewrite は、削除して統一した方が良い

rewrite は「入れること」よりも、
「なぜ入れるのか」「なぜ外すのか」を説明できることが重要です。

設計をシンプルにするために rewrite を削除する、
それもまた 正しい Next.js の使い方です。