AI Assisted
この記事は筆者の実装経験をもとに実装コードをベースで執筆し、AIによる校閲・推敲を経て公開しています。

Next.js 16 proxy.ts 移行ガイド

Next.js 16 で middleware.ts が非推奨になり、proxy.ts への移行が必要になりました。この記事では、proxy.ts とは何か、なぜこの変更が行われたのか背景を解説し、実際の移行手順を紹介します。

---

proxy.ts とは

役割

proxy.ts は、リクエストがページやAPIに到達する前に実行される処理を書くファイルです。プロジェクトルートまたは src/ ディレクトリに配置します。

リクエスト → [proxy.ts] → ページ/API

できること

基本構文

// proxy.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function proxy(request: NextRequest) {
  // リクエスト情報の取得
  const pathname = request.nextUrl.pathname

  // リダイレクト
  if (pathname === '/old') {
    return NextResponse.redirect(new URL('/new', request.url))
  }

  // リライト（URLはそのまま、別ページを表示）
  if (pathname === '/blog') {
    return NextResponse.rewrite(new URL('/news', request.url))
  }

  // 何もしない（次の処理へ）
  return NextResponse.next()
}

config で対象パスを指定

すべてのリクエストで実行すると重いので、config.matcher で対象を絞ります。

export const config = {
  matcher: [
    // /admin 以下すべて
    '/admin/:path*',
    // /api/admin 以下すべて
    '/api/admin/:path*',
  ],
}

matcher の書き方:

実行順序

proxy.ts は以下の順序で実行されます：

1. next.config.js の headers
2. next.config.js の redirects
3. proxy.ts ← ここ
4. ファイルシステムルート（public/, _next/static/）
5. 動的ルート

使いどころ

• 認証チェック（ログインしていなければリダイレクト）
• 旧URLから新URLへのリダイレクト
• セキュリティヘッダーの追加
• A/Bテスト（条件によって別ページを表示）
• ロギング

---

なぜ middleware から proxy に変わったのか

1. 名前が誤解を招いていた

「middleware」という名前は Express.js のミドルウェアを連想させます。Express のミドルウェアは、リクエスト処理の途中で任意のロジックを挟み込む汎用的な仕組みです。

しかし、Next.js の middleware は違います。できることは限られています：

• リダイレクト
• リライト
• ヘッダーの追加・変更
• レスポンスを返す

これは「ミドルウェア」というより「プロキシ」の役割です。アプリケーションの前段でリクエストを受け取り、ルーティングを制御する。この実態に合わせて proxy という名前に変更されました。

2. セキュリティ上の問題

2025年3月、Next.js のミドルウェアに深刻な脆弱性（CVE-2025-29927）が発見されました。

攻撃者が x-middleware-subrequest ヘッダーを付与するだけで、ミドルウェアの認証チェックを完全にバイパスできるという問題です。Next.js 11.1.4 から 15.2.2 までの全バージョンが影響を受けました。

この脆弱性の発見を機に、Next.js チームはミドルウェアの設計を見直しました。名前の変更はその一環です。

3. Edge Runtime の制限

従来の middleware は Edge Runtime で動作していました。Edge Runtime は高速ですが、使える Node.js API が限られています：

• ファイルシステム（fs）が使えない
• 一部の npm パッケージが動作しない
• データベース接続に制限がある

新しい proxy.ts は Node.js ランタイムで動作します。Edge の制限がなくなり、より柔軟な処理が可能になりました。

---

何が変わったのか

ロジックの変更は不要です。ファイル名と関数名を変えるだけで移行できます。

---

移行手順

Step 1: ファイル名を変更

mv middleware.ts proxy.ts
# または
mv src/middleware.ts src/proxy.ts

Step 2: 関数名を変更

// ❌ 従来
export function middleware(request: NextRequest) {
  // ...
}

// ✅ 新
export function proxy(request: NextRequest) {
  // ...
}

これだけです。config や処理ロジックはそのまま使えます。

自動マイグレーション

codemod を使えば自動で変換できます。

npx @next/codemod@canary upgrade latest

---

移行しないとどうなるか

Next.js 16 では middleware.ts は非推奨ですが、まだ動作します。起動時に警告が表示されます：

⚠ The "middleware" file convention is deprecated. Please use "proxy" instead.

Next.js 17 以降で middleware.ts は完全に削除される予定です。早めに移行しておくことをおすすめします。

---

注意点

Edge Runtime を使いたい場合

proxy.ts は Node.js ランタイム固定です。Edge Runtime を使い続けたい場合は、当面 middleware.ts を使用してください。Vercel は今後のリリースで Edge Runtime のサポートについて詳細を発表予定です。

next.config.js の設定フラグ

middleware 関連の設定フラグも名前が変わりました。

// ❌ 従来
skipMiddlewareUrlNormalize: true

// ✅ 新
skipProxyUrlNormalize: true

---

まとめ

• middleware.ts → proxy.ts への移行は、ファイル名と関数名を変えるだけ
• 名前の変更は、実態（プロキシ）に合わせたもの
• セキュリティ強化と Edge Runtime 制限からの解放も背景にある
• Next.js 17 で完全削除予定なので、早めの移行を推奨

---

参考

• Next.js 16 Release Blog
• Upgrading to Version 16
• proxy.ts API Reference