Next.js动态API路由部署VPS后报NotFound问题排查求助

1. 开启Next.js详细日志 #

启动项目时添加环境变量，强制输出路由匹配的完整过程：

NEXT_DEBUG=1 npm run dev

通过日志可以看到Next.js如何解析请求路径、扫描路由文件的细节，确认服务器是否识别到app/api/todo/route.ts文件。

2. 核对服务器文件结构 #

登录VPS直接检查项目目录，确认app/api/todo/route.ts路径完全正确——注意Linux系统区分大小写，本地Windows环境下不敏感的路径差异（比如Todo和todo）会导致服务器无法识别。

3. 简化API路由代码排查 #

临时替换route.ts为最简响应代码，排除业务逻辑干扰：

// app/api/todo/route.ts
export async function GET() {
  return new Response(JSON.stringify({ msg: 'API test' }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

重启dev服务后再次访问，若仍返回NotFound，说明问题不在业务代码本身。

4. 在VPS本地发起请求验证 #

用curl在服务器内部直接请求API，排除外部代理的影响：

curl -v http://localhost:3000/api/todo

查看请求方法、路径是否正确，以及服务器的响应细节。如果本地curl也返回NotFound，说明是服务器端路由匹配问题；如果curl能正常响应，大概率是Nginx等反向代理的路径重写配置错误。

5. 生成并检查路由清单 #

在项目根目录执行命令，列出Next.js识别到的所有路由：

npx next list routes

检查输出结果中是否包含/api/todo，如果没有，说明文件命名或目录结构不符合App Router规则（比如文件名不是route.ts/js/tsx/jsx）。

6. 核对Next.js配置与环境变量 #

检查next.config.js中的basePath、rewrites等配置项，这些规则可能干扰路由匹配。同时确认服务器环境变量与本地一致，比如NODE_ENV是否为development，避免生产模式缓存影响。

7. 检查文件权限 #

Linux系统下，确保Next.js进程拥有读取app/api/todo/route.ts的权限：

ls -l app/api/todo/route.ts

若权限不足，执行以下命令调整：

chmod 644 app/api/todo/route.ts

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