Next.js の middleware が実行されない
middleware.ts はプロジェクトルートに 1 ファイル限定で、matcher の設定と Edge runtime 制約に従う必要がある。
配置と matcher がずれると静かにスキップされ、export 名を間違えるとリクエストがすべて 500 になる。
公開: 更新:
npx next build … └ other shared chunks (total) 1.88 kB ○ (Static) prerendered as static content ƒ (Dynamic) server-rendered on demand
2026-11-09 に node:20(Next.js 15.5.29 / Node.js 20.20.2) で実際に打って取った出力。検証環境の詳細
要約
middleware.ts が動かないときは「ファイルの場所」「matcher」「export 名」「ランタイム制約」を順に疑う。
公式の middleware.js(v15)(新しいタブで開く) のとおり、middleware は プロジェクトルートに 1 ファイルしか置けず、複数置いても認識されない。
なお Next.js 16.0.0 でこのファイル規約は非推奨になり proxy(新しいタブで開く) へ改名された。
16 以降は同じ位置に proxy.ts を置く。
実行例
Next.js 15.5.29 で、レスポンスに x-middleware: hit を付けるだけの middleware を app/ の中に置くと、next build の一覧に ƒ Middleware が出ず、ヘッダも付かなかった。
プロジェクトルートへ移すと、両方とも現れた。
matcher を /api/:path* だけにすると、トップページには付かなかった。
API と静的アセットを除く matcher に直すと、トップには付いて /api/hello には付かなくなった。
関数名を myMiddleware に変えると、ビルドは通るのにトップが 500 Internal Server Error になった。
$ npx next --version
Next.js v15.5.29$ npx next build
▲ Next.js 15.5.29
Creating an optimized production build ...
✓ Compiled successfully in 2.2s
Linting and checking validity of types ...
Collecting page data ...
Generating static pages (0/5) ...
Generating static pages (1/5)
Generating static pages (2/5)
Generating static pages (3/5)
✓ Generating static pages (5/5)
Finalizing page optimization ...
Collecting build traces ...
Route (app) Size First Load JS
┌ ○ / 131 B 103 kB
├ ○ /_not-found 990 B 104 kB
└ ƒ /api/hello 131 B 103 kB
+ First Load JS shared by all 103 kB
├ chunks/255-73938ce8a8eac1ad.js 46.6 kB
├ chunks/4bd1b696-c023c6e3521b1417.js 54.2 kB
└ other shared chunks (total) 1.88 kB
○ (Static) prerendered as static content
ƒ (Dynamic) server-rendered on demand$ curl -sI http://localhost:3000/
HTTP/1.1 200 OK
Vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch, Accept-Encoding
x-nextjs-cache: HIT
x-nextjs-prerender: 1
x-nextjs-prerender: 1
x-nextjs-stale-time: 300
X-Powered-By: Next.js
Cache-Control: s-maxage=31536000
ETag: "n4yn6lynuo31i"
Content-Type: text/html; charset=utf-8
Content-Length: 3954
Date: Sun, 08 Nov 2026 22:03:11 GMT
Connection: keep-alive
Keep-Alive: timeout=5$ mv app/middleware.js middleware.js$ npx next build
▲ Next.js 15.5.29
Creating an optimized production build ...
✓ Compiled successfully in 2.6s
Linting and checking validity of types ...
Collecting page data ...
Generating static pages (0/5) ...
Generating static pages (1/5)
Generating static pages (2/5)
Generating static pages (3/5)
✓ Generating static pages (5/5)
Finalizing page optimization ...
Collecting build traces ...
Route (app) Size First Load JS
┌ ○ / 131 B 103 kB
├ ○ /_not-found 990 B 104 kB
└ ƒ /api/hello 131 B 103 kB
+ First Load JS shared by all 103 kB
├ chunks/255-73938ce8a8eac1ad.js 46.6 kB
├ chunks/4bd1b696-c023c6e3521b1417.js 54.2 kB
└ other shared chunks (total) 1.88 kB
ƒ Middleware 34.2 kB
○ (Static) prerendered as static content
ƒ (Dynamic) server-rendered on demand$ curl -sI http://localhost:3000/
HTTP/1.1 200 OK
x-middleware: hit
Vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch, Accept-Encoding
x-nextjs-cache: HIT
x-nextjs-prerender: 1
x-nextjs-prerender: 1
x-nextjs-stale-time: 300
X-Powered-By: Next.js
Cache-Control: s-maxage=31536000
ETag: "kq08c2524y31i"
Content-Type: text/html; charset=utf-8
Content-Length: 3954
Date: Sun, 08 Nov 2026 22:03:20 GMT
Connection: keep-alive
Keep-Alive: timeout=5— 2026-11-09 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-11-09 検証(ほか 2 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
- Next.js 15.5.29
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. ルート配置を確認
my-app/
├── app/
├── src/ # src ディレクトリを使う場合
│ ├── app/
│ └── middleware.ts # ← ここ
├── middleware.ts # ← または ここ(src を使わない場合)
└── next.config.jsapp/middleware.ts に置いても動かない。
2. matcher を適切に書く
// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
export function middleware(req: NextRequest) {
return NextResponse.next();
}
export const config = {
matcher: [
"/((?!api|_next/static|_next/image|favicon.ico).*)",
],
};これは、API ルートや静的アセットを除外しつつ全ページに効かせるテンプレートである。
複数の matcher を配列で並べてもよい。
3. export 名は middleware
関数名は middleware でなければならない。
export function middleware(req: NextRequest) { /* ... */ }
// あるいは
export default function (req: NextRequest) { /* ... */ }auth や myMiddleware といった名前にしても、ビルドは成功してルート一覧にも ƒ Middleware が出る。
ところが実行時にはすべてのリクエストが 500 Internal Server Error になり、サーバーのログに次のエラーが出る(Next.js 15.5.29 の next build と next start で確認)。
Error: The Middleware "/middleware" must export a `middleware` or a `default` function静かにスキップされるのではなくサイト全体が落ちるので、500 が出たらまずこの行を探す。
4. ランタイムに合った API を使う
Edge runtime を選んだ場合は fs / child_process / Node.js 専用ストリーム等が使えない。
Node.js runtime は 15.5.0 で安定版になり、16.0.0 の proxy は既定が Node.js runtime である。
どちらを使うにせよ、重い処理や DB アクセスは Route Handler 側で行い、middleware は認証ヘッダの検査やリダイレクト判定に限定する。
export function middleware(req: NextRequest) {
const token = req.cookies.get("session")?.value;
if (!token) {
return NextResponse.redirect(new URL("/login", req.url));
}
return NextResponse.next();
}dev サーバを再起動して console.log がターミナルに出れば、middleware は動いている。
よくある原因
- 配置場所が間違っている。
app/middleware.tsやpages/middleware.tsは無効で、置く場所はプロジェクトルートか、src/を使う構成ならsrc/middleware.tsである。 - matcher が狭すぎる。
matcher: "/api/:path*"だけだと、通常ページで実行されない。 - export 名を間違えている。
myMiddlewareのような任意名で export すると、next buildは通るのに、実行時にすべてのリクエストが 500 Internal Server Error になる。 - 選んだランタイムで動かない API を使っている。
Edge runtime でfs.readFileSyncなどを呼ぶと middleware ごと落ち、結果として実行されていないように見える。