Next.js Pages Router动态API路由Vercel部署后无法访问

问题背景 #

使用Next.js Pages Router开发应用，创建动态API路由/pages/api/v1/wallet/expenses/[id]/index.ts，本地开发及构建运行时GET、DELETE方法均正常，但部署到Vercel后，访问该路由持续返回405 Method Not Allowed，响应头显示X-Matched-Path: /404，请求命中自定义404页面，Vercel无法识别该API路由。

已做排查：

• 页面路由/pages/test/[id]/index.tsx在Vercel上访问正常，可正确获取id参数；
• 测试API路由/pages/api/check/[id].ts本地正常，但Vercel上返回404；
• 未配置中间件或自定义构建流程，移除next-pwa配置、降级Next.js至15.0.4后问题仍存在；
• 非动态API路由（如/pages/api/v1/health.ts）在Vercel上运行正常；
• 部署日志和Functions列表显示动态API路由已部署，但实际访问失败。

环境：Next.js 15.2.3（曾降级至15.0.4）、TypeScript ^5、Node.js 22（本地Mac），无vercel.json，使用基础Next.js配置。

可能的解决方法 #

1. 强制清除Vercel部署缓存 #

Vercel可能缓存了旧的函数部署结果，即使日志显示路由存在，实际运行的仍是旧版本：

• 进入Vercel控制台的部署详情页，点击「Redeploy」，取消勾选「Use existing Build Cache?」，强制重新构建部署；
• 本地清理.next文件夹和node_modules，执行npm install重新安装依赖后，再推送代码重新部署。

2. 调整动态API路由的文件结构 #

Vercel的路由解析对文件结构的严格性可能高于本地：

• 将嵌套的[id]/index.ts重命名为[id].ts，即路径改为pages/api/v1/wallet/expenses/[id].ts，符合Pages Router的标准动态路由命名规范；
• 检查文件名大小写，Vercel文件系统区分大小写，本地Mac默认不区分，确保[id]拼写完全一致。

3. 统一Node.js版本与Next.js稳定版 #

本地Node.js版本（22）与Vercel默认支持的版本可能存在差异，Next.js 15.x可能存在兼容性问题：

• 在package.json中添加engines字段，指定Vercel支持的Node.js LTS版本：

  {
    "engines": {
      "node": "20.x"
    }
  }
  

• 降级Next.js到14.2.x（LTS稳定版），执行npm install next@14.2.x后重新部署。

4. 显式指定Vercel函数运行时 #

创建vercel.json文件，指定API路由的Node.js运行时版本，确保Vercel正确解析路由：

{
  "functions": {
    "pages/api/**/*.ts": {
      "runtime": "@vercel/node@3"
    }
  }
}

5. 检查API路由的方法处理逻辑 #

确保API路由正确导出处理函数，并对未支持的方法返回正确的405响应，避免隐性错误：

import type { NextApiRequest, NextApiResponse } from 'next';

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const { id } = req.query;

  switch (req.method) {
    case 'GET':
      res.status(200).json({ success: true, id });
      break;
    case 'DELETE':
      res.status(200).json({ success: true, message: `Expense ${id} deleted` });
      break;
    default:
      res.setHeader('Allow', ['GET', 'DELETE']);
      res.status(405).end(`Method ${req.method} Not Allowed`);
  }
}

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