できない.dev

Next.js の Route Handler で CORS エラーが出て呼び出せない

Route Handler の CORS エラーは、Access-Control-Allow-Origin を返し OPTIONS ハンドラを書けば直る。
Route Handler には自動の CORS が無いためだ。

公開: 更新:

症状できない
curl -si -H "Origin: https://app.example.com" http://localhost:3001/api/foo
…
Keep-Alive: timeout=5
Transfer-Encoding: chunked
{"ok":true}

2026-10-06 に node:20(Next.js 16.3.8 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細

要約

Next.js の Route Handler は Express のような自動 CORS が無いため、Response ヘッダーを自分で設定し、OPTIONS ハンドラを実装する ことで対応する。
クッキー連携時はオリジンを具体名で指定し Allow-Credentials: true を返す。

実行例

node:20 で Next.js 16.3.8 の開発サーバーを動かし、curl で Origin 付きのリクエストを送った。
CORS ヘッダーを付けない GET と、OPTIONS 未実装のプリフライト(自動で 204 が返り allow は付く)には、access-control-allow-origin が付かなかった。
GET にヘッダーを足して同じファイルに OPTIONS を実装すると、どちらの応答にも許可オリジンが返った。
プリフライトには、許可メソッドとヘッダーも付いた。

$ curl -si -H "Origin: https://app.example.com" http://localhost:3001/api/foo
HTTP/1.1 200 OK
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
content-type: application/json
Date: Tue, 06 Oct 2026 00:50:58 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked
 
{"ok":true}
$ curl -si -X OPTIONS -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: GET" http://localhost:3001/api/foo
HTTP/1.1 204 No Content
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
allow: GET, HEAD, OPTIONS
Date: Tue, 06 Oct 2026 00:50:58 GMT
Connection: keep-alive
Keep-Alive: timeout=5
$ curl -si -H "Origin: https://app.example.com" http://localhost:3001/api/foo
HTTP/1.1 200 OK
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
access-control-allow-origin: https://app.example.com
content-type: application/json
Date: Tue, 06 Oct 2026 00:50:59 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Transfer-Encoding: chunked
 
{"ok":true}
$ curl -si -X OPTIONS -H "Origin: https://app.example.com" -H "Access-Control-Request-Method: GET" http://localhost:3001/api/foo
HTTP/1.1 204 No Content
vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch
access-control-allow-headers: Content-Type, Authorization
access-control-allow-methods: GET, POST, OPTIONS
access-control-allow-origin: https://app.example.com
Date: Tue, 06 Oct 2026 00:50:59 GMT
Connection: keep-alive
Keep-Alive: timeout=5

— 2026-10-06 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-06 検証(ほか 2 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5
  • Next.js 16.3.8

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 個別 Route Handler でヘッダーを返す

公式の Route Handlers ドキュメント(新しいタブで開く) と route.js ファイル規約(新しいタブで開く) に沿って、app/api/foo/route.ts を実装する。

const ALLOW_ORIGIN = "https://app.example.com";
 
export async function GET() {
  return new Response(JSON.stringify({ ok: true }), {
    headers: {
      "Content-Type": "application/json",
      "Access-Control-Allow-Origin": ALLOW_ORIGIN,
    },
  });
}
 
export async function OPTIONS() {
  return new Response(null, {
    status: 204,
    headers: {
      "Access-Control-Allow-Origin": ALLOW_ORIGIN,
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization",
    },
  });
}

2. 全 API へ middleware で一括付与する

オリジンを動的に判定したい場合は middleware.ts で NextResponse のヘッダーを書き換える。
Route Handler 側との二重設定を避け、責任箇所を 1 つに絞る。

3. クッキー連携時の注意

fetch(url, { credentials: "include" }) を使うクライアントには、Access-Control-Allow-Origin: * ではなく具体的オリジン、加えて Access-Control-Allow-Credentials: true を返す。
* と credentials の併用はブラウザ側で拒否される。

よくある原因

  1. ヘッダーを設定していない。
    このときブラウザコンソールに「No 'Access-Control-Allow-Origin' header is present」エラーが出る。
  2. OPTIONS ハンドラが無い。
    OPTIONS を書かないと Next.js が自動で実装し、プリフライトは 204 No Content(allow: GET, HEAD, OPTIONS のように定義済みメソッドを並べたヘッダー付き)で返る(route.js の公式リファレンス(新しいタブで開く)・Next.js 16.3.8 で確認)。
    ただし Access-Control-Allow-Origin などの CORS ヘッダーは付かないので、ブラウザはプリフライトを失敗として扱う。
  3. * と credentials を併用している。
    この組み合わせは、ブラウザの仕様で禁止されている。
  4. 設定が重複している。
    middleware と Route Handler の両方でヘッダーを出して、値が上書きされる。