Vercel部署的Next.js中Stripe Webhook 404致无法同步数据到Clerk

路由配置排查 #

• 核对路由文件路径：Next.js App Router要求路由文件放在app/api/webhooks/route.ts，Pages Router则是pages/api/webhooks.ts，确认你的项目结构和使用的路由模式匹配，别放错目录。
• 确保只导出POST方法：Stripe Webhook只会发POST请求，你的route.ts里必须正确导出POST函数，示例：

export async function POST(request: Request) {
  // 处理Stripe webhook逻辑
}

Vercel部署配置检查 #

• 查看函数日志：去Vercel控制台的「Functions」板块，找api/webhooks的请求记录，看有没有请求进来，以及返回的错误码（404说明路由没被识别，500则看具体错误信息）。
• 移除ignoredRoutes配置：添加这个配置没用反而可能让Vercel跳过路由部署，直接删掉。
• 清除部署缓存：重新部署时勾选「Skip Build Cache」，强制重新构建，避免旧配置缓存导致的问题。

Stripe Webhook配置验证 #

• 检查端点URL：Stripe Dashboard里的Webhook URL必须是https://你的Vercel应用域名.vercel.app/api/webhooks，路径别写错。
• 用Stripe CLI本地测试：运行stripe listen --forward-to localhost:3000/api/webhooks，然后用测试卡完成支付，看本地能不能收到请求，排除线上网络问题。

Clerk同步逻辑检查 #

• 确保关联用户ID：支付时要把Clerk用户ID传入Stripe的session metadata里，Webhook处理时才能拿到对应的用户ID去更新publicMetadata，示例核心逻辑：

import { clerkClient } from '@clerk/nextjs';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2024-06-20' });

export async function POST(request: Request) {
  const sig = request.headers.get('stripe-signature')!;
  const body = await request.text();

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch (err) {
    return new Response(`Webhook Error: ${(err as Error).message}`, { status: 400 });
  }

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session;
    const clerkUserId = session.metadata?.clerkUserId;

    if (clerkUserId) {
      await clerkClient.users.updateUser(clerkUserId, {
        publicMetadata: {
          isSubscribed: true,
          subscriptionId: session.subscription?.toString()
          // 其他需要同步的字段
        }
      });
    }
  }

  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

• 检查Clerk密钥权限：确认Clerk的秘钥有Users: Update权限，在Clerk Dashboard的「API Keys」里查看设置。

额外排查项 #

• 检查next.config.js：如果有重写/重定向规则，别把/api/webhooks路径改走其他地方。
• 再次核对环境变量：Vercel控制台的「Environment Variables」里，确认STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET、CLERK_SECRET_KEY都是生产环境的正确密钥，没有拼写错误。

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