nextjs-16-proxy

Next.js 16 の Proxy 規約

Next.js 16 では、ネットワーク境界としての役割をより適切に表すため、middleware が proxy に名称変更されました。

Middleware からの主な変更点

旧（Next.js 15）	新（Next.js 16 以降）
middleware.ts	proxy.ts
export function middleware()	export function proxy()
同じ場所	同じ場所

ファイルの場所

proxy.ts は app または pages と同じ階層に配置します。

src/
├── proxy.ts      ← Correct location
├── app/
│   └── ...

app/ の中には配置しません。

src/
├── app/
│   ├── proxy.ts  ← Wrong location
│   └── ...

基本テンプレート

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Example: rewrite /uploads/* to /api/uploads/*
  if (pathname.startsWith("/uploads/")) {
    const newUrl = request.nextUrl.clone();
    newUrl.pathname = pathname.replace("/uploads/", "/api/uploads/");
    return NextResponse.rewrite(newUrl);
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/uploads/:path*"],
};

よくある問題：動的ルートがパスを捕捉する

ルートに [teamSlug] のような動的ルートがある場合、next.config.ts のリライトが適用される前にパスを捕捉することがあります。

問題：

• リクエスト：/uploads/image.png
• 動的ルート [teamSlug] が teamSlug = "uploads" として捕捉する
• 404 になります

解決策： next.config.ts のリライトではなく、proxy.ts を使用します。Proxy はルーティングの前に実行されます。

移行コマンド

npx @next/codemod@canary middleware-to-proxy .

これにより、次の処理が自動的に行われます。

• middleware.ts を proxy.ts に名称変更する
• 関数名を middleware から proxy に更新する