Next.js を Cloudflare で動かすときのつまずき 10 選 — 2026 年の現行パス

# Next.js 側の環境変数。
# - NEXT_PUBLIC_* … クライアントバンドルに埋め込まれる
# - それ以外 … `next build` 時にサーバーバンドルへ埋め込まれる
#
# サーバー「実行時」に読みたい秘密情報 (API キー等) はここではなく
# `wrangler secret put KEY` で Workers Secrets に登録すること。

# 例: 公開しても安全なサイト URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# 例: 公開しても安全な API エンドポイント
NEXT_PUBLIC_API_BASE=/api

# nextjs-cloudflare-starter

Next.js 16 を **Cloudflare Workers** で動かす最小テンプレート。
[記事本文](https://r43lab.com/blog/nextjs-cloudflare-deploy-pitfalls) と対になる実動構成です。

## Quick start

```bash
bun install

# 開発 (Next.js の Node サーバー)
bun run dev

# 本番同等で動かす (Workers ランタイム = workerd)
bun run preview       # next build → opennextjs-cloudflare build → wrangler dev

# デプロイ
bun run deploy        # next build → opennextjs-cloudflare build → wrangler deploy
```

## なぜ Workers 推奨?

2024 年後半から Cloudflare は Next.js の公式推奨パスを **`@opennextjs/cloudflare` + Cloudflare Workers** に切り替えました。旧来の `@cloudflare/next-on-pages` + Pages は引き続き動きますが、Node 互換や新機能の優先投入先は Workers 側です。

新規採用は Workers、既存 Pages 構成は中長期で移行、という整理が 2026-04 時点の定石。

## 要件

- Next.js 16 系 (App Router)
- `@opennextjs/cloudflare` v1.19 系
- `wrangler.jsonc` で **`nodejs_compat` フラグ** を有効化
- `compatibility_date` を **2024-09-23 以降**(このテンプレは `2026-04-01`)

## ハマりポイント

記事本文で 10 件解説していますが、特にデプロイ直後に気づきがちなのは:

- `next/image` は Cloudflare Images または loaderFile 指定が必須
- `pg` / Prisma の既定アダプタは動かない — D1 / Hyperdrive / Neon HTTP driver へ
- Middleware のバンドルを軽く保つ(重いライブラリを import しない)

## 依存バージョン

`package.json` は **2026-04 時点のスナップショット** です。Next.js と adapter は動きが速いので、clone 後に最新化を推奨。

```bash
bun outdated
bun update
```

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Next.js 本体の設定。Cloudflare 固有の設定は open-next.config.ts 側に寄せる。

  images: {
    // Cloudflare Workers には Vercel の Image Optimization がないため、
    // どう配信するかを明示する必要がある。選択肢:
    //   (a) Cloudflare Images を使う (loaderFile で carrier を差し込む)
    //   (b) <img> で直接配信して next/image の最適化を使わない
    //   (c) 外部 CDN (imgix / Cloudinary 等) を loaderFile で繋ぐ
    //
    // 小規模プロジェクトなら unoptimized: true で十分なケースも多い。
    unoptimized: true,
  },

  // Cloudflare のビルドは open-next adapter が面倒を見るので standalone 指定は不要。
};

export default nextConfig;

import { defineCloudflareConfig } from "@opennextjs/cloudflare";

// OpenNext の Cloudflare adapter 設定。
// デフォルトの `defineCloudflareConfig()` だけで通常は十分動く。
// Incremental cache / queue / tag cache の backend を差し替えたい場合のみ指定する。
export default defineCloudflareConfig({
  // incrementalCache: ... // (KV / D1 backend を差し替える場合)
  // tagCache: ...
  // queue: ...
});

{
  "name": "nextjs-cloudflare-starter",
  "private": true,
  "version": "0.0.1",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "preview": "opennextjs-cloudflare build && wrangler dev",
    "deploy": "opennextjs-cloudflare build && wrangler deploy",
    "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
  },
  "dependencies": {
    "next": "^16.2.4",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@opennextjs/cloudflare": "^1.19.3",
    "@types/node": "^22",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "typescript": "^6.0.3",
    "wrangler": "^4.84.0"
  }
}

// Route Handler のサンプル。
// OpenNext 経由で Cloudflare Workers 上では Node 互換ランタイム
// (workerd + nodejs_compat) で実行される。
//
// export const runtime = "edge";  // ← 指定しても良いが、OpenNext + Workers では
//                                     default (Node-like) のままで問題ないケースが多い

export async function GET(request: Request) {
  const url = new URL(request.url);
  const name = url.searchParams.get("name") ?? "world";

  return Response.json({
    greet: `hello, ${name}`,
    runtime: "cloudflare-workers (workerd)",
    at: new Date().toISOString(),
  });
}

// App Router の最小ページ (Server Component)

export default function Home() {
  return (
    <main
      style={{
        fontFamily: "ui-monospace, monospace",
        padding: "2rem",
        lineHeight: 1.8,
      }}
    >
      <h1>nextjs-cloudflare-starter</h1>
      <p>Next.js 16 が Cloudflare Workers (workerd) で動いています。</p>

      <h2>動作確認</h2>
      <ul>
        <li>
          <code>GET /api/hello</code> — Route Handler (Edge/Node どちらでも可)
        </li>
      </ul>

      <h2>次にやること</h2>
      <ol>
        <li>
          <code>wrangler dev</code> で workerd ランタイム上のローカル確認
        </li>
        <li>
          <code>wrangler secret put DATABASE_URL</code> でサーバー秘密情報を登録
        </li>
        <li>データアクセス層を D1 / Hyperdrive / Neon HTTP へ差し替え</li>
      </ol>
    </main>
  );
}

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "nextjs-cloudflare-starter",
  "main": ".open-next/worker.js",

  // nodejs_compat を有効にするため、compatibility_date は 2024-09-23 以降が必要。
  "compatibility_date": "2026-04-01",
  "compatibility_flags": ["nodejs_compat"],

  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  },

  "observability": {
    "enabled": true
  }

  // サーバーサイドで参照する秘密情報は wrangler secret put で。
  //   wrangler secret put DATABASE_URL
  //   wrangler secret put SOME_API_KEY
  //
  // NEXT_PUBLIC_* のビルド時埋め込み値は .env.local / .env.production に。
}