用途:在 Convex 应用中接入 Stripe 计费/支付,通过 @convex-dev/stripe 组件提供结算 action、由组件注册并自动验签的 httpAction webhook、存储于组件表的订阅状态,以及服务端订阅门控查询。
主要能力:创建订阅 Checkout 会话;通过 registerRoutes 注册 webhook 路由并由组件内部自动完成签名校验;订阅状态保存在组件表中,可在服务端按用户查询订阅是否有效(active 或 trialing)。
使用方式:先安装组件 npm install @convex-dev/stripe。然后在 convex/convex.config.ts 中用 defineApp 注册 stripe(注意必须从 '@convex-dev/stripe/convex.config.js' 导入,.js 扩展名为 Convex 打包器所需)。将 STRIPE_SECRET_KEY 与 STRIPE_WEBHOOK_SECRET 存入 Convex 环境变量。在 convex/http.ts 中用 httpRouter 与 registerRoutes(http, components.stripe, { webhookPath: '/stripe/webhook' }) 注册 webhook 路由。在 convex/billing.ts 中创建 checkout action(获取用户身份、getOrCreateCustomer、createCheckoutSession,mode 为 subscription)以及读取组件表的 isSubscribed 查询。运行 npx convex dev --once 安装组件并推送函数,确认输出 ✔ Installed component stripe。最后在 Stripe Dashboard 的 Webhooks 中添加端点 https://<deployment>.convex.site/stripe/webhook,订阅 checkout.session.completed、customer.subscription.、invoice.、payment_intent.*,并把签名密钥设为 STRIPE_WEBHOOK_SECRET。
适用场景:需要为 Convex 应用添加订阅制付费与访问控制的场景。
限制与规则:应使用 @convex-dev/stripe(npm: @convex-dev/stripe@^0.1.4),它通过 registerRoutes 内部处理 webhook 验签,不要手写 constructEvent webhook;密钥存放在 Convex 环境变量;门控必须基于服务端存储的订阅状态查询,而非客户端声明。资料未提供定价、配额或计费价格等更多信息。