[Cloudflare Pages] Next.jsを動かすにはEdge Runtimeの指定が必須

2025-12-07 sun

Cloudflare PagesでNext.jsをデプロイした際に発生したエラー

Cloudflare PagesにNext.jsプロジェクトをデプロイしたところ、ローカルでは問題なく動作していたにもかかわらず、ビルド時に次のようなエラーが発生した。

⚡️ ERROR: Failed to produce a Cloudflare Pages build from the project. ⚡️
⚡️ The following routes were not configured to run with the Edge Runtime: ⚡️
 
⚡️ - /api/form
⚡️ - /posts/[id]
⚡️
⚡️ Please make sure that all your non-static routes export the following edge runtime route segment config: ⚡️
⚡️ export const runtime = 'edge';
⚡️
⚡️ You can read more about the Edge Runtime on the Next.js documentation: ⚡️
⚡️ https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes

要約すると、非静的ルートが Edge Runtime で動作する設定になっていないため、Cloudflare Pages のビルドが失敗したという内容である。

なぜこのエラーが起きたのか？

Next.jsは、特に何も指定しない限り Node.js Runtime を使用する。一方で、Cloudflare Pages / Workersは 非静的ルートをEdge Runtimeで動かすことを前提としている。

つまり、

  • Next.js → Node.js Runtime（デフォルト）
  • Cloudflare Pages → Edge Runtime前提

という不一致が原因で、API RouteやSSRページがCloudflare上で正しく処理されず、ビルドが失敗していた。

特にエラー対象となっていたルート

今回のエラーでは、以下の2つのルートが問題として指摘されていた。

  • /api/form（API Route）
  • /posts/[id]（動的ページ）

どちらも サーバー側の処理が必要なルート であり、Node.js RuntimeのままではCloudflare Pagesで動作しない。

解決方法：export const runtime = 'edge' を付ける

Cloudflare PagesでNext.jsの非静的ルートを正しく動作させるには、該当ルートでRuntimeをEdgeに切り替える必要がある。

export const runtime = 'edge';

この宣言を追加することで、Next.jsが対象ルートをEdge Runtimeで扱うようになり、Cloudflare Pagesのビルドも正常に完了する。

実際の修正例（API Route）

// app/api/form/route.ts
import { NextRequest, NextResponse } from "next/server";
 
export const runtime = "edge";
 
export async function POST(req: NextRequest) {
  const data = await req.json();
 
  if (!data.name || !data.message) {
    return NextResponse.json({ error: "Missing fields" }, { status: 400 });
  }
 
  return NextResponse.json({ ok: true });
}

このようにRuntimeをEdgeに切り替えたところ、Cloudflare Pagesのビルドは正常に完了し、デプロイ後も問題なく動作した。

Edge Runtimeとは何か

Edge Runtimeは Node.js ではなく、より軽量で高速に動作する実行環境 であり、Cloudflare Workersと同じ仕組みのうえで動作する。

世界中のエッジ拠点で実行されるため、低レイテンシでレスポンスできるという利点がある。

ただし制約もあり、

  • fs や path などの Node.js API は使用不可
  • Web標準API（fetch / Request / Response など）中心で実装する必要がある

という点に注意が必要。

どのルートに runtime = 'edge' が必要か

Cloudflare Pagesでは、以下のケースでEdge Runtimeを必ず指定する必要がある。

1. API Route (app/api/**/route.ts)

サーバー側で処理する以下のようなルートは、すべてEdge Runtimeを要求する。

  • フォーム送信（POST）
  • データの取得（GET）
  • 外部API呼び出し
    など

これらは 必ず Edge Runtime を指定する必要がある。

2. 動的レンダリング（SSR）を行うページ

次のような「リクエストごとに処理が走る」ページもEdge Runtimeを必要とする。

  • SSRを行うページ
  • cookies()、headers() などを利用するページ
  • getAllPostMeta() のようなサーバー処理を含む動的ルート

一方、完全に静的化できるページであれば Runtime 設定は不要 である。

まとめ

  • Cloudflare Pagesは 非静的ルートを Edge Runtime で実行する前提

  • Next.jsはデフォルトでNode.js Runtimeのため、そのままではエラーになる

  • エラーメッセージには問題となるルートが明示される

  • export const runtime = 'edge' を付加することで解決可能

関連記事