# 计费集成 ## 说明此技能提供了与 Stripe 的完整 Clerk Billing 集成，用于订阅管理、定价计划和付款处理。 Clerk Billing 通过直接连接到 Stripe，同时处理用户界面、权利逻辑和会话感知计费流程，消除了对自定义 Webhook 和支付 UI 的需求。 ### 1\.启用职员计费在您的职员仪表板中初始化职员账单： # 运行自动安装脚本 bash ./skills/billing-integration/scripts/setup-billing.sh **这有什么作用：** * 指导您完成文员仪表板设置 * 连接您的 Stripe 帐户 * 启用计费功能 * 配置生产/沙箱模式 **手动设置步骤：** 1. 导航至职员仪表板 > 配置 > 计费 2. 点击“启用计费” 3.连接您的Stripe账户（或使用沙箱模式进行开发） 4. 配置计费设置和默认值 ### 2\.配置定价计划创建订阅计划和功能： # 运行计划配置脚本 bash ./skills/billing-integration/scripts/configure-plans.sh **配置过程：** 1. 导航到仪表板 > 配置 > 订阅计划 2. 单击“添加用户计划”(B2C) 或“添加组织计划”(B2B) 3. 输入计划详细信息： * 名称（例如“专业计划”） * Slug（自动生成，例如“pro_plan”） * 描述 * 定价（按月/按年） 4. 添加功能到计划中： * 功能名称（例如“AI助手”） * 功能块（例如“ai_assistant”） * 功能描述 5. 根据使用情况设置功能限制 **计划类型：** * **用户计划**：与个人用户绑定的 B2C 订阅 * **组织计划**：团队/公司的 B2B 订阅 * **免费套餐**：功能有限的可选免费计划 * **试用计划**：限时免费使用付费功能 ### 3\.实施定价表添加定价显示组件： **使用模板：** # 复制定价页面模板 cp ./skills/billing-integration/templates/pricing-page.tsx app/pricing/page.tsx **基本实现：** 从“@clerk/nextjs”导入{PricingTable} 导出默认函数 PricingPage() { 返回（

选择您的计划

<定价表/>

