Next.js App Router API 路由 405 Method Not Allowed 错误排查与解决

快速答案

• 核心结论：Next.js App Router 中，API 路由处理程序必须显式导出与请求 HTTP 方法对应的函数（如 GET、POST），未导出的方法会直接返回 405 错误。这与 Pages Router 的自动方法处理机制不同。
• 第一检查项：确认 app/api/your-route/route.ts 文件中是否导出了客户端请求所使用的 HTTP 方法对应的函数。例如，客户端发送 POST 请求，文件中必须有 export async function POST(request)。
• 最小修复方案：在路由处理程序中添加缺失的方法导出，或使用 if (request.method !== 'POST') 手动检查并返回自定义 405 响应。
• 适用环境：Next.js 13+ 使用 App Router 的项目，部署在 Vercel 或 Node.js 服务器上。该问题在本地开发环境和生产环境均可能出现。

问题复现与根因分析

典型场景复现

假设你有一个 Next.js App Router 项目，在 app/api/items/route.ts 中定义了如下路由处理程序：

TYPESCRIPT
// app/api/items/route.ts
export async function GET(request: Request) {
  return Response.json({ items: ['item1', 'item2'] });
}

当客户端发送 POST /api/items 请求时，浏览器或 fetch API 会收到 405 Method Not Allowed 错误。这是因为该路由处理程序只导出了 GET 方法，未导出 POST 方法。

根因分析

Next.js App Router 的路由处理程序采用显式方法导出机制。每个 HTTP 方法对应一个独立的导出函数，框架会根据请求方法自动匹配对应的函数。如果未找到匹配的函数，则返回 405 错误。

与 Pages Router 的对比：

核心配置与参数说明

路由处理程序方法导出规范

在 app/api/ 目录下的 route.ts 或 route.js 文件中，你需要导出以下函数：

TYPESCRIPT
// 支持的 HTTP 方法
export async function GET(request: Request) { /* ... */ }
export async function POST(request: Request) { /* ... */ }
export async function PUT(request: Request) { /* ... */ }
export async function DELETE(request: Request) { /* ... */ }
export async function PATCH(request: Request) { /* ... */ }
export async function OPTIONS(request: Request) { /* ... */ }
export async function HEAD(request: Request) { /* ... */ }

动态路由参数

在动态路由（如 app/api/items/[id]/route.ts）中，方法签名需要包含 context 参数：

TYPESCRIPT
export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const id = params.id;
  return Response.json({ id });
}

常见报错与排查

错误 1：客户端发送 POST 请求，但路由处理程序只导出了 GET 方法

报错信息：405 Method Not Allowed

解决方案：

1. 检查 app/api/your-route/route.ts 文件，确保导出了与请求方法对应的函数。
2. 如果需要支持 POST 方法，添加：

TYPESCRIPT
export async function POST(request: Request) {
  const body = await request.json();
  // 处理 POST 请求
  return Response.json({ success: true });
}

错误 2：浏览器发送 OPTIONS 预检请求（CORS 场景）

报错信息：405 Method Not Allowed（OPTIONS 请求）

解决方案： 在路由处理程序中显式导出 OPTIONS 方法：

TYPESCRIPT
export async function OPTIONS(request: Request) {
  return new Response(null, {
    status: 204,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  });
}

或者，在中间件中统一处理 CORS 预检请求：

TYPESCRIPT
// middleware.ts
export function middleware(request: Request) {
  if (request.method === 'OPTIONS') {
    return new Response(null, {
      status: 204,
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
      },
    });
  }
}

错误 3：中间件重写导致 405

报错信息：405 Method Not Allowed（请求被中间件重写后）

解决方案：

1. 在 middleware.ts 中添加调试日志：

TYPESCRIPT
export function middleware(request: Request) {
  console.log('Original method:', request.method);
  console.log('Original path:', request.nextUrl.pathname);
  // 重写逻辑...
}

2. 确保重写后的路径对应的路由处理程序支持原始请求方法。

错误 4：pages/api 和 app/api 路由冲突

报错信息：405 Method Not Allowed

解决方案：

• Next.js 会优先使用 app/api 路由。
• 如果 pages/api 中的路由处理了所有方法，但 app/api 中的路由只处理了部分方法，则未处理的方法会返回 405。
• 建议统一使用一种路由模式（推荐 App Router），或删除冲突的路由。

