Next.js 14.1.3中Stripe Webhook API端点404错误排查求助

针对Next.js 14.1.3版本下的Stripe Webhook 404问题，按以下顺序排查：

1. 确认API路由的文件结构（关键） #

Next.js 14的App Router和Pages Router对API路由的要求完全不同：

• App Router：必须创建app/api/stripe-webhook/route.ts（文件夹+route.ts文件），而非直接的app/api/stripe-webhook.ts。同时代码需要适配App Router的写法，替换原有Pages Router的类型和导出方式：

import { NextRequest, NextResponse } from "next/server";
import { buffer } from "micro";
import Stripe from "stripe";
import prisma from "@/libs/prismadb";

export const config = {
  api: {
    bodyParser: false,
  },
};

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
  apiVersion: "2023-10-16",
});

export async function POST(req: NextRequest) {
  console.log("accessed handler");
  const buf = await buffer(req);
  const sig = req.headers.get("stripe-signature");

  if (!sig) {
    return NextResponse.json({ error: "Missing stripe signature" }, { status: 400 });
  }

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(
      buf,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err: any) {
    return NextResponse.json({ error: "Webhook error: " + err.message }, { status: 400 });
  }

  switch (event.type) {
    case "charge.succeeded":
      const charge = event.data.object as Stripe.Charge;
      if (typeof charge.payment_intent === "string") {
        console.log("hello");
        await prisma?.order.update({
          where: {
            paymentIntentId: charge.payment_intent,
          },
          data: {
            status: "completed",
            address: charge.shipping?.address,
          },
        });
      }
      break;
    default:
      console.log("Unhandled event type: " + event.type);
  }

  return NextResponse.json({ received: true });
}

• Pages Router：文件放在pages/api/stripe-webhook.ts是正确的，但要确保项目启用了Pages Router（Next.js 14默认是App Router，若需兼容需在next.config.js中配置experimental: { appDir: true }，或直接采用Pages Router结构）。

2. 验证路由是否存在 #

手动用GET请求访问http://localhost:3000/api/stripe-webhook：

• 如果返回405 Method Not Allowed，说明路由已注册，只是不接受GET请求，404问题解决，后续排查Stripe签名或事件处理逻辑；
• 如果仍返回404，说明路由未正确注册，回到第一步检查文件结构。

3. 检查依赖是否安装 #

确保micro包已安装，代码中用到的buffer(req)依赖该包：

npm install micro
# 或
yarn add micro

4. 确认服务器运行状态 #

确保本地服务器通过npm run dev启动，端口确实为3000，未被其他程序占用。

5. 检查Next.js配置 #

如果使用App Router，确保next.config.js中没有禁用API路由的相关配置；如果混合使用Pages和App Router，确认配置项正确。

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