） } **定价表提供什么：** * 从仪表板配置自动绘制计划 * 带 Stripe Elements 的内置付款表格 * 订阅创建和管理 * 响应式设计，匹配 Clerk UI * 会话感知（显示登录用户的当前计划） ### 4\.实施结账流程创建完整的结账体验： # 复制结账流程模板 cp ./skills/billing-integration/templates/checkout-flow.tsx 组件/checkout-flow.tsx **结帐功能：** * 方案选择与比较 * 付款方式集合 * 订阅确认 * 错误处理 * 成功重定向 * 电子邮件收据（通过 Stripe 自动发送） **定制选项：** <定价表外观={{ 主题：“黑暗”，变量：{ 主要颜色：'#3b82f6', borderRadius: '0.5rem', } }} onSuccess={(订阅) => { // 自定义成功处理程序路由器.push('/仪表板') }} /> ### 5\.访问控制和权利根据订阅状态保护功能： **前端保护：** 从 '@clerk/nextjs' 导入 { useAuth } 导出默认函数FeatureComponent() { const { 有 } = useAuth() const canUseFeature = has?.({ feature: 'ai_assistant' }) 如果（！canUseFeature）{ return } 返回 } **后端保护（API 路由）：** 从 '@clerk/nextjs/server' 导入 { auth } 导出异步函数 POST(request: Request) { const { 有 } = 等待 auth() if (!has({ 功能: 'ai_assistant' })) { 返回响应.json( { error: '需要订阅' }, {状态：403} ） } // 处理请求 } **组织级别访问权限：** const { 有 } = useAuth() const orgHasFeature = 有？.({ 权限：'组织：计费：管理'，功能：“团队工作空间” }) ### 6\.订阅管理使用户能够管理订阅： **内置管理：** 从 '@clerk/nextjs' 导入 { UserButton } 导出默认函数 Navigation() { 返回（） } **用户可以访问的内容：** * 查看当前计划和功能 * 查看发票历史记录 * 更新付款方式 * 升级/降级计划 * 取消订阅 * 查看即将更新的内容 **自定义管理界面：** # 复制订阅管理模板 cp ./skills/billing-integration/templates/subscription-management.tsx 组件/subscription-management.tsx ### 7\. Webhook 处理（可选）虽然 Clerk 自动处理大多数 Webhook 逻辑，但您可能需要自定义 Webhook： * 使用情况跟踪 * 自定义通知 * 分析集成 * 第三方服务集成 # 设置 webhook 处理程序 bash ./skills/billing-integration/scripts/setup-webhooks.sh **常见 Webhook 事件：** * `subscription.created` \- 新订阅 * `subscription.updated` \- 计划变更 * `subscription.deleted` \- 取消 * `invoice. payment_succeeded` \- 支付成功 * `invoice. payment_failed` \- 支付失败 **处理程序模板：** # 复制 webhook 处理程序模板 cp ./skills/billing-integration/templates/webhook-handlers/subscription-created.ts app/api/webhooks/subscription-created/route.ts cp ./skills/billing-integration/templates/webhook-handlers/ payment-succeeded.ts app/api/webhooks/ payment-succeeded/route.ts ### 8\.测试与开发 **沙盒模式：** * 使用Clerk的沙盒模式进行开发 * 最初不需要 Stripe 帐户 * 测试所有计费流程，无需实际付款 * 准备好后切换到生产 **测试卡（条纹）：** 成功：4242 4242 4242 4242 拒绝：4000 0000 0000 0002 3D 安全：4000 0027 6000 3184 **测试清单：** * 计划选择和显示 * 付款表格功能 * 订阅创建 * 功能访问控制 * 计划升级/降级 * 取消订阅 * 发票生成 * 电子邮件通知 ## 示例 ### 示例 1：完整的 SaaS 计费流程 # 1. 在仪表板中启用计费 bash ./skills/billing-integration/scripts/setup-billing.sh # 2. 配置定价计划 bash ./skills/billing-integration/scripts/configure-plans.sh # 3. 实施定价页面 cp ./skills/billing-integration/templates/pricing-page.tsx app/pricing/page.tsx # 4.添加订阅管理 cp ./skills/billing-integration/templates/subscription-management.tsx 组件/subscription-management.tsx # 5. 复制完整示例 cp ./skills/billing-integration/examples/saas-billing-flow.tsx app/subscribe/page.tsx **结果：** 完整的计费系统，具有定价显示、结账和订阅管理功能 ### 示例 2：具有功能门的免费增值模式 **设置：** 1. 创建具有基本功能的“免费”计划 2. 创建具有高级功能的“Pro”计划 3. 在整个应用程序中实施功能门 **实施：** // 功能门控组件从 '@clerk/nextjs' 导入 { useAuth } 从“@clerk/nextjs”导入{PricingTable} 导出默认函数 PremiumFeature() { const { 有 } = useAuth() if (!has({ 功能: 'premium_analytics' })) { 返回（

高级分析

升级到专业版以解锁高级分析

<定价表/>

） } 返回 } ### 示例 3：组织计费 (B2B) **设置：** 1. 在仪表板中启用组织计划 2. 配置基于团队的定价 3. 实现组织计费接口 **实施：** 从 '@clerk/nextjs' 导入 { useOrganization } 导出默认函数 OrgBilling() { const { 组织 } = useOrganization() 返回（

{组织？.名称}的账单

