Next.js 15部署Docker后PUT请求返回405 Method Not Allowed问题

问题概述 #

按照Next.js官方文档实现了基于App Router的Route Handler，文件路径为src/app/api/import-batch/[id]/route.ts，负责处理GET和PUT请求。本地开发环境下所有请求正常，但部署到VPS的Docker容器后，PUT /api/import-batch/[id]返回405 Method Not Allowed，GET请求在两种环境下均正常工作。相关代码已附上，尝试过类似社区问题的解决方案但无效。

排查与解决方案 #

1. 修正Route Handler的参数类型定义 #

你的代码中对RequestParams的类型定义存在错误：

type RequestParams = { params: Promise<{ id: string }> };

Next.js App Router的Route Handler中，params是直接包含动态路由参数的普通对象，而非Promise。虽然本地开发时TypeScript宽松配置可能不会报错，但生产构建后，这种错误定义可能导致Next.js无法正确识别PUT方法的存在，或执行时出现异常，最终返回405。

修正方式：
将类型定义改为：

type RequestParams = { params: { id: string } };

同时去掉await，直接获取参数：

// GET方法中
const { id } = params;
// PUT方法中
const { id } = params;

2. 检查Docker构建与启动流程 #

确保Docker容器中Next.js是生产模式运行：

• 确认Dockerfile中执行了next build命令，生成完整的生产构建产物
• 启动命令使用next start而非开发模式的next dev

示例Dockerfile：

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

3. 排查反向代理配置（如使用Nginx） #

如果VPS上使用了Nginx等反向代理，需确保配置允许PUT方法，且正确传递请求信息：

• 检查Nginx配置中是否拦截了PUT方法
• 确保代理配置中包含正确的请求头传递，避免方法被篡改

示例Nginx配置片段：

location / {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
}

4. 验证路由匹配与请求URL #

• 确认请求的URL格式正确，避免末尾斜杠差异导致的路由不匹配（Next.js默认会处理重定向，但反向代理可能干扰）
• 检查生产环境下的路由是否正确注册，可通过查看.next/server/app/api/import-batch/[id]/route.js文件，确认PUT方法的代码是否存在

5. 升级Next.js版本 #

如果使用的Next.js版本存在已知的Route Handler部署问题，尝试升级到最新稳定版，修复潜在的框架层面bug。

内容的提问来源于stack exchange，提问作者Julian