NextJS TypeScript Pages Router API路由404错误求助

核心排查步骤 #

1. 确认API路由文件结构合规 #

• 必须将路由文件放在pages/api目录下（Next.js 12及之前的Pages Router），或app/api目录下（Next.js 13+的App Router）
• 文件名全小写，Next.js对路径大小写敏感，比如Posts.ts会直接导致404
• 动态路由要遵循命名规则，比如pages/api/posts/[id].ts对应请求路径/api/posts/123

2. 检查路由处理函数的导出格式 #

Pages Router 示例（必须导出默认函数）

// pages/api/posts.ts
import type { NextApiRequest, NextApiResponse } from 'next'
import prisma from '../../lib/prisma'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // 严格处理HTTP方法，避免405错误
  if (req.method === 'GET') {
    const posts = await prisma.post.findMany()
    return res.status(200).json(posts)
  }

  if (req.method === 'POST') {
    const { title, content } = req.body
    const post = await prisma.post.create({ data: { title, content } })
    return res.status(201).json(post)
  }

  // 返回不支持的方法提示
  res.setHeader('Allow', ['GET', 'POST'])
  res.status(405).end(`Method ${req.method} Not Allowed`)
}

App Router 示例（导出对应方法的函数）

如果用Next.js 13+ App Router，API路由文件必须命名为route.ts，且导出对应HTTP方法的函数：

// app/api/posts/route.ts
import { NextResponse } from 'next/server'
import prisma from '@/lib/prisma'

export async function GET() {
  const posts = await prisma.post.findMany()
  return NextResponse.json(posts)
}

export async function POST(request: Request) {
  const { title, content } = await request.json()
  const post = await prisma.post.create({ data: { title, content } })
  return NextResponse.json(post, { status: 201 })
}

3. 验证请求的路径和方法 #

• Insomnia中请求URL必须是http://localhost:3000/api/[路由文件名]，比如http://localhost:3000/api/posts，绝对不能加pages/前缀
• 确保请求方法和路由中处理的一致，比如路由只支持GET/POST，发送PUT请求会返回405
• 检查URL是否有拼写错误，比如多打斜杠或字母错误

4. 排查开发环境问题 #

• 重启Next.js开发服务器（npm run dev），避免文件修改未热加载
• 查看终端输出，检查是否有编译错误、Prisma客户端生成失败等提示
• 重新生成Prisma客户端：运行npx prisma generate，确保node_modules/@prisma/client目录存在

5. 验证数据库连接 #

• 运行npx prisma studio，确认能正常连接PostgreSQL数据库，避免因数据库连接失败导致API路由异常
• 检查.env文件中的DATABASE_URL格式是否正确：postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public

快速验证方法 #

创建一个极简测试路由pages/api/test.ts：

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: 'API正常响应' })
}

请求http://localhost:3000/api/test，如果仍返回404，说明是Next.js项目配置或目录结构问题；如果成功，再逐步添加Prisma逻辑排查。

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