Next.js API Routes 405 错误的根源与完整解决方案

本文详解 next.js 中调用 api route 时返回 405 method not allowed 的根本原因（特别是预检 options 请求未被正确处理），并提供包含中间件、路由处理、cors 配置及 axios 封装的端到端修复方案。

本文详解 next.js 中调用 api route 时返回 405 method not allowed 的根本原因（特别是预检 options 请求未被正确处理），并提供包含中间件、路由处理、cors 配置及 axios 封装的端到端修复方案。

在 Next.js 应用中，前端通过 axios.post('/api/auth/change-password', ...) 调用自定义 API Route 时频繁收到 405 Method Not Allowed 响应，即使后端逻辑正确、网络可达，也常令人困惑。该问题并非源于业务代码错误，而是由浏览器发起的 CORS 预检（OPTIONS）请求未被 API Route 显式处理所致——当请求携带自定义请求头（如 Authorization）、使用非简单方法（如 POST + JSON）或非简单内容类型时，浏览器会先发送一个 OPTIONS 请求探查服务端是否允许该跨域操作；若 API Route 未响应 OPTIONS，Next.js 默认返回 405。

✅ 正确处理 OPTIONS 请求（关键修复）

Next.js 的 Pages Router API Route（即 /pages/api/xxx.ts）默认不自动处理 OPTIONS 方法。必须在 handler 中显式支持：

// pages/api/auth/change-password.ts
import axios from 'utils/axios';

export default async function handler(req, res) {
  const { method, body, headers } = req;

  // ✅ 关键：显式处理 OPTIONS 预检请求
  if (method === 'OPTIONS') {
    res.setHeader('Access-Control-Allow-Methods', 'POST');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    res.setHeader('Access-Control-Allow-Credentials', 'true');
    res.status(200).end(); // 返回 200 OK，而非 405
    return;
  }

  // 原有业务逻辑（仅处理 POST）
  if (method === 'POST') {
    const { currentPassword, password } = body;
    const authorization = headers.authorization;

    try {
      const { data } = await axios.post(
        `${process.env.REACT_BACKEND_URL}users/change-password`,
        { password, currentPassword },
        { headers: { Authorization: authorization } }
      );
      res.status(200).json(data);
    } catch (error) {
      const statusCode = error.response?.status || 500;
      const message = error.response?.data?.message || error.message;
      res.status(statusCode).json({ message });
    }
  } else {
    res.setHeader('Allow', ['POST', 'OPTIONS']); // 同步更新 Allow header
    res.status(405).end(`Method ${method} Not Allowed`);
  }
}

⚠️ 注意：res.setHeader() 必须在 res.status().end() 或 res.json() 之前调用，否则无效；且 OPTIONS 响应必须返回 200 状态码，不可用 204 或重定向。

? 中间件配置优化（Next.js 13+ App Router 适用）

你当前的中间件使用了旧版 NextResponse.next() 方式，但存在两个隐患：

Dora

创建令人惊叹的3D动画网站，无需编写一行代码。

下载

• Access-Control-Allow-Origin: * 与 Access-Control-Allow-Credentials: true 互斥（带凭据时 Origin 必须为明确域名）；
• Access-Control-Allow-Headers: * 在多数浏览器中不被支持（需显式列出）。

推荐修正如下（适用于 middleware.ts）：

import { NextResponse } from 'next/server';

export function middleware(request: Request) {
  const response = NextResponse.next();

  // ✅ 安全的 CORS 头（生产环境请替换为具体域名）
  const origin = request.headers.get('origin') || '';
  const allowedOrigins = ['https://your-frontend.com', 'http://localhost:3000'];
  const isAllowedOrigin = allowedOrigins.includes(origin);

  if (isAllowedOrigin) {
    response.headers.set('Access-Control-Allow-Origin', origin);
    response.headers.set('Vary', 'Origin'); // 告知 CDN 缓存需按 Origin 区分
  }
  response.headers.set('Access-Control-Allow-Credentials', 'true');
  response.headers.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
  response.headers.set('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With');

  return response;
}

export const config = {
  matcher: '/api/:path*',
};

? Axios 工具封装建议（避免 baseURL 冲突）

你当前的 utils/axios.ts 使用 baseURL: process.env.REACT_APP_API_URL，但在 API Route 中调用时，此 baseURL 指向外部后端，而前端请求 /api/auth/change-password 是发给 Next.js 自身的 Serverless 函数。因此该封装在此处是合理的（用于代理后端请求），但需确保环境变量命名清晰且无歧义：

// utils/axios.ts —— 专用于调用真实后端（非 Next.js API）
import axios from 'axios';

const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_BACKEND_URL || 'http://localhost:8000',
  headers: { 'Content-Type': 'application/json' },
});

// 可选：统一错误拦截
apiClient.interceptors.response.use(
  (res) => res,
  (error) => {
    console.error('Backend API Error:', error.response?.status, error.message);
    throw error;
  }
);

export default apiClient;

同时，在 next.config.js 中明确暴露环境变量（Pages Router）：

module.exports = {
  env: {
    NEXT_PUBLIC_BACKEND_URL: process.env.NEXT_PUBLIC_BACKEND_URL,
  },
};

✅ 最终验证步骤

1. 本地测试：使用 curl -X OPTIONS http://localhost:3000/api/auth/change-password -v，确认返回 200 OK 且含 Access-Control-Allow-Methods: POST, OPTIONS；
2. 浏览器调试：在 DevTools Network 标签页中查看请求，确认首个请求为 OPTIONS 且状态为 200，随后才是 POST；
3. 禁用缓存重试：临时在 Axios 请求中添加时间戳避免缓存干扰：

   axios.post('/api/auth/change-password?_t=' + Date.now(), { ... })

? 总结

遵循以上结构化修复，即可彻底解决 Next.js API Route 的 405 顽疾，让跨域认证请求稳定可靠。