Next.js App Router Stripe Webhook在GCP工作站返回302而非200求助

问题背景 #

需在基于App Router的Next.js应用中实现Stripe webhook端点，处理checkout.session.completed事件并返回200 OK确认接收。但部署在Google Cloud Workstations后，Stripe推送事件时始终收到302重定向响应，导致交付失败。即使简化逻辑仅返回200，问题依旧存在。

技术栈：

• Next.js（最新版本，App Router）
• TypeScript
• Google Cloud Workstations（公网访问）
• Stripe Node.js SDK

已确认：端点可公网访问、环境变量配置正确、无干扰的middleware.ts、日志显示执行到返回步骤。

排查思路与解决方案 #

1. 路由路径与URL匹配问题 #

Next.js在Linux环境（含Cloud Workstations）下路径区分大小写，且对URL末尾斜杠的处理可能触发重定向：

• 检查Stripe配置的webhook URL是否与路由路径完全一致：比如Stripe用/api/stripe-webhook/（带斜杠），而路由文件是app/api/stripe-webhook/route.ts，Next.js会自动重定向不带斜杠的请求到带斜杠的（或反之）。
• 解决：要么调整Stripe的URL匹配路由的斜杠规则，要么在next.config.js中设置trailingSlash统一规则：

  const nextConfig = {
    trailingSlash: true, // 或false，确保与Stripe URL一致
  };
  module.exports = nextConfig;
  

• 确认路由文件路径拼写完全正确：比如stripe-webhook不能写成Stripe-Webhook，否则会因大小写不匹配导致路由未命中，触发默认重定向。

2. NextResponse返回逻辑错误 #

检查webhook代码是否误触发重定向：

• 确保没有使用NextResponse.redirect()，而是明确返回200状态的响应。最简示例：

  import { NextResponse } from 'next/server';
  
  export async function POST(request: Request) {
    console.log('Webhook triggered');
    return new NextResponse(null, { status: 200 });
  }
  

• 避免在返回前有未捕获的异步错误，即使日志显示执行到返回步骤，也需确认Promise是否正确处理（比如没有await异步操作导致提前返回默认响应）。

3. Next.js配置中的重定向/重写规则 #

检查next.config.js中是否存在针对/api/*路径的重定向或重写规则：

• 查看redirects或rewrites数组，确认没有匹配/api/stripe-webhook的规则，这类规则会强制修改请求路径导致302。

4. Google Cloud Workstations网络代理干扰 #

Cloud Workstations的公网访问代理可能存在路径重写或自动添加前缀的情况：

• 用curl模拟Stripe请求并查看详细响应：

  curl -v -X POST https://your-workstation-public-url/api/stripe-webhook \
    -H "Content-Type: application/json" \
    -d '{}'
  

• 观察返回的Location响应头，确认重定向的目标路径，判断是否是Workstations代理修改了请求路径。如果存在此类情况，需调整Stripe的webhook URL匹配代理后的路径，或在Workstations配置中关闭不必要的路径重写。

5. 请求方法与路由导出验证 #

确认路由文件中仅导出POST方法（Stripe webhook仅用POST请求）：

• 如果同时导出了GET方法，虽不会直接导致302，但需确保POST请求被正确处理。避免因路由导出不规范导致Next.js的默认路由行为干扰。

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