Next.js API路由结构合规却返回404，请求排查原因及解决方法

核心问题：请求路径与路由文件不匹配 #

你客户端代码发起的请求是/api/generate-outline，但实际API路由文件是app/api/generate-course/route.ts，两者路径完全不一致，这是导致404的直接原因。

其他可能的排查方向 #

如果修正路径后仍出现404，可检查以下几点：

1. Next.js 15的API路由规范 #

Next.js 15对App Router的API路由有细节调整，需确保：

• 已正确导入NextRequest：import { NextRequest } from 'next/server';
• 请求处理函数名严格为POST/GET（大小写敏感，不能写成小写）
• 函数内返回合法的响应对象，比如return new Response('success', { status: 200 })

2. 中间件的实际生效情况 #

虽然配置了/api/(.*)为公共路由，仍需验证：

• 中间件文件（middleware.ts）位于项目根目录，而非app文件夹内
• 匹配器规则无冲突，比如是否有更具体的规则优先拦截了/api/generate-course
• 临时注释中间件代码，测试是否是中间件导致的路由拦截

3. 开发服务器缓存问题 #

Next.js开发模式下可能存在缓存残留，尝试：

• 完全重启开发服务器（终止进程后重新执行npm run dev）
• 使用浏览器无痕模式发起请求，排除客户端缓存影响

4. EventSource请求的兼容性 #

你用EventSource发起的是GET请求，需注意：

• 路由中的GET函数必须返回支持流式响应的格式，或至少是合法的HTTP响应
• EventSource不支持自定义请求头，若API依赖特定头信息，需改用fetch等方式实现

验证步骤 #

1. 先修正客户端请求路径为/api/generate-course
2. 重启开发服务器
3. 用Postman或curl直接测试POST http://localhost:3000/api/generate-course，排除客户端代码干扰

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