Next.js项目访问api/create-chat出现404错误，请求调试帮助

我是Next.js新手，正在开发对接OpenAI与PDF的项目，创建了create-chat API模块，但访问localhost:3000/api/create-chat时始终返回404错误，URL路径正确且文件确实存在。以下是我的create-chat/route.ts代码：

import { db } from "@/lib/db";
import { chats } from "@/lib/db/schema";
import { loadS3IntoPinecone } from "@/lib/pinecone";
import { getS3Url } from "@/lib/s3";
import { auth } from "@clerk/nextjs";
import { NextResponse } from "next/server";

// /api/create-chat
export async function POST(req: Request) {
  const { userId } = await auth();
  if (!userId) {
    return NextResponse.json({ error: "unauthorized" }, { status: 401 });
  }
  try {
    const body = await req.json();
    const { file_key, file_name } = body;
    console.log(file_key, file_name);
    await loadS3IntoPinecone(file_key);
    const chat_id = await db
      .insert(chats)
      .values({
        fileKey: file_key,
        pdfName: file_name,
        pdfUrl: getS3Url(file_key),
        userId,
      })
      .returning({
        insertedId: chats.id,
      });

    return NextResponse.json(
      {
        chat_id: chat_id[0].insertedId,
      },
      { status: 200 }
    );
  } catch (error) {
    console.error(error);
    return NextResponse.json(
      { error: "internal server error" },
      { status: 500 }
    );
  }
}

我已尝试创建自定义server.js、验证路径正确性、按Clerk官网配置Middleware，但仍未找到问题根源，不知如何调试该错误。

排查与解决步骤 #

1. 确认路由系统与文件结构匹配

Next.js 13+ 有App Router和Pages Router两种路由体系，API路由的结构完全不同：

• 若使用App Router，API文件必须放在app/api/create-chat/route.ts，目录层级严格对应/api/create-chat路径；
• 若使用Pages Router，API文件应命名为pages/api/create-chat.ts，不能用route.ts子目录的形式。
  检查你的项目使用的路由体系，确保文件路径完全符合对应规则。

2. 重启开发服务器并清除缓存

开发服务器可能未加载新添加的路由，执行以下操作：

• 终止当前npm run dev进程，重新启动；
• 用浏览器无痕模式访问API，或清除浏览器缓存，避免旧缓存导致的404。

3. 排查Clerk中间件的拦截问题

临时注释掉项目中的middleware.ts/js文件，重新启动服务器后测试API是否能正常访问：

• 如果注释后能访问，说明中间件的路径匹配规则有误，比如误将/api/create-chat排除在允许范围外，或重定向规则导致请求被拦截；
• 检查中间件中的auth配置，确保没有对API路由设置错误的权限拦截（正常情况下未授权请求应返回401而非404）。

4. 验证文件命名与大小写

• 确保文件名是小写的route.ts，目录名是create-chat；
• Linux/macOS系统对文件名大小写敏感，确保请求URL的/api/create-chat与目录名完全一致。

5. 添加测试接口调试

在route.ts中添加一个简单的GET函数，测试路由是否被识别：

export async function GET() {
  return NextResponse.json({ message: "API route is working" }, { status: 200 });
}

启动服务器后用GET请求访问localhost:3000/api/create-chat，如果能返回正常响应，说明路由本身没问题，问题可能出在POST请求的处理或依赖服务上；如果仍返回404，说明路由未被Next.js识别，需回到步骤1检查文件结构。

6. 移除自定义server.js测试

若你使用了自定义server.js，可能覆盖了Next.js默认的API路由处理逻辑：

• 临时移除自定义服务器配置，改用Next.js默认的开发服务器启动；
• 测试API是否能正常访问，排除自定义服务器的干扰。

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