） } ### 示例 4：基于使用情况的计费 **设置：** 1. 在仪表板中配置基于使用情况的功能 2. 设置每个计划的使用限制 3. 跟踪应用程序的使用情况 **实施：** // 跟踪 API 使用情况从 '@clerk/nextjs/server' 导入 { clerkClient } 导出异步函数 POST(request: Request) { const { userId } = 等待 auth() // 检查当前使用情况 const 用户 = 等待 clerkClient.users.getUser(userId) const currentUsage = user.publicMetadata.apiUsage || 0 // 检查限制 const { 有 } = 等待 auth() const limit = has({ feature: 'api_calls_1000' }) ？ 1000：100 if (当前使用情况 >= 限制) { return Response.json({ error: '达到使用限制' }, { status: 429 }) } // 增加使用量等待 clerkClient.users.updateUserMetadata(userId, { 公共元数据：{ apiUsage: 当前Usage + 1 } }) // 处理请求 } ## 要求 **文员设置：** * 已配置应用程序的文员帐户 * 在仪表板中启用职员计费 * Next.js 13.4+ 与应用程序路由器 * `@clerk/nextjs` 版本 5.0+ **条纹要求：** * Stripe账户（生产或测试模式） * Stripe可发布密钥和秘密密钥 * 在 Stripe 中配置的产品和价格（通过 Clerk 同步） **环境变量：** NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_... CLERK_SECRET_KEY=sk_test_... **依赖关系：** { "@clerk/nextjs": "^5.0.0", "下一个": "^14.0.0", “反应”：“^18.0.0” } **项目结构：** 应用程序/ ├── 定价/ │ └── page.tsx # 带 PricingTable 的定价页面 ├── 订阅/ │ └── page.tsx # 结账流程 ├── API/ │ └── webhooks/ # 可选的自定义 webhooks 组件/ ├── 订阅管理.tsx └── 升级提示.tsx ## 安全最佳实践 **切勿对凭证进行硬编码：** # ❌ 错误 STRIPE_SECRET_KEY=sk_live_actual_key_here # ✅ 正确 STRIPE_SECRET_KEY=your_stripe_secret_key_here **始终使用环境变量：** // ✅ 从环境中读取 const stripeKey = process.env.STRIPE_SECRET_KEY 如果（！stripeKey）{ 抛出新错误（'STRIPE_SECRET_KEY 未配置'） } **保护 API 路由：** * 始终使用“auth()”验证身份验证 * 检查服务器端的功能权限 * 验证webhook签名 * 在生产中使用HTTPS **Webhook 安全性：** 从 'next/headers' 导入 { headers } 从 '@/lib/stripe' 导入 { stripe } 导出异步函数 POST(request: Request) { const body = 等待 request.text() const 签名 = headers().get('stripe-signature') 尝试{ const 事件 = stripe.webhooks.constructEvent( 身体, 签名, process.env.STRIPE_WEBHOOK_SECRET ） // 处理事件 } 捕获（错误）{ return Response.json({ error: '无效签名' }, { status: 400 }) } } ## 配置文件 **文员计费设置（仪表板）：** * 订阅计划和功能 * 定价等级和间隔 * 试用期配置 * 取消行为 * 发票设置 * 接受付款方式 **条带配置（已同步）：** * 产品 → 文员计划 * 价格 → 职员定价等级 * 顾客 → 文员用户 * 订阅 → 用户/组织订阅 * 付款方式 → 自动存储 ## 最佳实践 **方案设计：** * 从 2-3 个明确的层级开始（免费、专业、企业） * 使功能差异明显 * 使用清晰、注重利益的名称 * 设置适当的价格点 * 考虑年度折扣 **用户体验：** * 清楚地显示当前计划 * 使升级变得简单（从应用程序中一键点击） * 提供取消宽限期 * 发送清晰的电子邮件通知 * 主动显示使用限制 **访问控制：** * 始终检查服务器端的权利 * 仅对用户体验使用前端检查 * 实现优雅降级 * 在相关时刻显示升级提示 * 降级时不要破坏现有功能 **定价策略：** * 价格基于价值，而不是成本 * 使用心理定价（29 美元 vs 30 美元） * 提供年度计划折扣 * 考虑基于使用的可扩展性 * 与真实用户测试定价 **盈利方式：** * 免费增值：免费套餐+付费升级 * 试用：7-14天免费试用，然后收费 * 分层：具有不同功能的多个计划 * 基于使用情况：按 API 调用/用户/功能付费 * 混合：基本费+使用费 ## 与 Clerk 功能集成 **组织：** * 启用 B2B 组织计费 * 设置每个座位的定价 * 允许组织管理员管理计费 * 跟踪组织级别的使用情况 **用户管理：** * 将订阅链接到用户帐户 * 将订阅状态存储在用户元数据中 * 使用“publicMetadata”作为客户端可访问的数据 * 使用“privateMetadata”来存储敏感的账单数据 **会话意识：** * 登录后定价表显示当前计划 * 自动处理升级流程 * 如果未验证则重定向到登录 * 保留预期的计划选择 ## 故障排除 **常见问题：** 1. **定价表未显示：** * 验证仪表板中是否启用了计费 * 检查计划是否配置 * 确保 Stripe 已连接 * 验证组件导入 2. **付款失败：** * 检查 Stripe API 密钥 * 验证webhook端点 * 使用 Stripe 测试卡进行测试 * 查看 Stripe 仪表板日志 3. **访问控制不起作用：** * 验证功能块完全匹配 * 检查计划包括该功能 * 确保订阅处于活动状态 * 测试客户端和服务器检查 4. **Webhooks 未触发：** * 验证 webhook URL 是否正确 * 检查 webhook 签名秘密 * 为本地开发启用 webhook 转发 * 查看 Clerk webhook 日志 **调试：** // 记录订阅状态 const { 有，调试 } = useAuth() console.log('验证调试：', 调试) console.log('有功能：', has({ 功能: 'ai_assistant' })) ** ** **插件：** clerk **版本：** 1.0.0 **类别：** 计费和货币化 **技能类型：** 集成和设置

计费集成

包含技能