Next.js 14集成Stripe订阅支付：Webhook出现401未授权错误

核心排查方向及修复方案 #

1. Vercel预览环境的默认基础认证拦截 #

Vercel预发布预览环境默认会开启基础HTTP认证，防止外部无关访问。Stripe的Webhook请求不会携带这些认证信息，直接被拦截返回401。

• 解决办法：
  • 临时关闭预览环境的密码保护：进入Vercel项目对应预览环境的设置，找到「Password Protection」选项关闭即可（测试场景适用）。
  • 给Stripe Webhook添加认证头：在Stripe控制台的Webhook配置里，新增自定义HTTP头Authorization: Basic [base64编码的用户名:密码]。编码值可以通过终端命令echo -n "你的用户名:你的密码" | base64生成。

2. Webhook路由意外引入认证逻辑 #

虽然你没配置middleware.ts，但如果src/app/api/webhooks/stripe/route.ts里不小心调用了用户认证相关的方法（比如getServerSession、Auth库的auth()函数），Stripe请求没有携带用户会话Cookie，就会触发401，且请求到不了核心处理逻辑。

• 解决办法：彻底清理Webhook路由里的用户认证代码，保证该路由完全公开。Stripe Webhook只需要验证签名，不需要用户登录状态。

3. 环境变量或签名验证问题（伪装401） #

如果STRIPE_WEBHOOK_SECRET配置错误，或者签名验证逻辑有问题，也可能导致请求被拦截。不过你提到看不到控制台日志，这个可能性稍低，但仍需排查：

• 解决办法：
  • 确认Vercel环境变量里的STRIPE_WEBHOOK_SECRET是对应测试模式的密钥（测试支付场景），别用生产密钥。
  • 临时注释掉签名验证代码，重新部署后测试，看请求是否能到达处理函数并输出日志。如果可以，再针对性修复签名验证逻辑。

4. Vercel部署缓存或路由配置问题 #

偶尔Vercel部署后的缓存会导致旧配置生效，或者路由导出格式错误。

• 解决办法：
  • 在Vercel控制台重新部署预览环境，勾选「Redeploy with cache cleared」清除缓存。
  • 检查route.ts的导出是否正确：确保是export async function POST(req: Request) { ... }的标准格式，没有语法错误或错误导出。

快速验证方法 #

用curl测试时带上预览环境的认证头，看是否能绕过401：

curl -X POST https://subdomain.domain.xyz/api/webhooks/stripe -u "预览用户名:预览密码" -H "Content-Type: application/json" -d '{}'

如果返回不再是401，直接坐实是基础认证的问题。

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