Next.js + FastAPI を nginx サブパスで配信するときに踏んだ3つの落とし穴 — trailingSlash・ルーティング分離・MuleSoftのSSEバッファリング

• URL: https://dev.classmethod.jp/articles/nextjs-fastapi-nginx-subpath-routing-pitfalls
• 日付: 2026-06-22
• Tier: Tier 2
• 要旨: Next.js + FastAPI をサブパス配信時の 3 つのルーティング落とし穴。(1) basePath だけで 404 → trailingSlash 設定必須、(2) フロントエンド・バックエンド分離 → nginx で proxy_pass パスベースルーティング、(3) API Gateway が SSE バッファリング → MuleSoft 経由でストリーミング停止。nginx proxy_pass の末尾「/」で location プレフィックス除去。X-Forwarded-* ヘッダー・Upgrade ヘッダー・proxy_buffering off で WebSocket/SSE 対応。

詳細

Next.js 16（App Router）+ FastAPI 0.115+ を Docker Compose + nginx v1.24 でサブパス配信時の 3 つのルーティング落とし穴。前提：localhost:40001（Next.js）・localhost:40002（FastAPI）を http://host/your-app/ に統合。nginx リバースプロキシ役割：複数アプリ共存・パスベースルーティング・SSL 終端・負荷分散。(1) basePath="/your-app" だけでは 404 → nginx の location /your-app/ で proxy_pass http://localhost:40001/ の末尾「/」が重要。location プレフィックス（/your-app/）が除去されて転送。trailingSlash 設定で slash 統一必須。proxy_http_version 1.1・Upgrade・Connection ヘッダー設定で WebSocket/HMR 対応。(2) フロントエンド・バックエンド分離 → nginx で振り分け。location /your-app/ → Next.js、location /your-app/api/ → FastAPI。X-Forwarded-* ヘッダー転送で リダイレクト/ログ/認証が正常動作。(3) API Gateway が SSE バッファリング → MuleSoft Anypoint Platform 経由時ストリーミング停止。proxy_buffering off・proxy_read_timeout 120s・client_max_body_size 20m で設定。X-Real-IP（直近クライアント IP）・X-Forwarded-For（プロキシチェーン IP）・X-Forwarded-Proto（http/https）でクライアント情報正確に伝播。nginx 構成 40+ アプリを 1 ドメイン・IP で運用時に location ブロック複数で パスベース振り分け必須。Next.js 単体（専用ドメイン 1 アプリ）なら nginx 不要・next start で十分。複数アプリ共存・SSL 一元管理・既存 nginx インフラ統合時に nginx 必須。