生产环境实践与注意事项

CORS 预检请求处理

如果前端和后端部署在不同域名下，浏览器会发送 OPTIONS 预检请求。App Router 路由处理程序必须显式导出 OPTIONS 方法，否则会返回 405。

最佳实践：在中间件中统一处理 CORS 预检请求，避免在每个路由处理程序中重复编写。

中间件干扰排查

中间件中的重写（rewrite）或重定向（redirect）逻辑可能改变请求的 HTTP 方法或路径，导致 405。

建议：

• 在中间件中记录原始请求方法。
• 确保重写后的路由处理程序支持该方法。
• 使用 request.nextUrl.clone() 避免修改原始 URL。

动态路由参数匹配问题

在 app/api/[slug]/route.ts 中，如果客户端请求 POST /api/items，但 items 不是动态参数，会匹配到 app/api/items/route.ts。如果该文件未导出 POST 方法，则返回 405。

建议：

• 使用 export const dynamic = 'force-static' 明确路由的静态/动态行为。
• 检查路由文件结构，确保路径匹配正确。

部署到 Vercel 的注意事项

本地开发正常但部署到 Vercel 后出现 405 错误，可能的原因包括：

1. Runtime 不匹配：路由处理程序使用了 Node.js 特有的 API（如 fs、path），但部署时使用了 Edge Runtime。

   • 解决方案：在路由文件顶部添加 export const runtime = 'nodejs';。

2. Vercel 自动重写规则：vercel.json 中的 rewrites 配置与本地不一致。

   • 解决方案：检查 vercel.json 中的路由配置，确保与本地一致。

3. 环境变量未设置：在 Vercel 项目设置中添加所需的环境变量。

安全性建议

• 权限控制：API 路由默认对外公开。在路由处理程序或中间件中实现身份验证（如 JWT、Session）。
• 输入验证：对用户输入进行严格验证和清理，防止 SQL 注入或 XSS 攻击。
• 敏感信息保护：避免在 API 路由中直接暴露敏感信息（如数据库密码），使用环境变量管理配置。

常见问题 FAQ

Q: 如何在 Next.js App Router 中自定义 405 错误的响应内容？

A: Next.js 默认的 405 响应是框架内置的，无法直接修改。但你可以通过以下方式间接实现：

1. 在路由处理程序中，使用 if (request.method !== 'POST') { return new Response('Method Not Allowed', { status: 405 }); } 手动检查方法并返回自定义响应。
2. 使用中间件（middleware.ts）统一拦截所有请求，检查方法是否允许，并返回自定义 405 响应。
3. 在 app/not-found.tsx 或 app/error.tsx 中处理 405 错误（但 405 通常不会触发这些页面）。

Q: 我的 API 路由需要同时支持 GET 和 POST 方法，但客户端发送的请求总是返回 405。如何调试？

A: 调试步骤：

1. 检查路由文件：确保 app/api/your-route/route.ts 中同时导出了 GET 和 POST 函数。
2. 检查请求 URL：确认客户端请求的 URL 完全匹配路由路径（包括大小写和尾部斜杠）。
3. 检查中间件：在 middleware.ts 中添加日志，打印 request.method 和 request.nextUrl.pathname。
4. 检查浏览器开发者工具：查看网络请求的详细信息，确认请求方法和响应头。
5. 使用 curl 测试：在终端中运行 curl -X POST http://localhost:3000/api/your-route，查看响应。

Q: 为什么我的 Next.js App Router API 路由在本地开发时正常，但部署到 Vercel 后出现 405 错误？

A: 这通常是因为 Vercel 的 Edge Runtime 或 Serverless Function 配置与本地 Node.js 环境不同。可能的原因包括：

1. 路由处理程序使用了 Node.js 特有的 API（如 fs、path），但部署时使用了 Edge Runtime（不支持 Node.js API）。
   • 解决方案：在路由文件顶部添加 export const runtime = 'nodejs';。
2. Vercel 的自动重写规则（如 vercel.json 中的 rewrites）与本地配置不一致。
   • 解决方案：检查 vercel.json 中的路由配置，确保与本地一致。
3. 环境变量未正确设置。
   • 解决方案：在 Vercel 项目设置中添加所需的环境变量。

官方参考

• GitHub Issue: Next.js App Router API Route 405 Method Not Allowed