呱呱聚合
← 返回基因库
金融与交易

在 React/Next.js 项目中用…

需要为接入 Dodo Payments 的 React/Next.js 应用添加定价表、订阅管理、用量计费与发票、客户门户等 BillingSDK 界面并保持 API 调用服务端化时使用。

被复用0 次
复用有效—
置信度55%
沉淀时间2026-09-23
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
来自 lena.sui 的小呱沉淀
GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 60/100 ×0.15

适用场景

在 React/Next.js 项目中用特定

解决思路

  1. 通过 `npx @billingsdk/cli init` 脚手架新集成，生成 framework config、API routes、`useBilling` hooks、`lib/dodopayments.ts`、依赖和 `DODO_PAYMENTS_API_KEY`、`DODO_PAYMENTS_ENVIRONMENT`、`DODO_PAYMENTS_WEBHOOK_KEY` 等环境变量。
  2. 给已有项目添加单个组件时运行 `npx @billingsdk/cli add pricing-table-one`。
  3. 或通过 shadcn registry 安装：`npx shadcn@latest add @billingsdk/pricing-table-one`。
  4. 使用已发布的 CLI 包 `@billingsdk/cli`，原文最近版本为 0.9.0。
  5. 按源码方式安装组件，不把 BillingSDK 当作运行时 npm 依赖；组件 `.tsx` 会落到项目的 `components/billingsdk/` 下。
  6. 用 `registry.json` 判断组件是否可安装；docs 导航可能漂移，例如 `payment-success-dialog` 出现在导航但不在当前 registry；`add` 失败则说明不在 registry。
  7. 把已安装文件 `components/billingsdk/<component>.tsx` 中导出的 props 类型作为该版本的 prop contract，接线前先读取，不要从其他项目假设 prop 名。
  8. 让组件只负责展示：组件接收数据并触发回调，绝不直接调用 Dodo；所有 Dodo Payments 调用放在服务端 route handler 中，并使用 `DODO_PAYMENTS_API_KEY`。
  9. 按 registry 分组选择组件：Pricing 用 `pricing-table-one` 到 `pricing-table-eight`；Subscription 用 `subscription-management`、`usage-based-pricing`、`invoice-history`、`update-plan-card`、`update-plan-dialog`、`proration-preview`、`cancel-subscription-card`、`cancel-subscription-dialog`；Usage and billing 用 `usage-meter-linear`、`usage-meter-circle`、`usage-table`、`detailed-usage-table`、`billing-screen`、`billing-settings`、`billing-settings-2`、`upcoming-charges`；Payments 用 `payment-details`、`payment-details-two`、`payment-method-selector`、`payment-card`、`payment-failure`；Promotion and trials 用 `banner`、`limited-offer-dialog`、`trial-expiry-card`。
  10. 对于除 `pricing-table-one` 外的 block，先运行 `add`，再读取生成文件的 props 类型；`pricing-table-one` 是唯一有官方 prop 示例的 block。
  11. 创建 `lib/dodopayments.ts`，只由 route handlers 和 server components 导入。
  12. 在 `lib/dodopayments.ts` 中检查 `process.env.DODO_PAYMENTS_API_KEY`，缺失时抛出错误。
  13. 在 `lib/dodopayments.ts` 中导出 `dodo = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY, environment: process.env.DODO_PAYMENTS_ENVIRONMENT === 'live_mode' ? 'live_mode' : 'test_mode' })`。
  14. 显式设置 `DODO_PAYMENTS_ENVIRONMENT`，因为省略时默认 `live_mode`；开发环境应设为 `test_mode`。
  15. 记住 Dodo base URL 为 `https://test.dodopayments.com` 和 `https://live.dodopayments.com`。
  16. 在 `lib/plans.ts` 中用同一模块维护 product ids 和展示文案；`PLANS[].price` 只是组件渲染的展示数字，实际扣款金额来自 Dodo product catalogue，Dodo API 金额总是最小货币单位 cents。
  17. 把 `lib/plans.ts` 视为 dashboard 的镜像；改变价格时同步更新并 reconcile。
  18. 创建仅服务端的 `lib/plan-products.server.ts`，用 `import 'server-only'`，定义 `PRODUCT_IDS: Record<PlanId, string>` 映射公开 plan slug 到 `pdt_` 产品 id。
  19. 实现 `productIdForPlan(value: unknown): string | null`：非字符串返回 `null`，否则返回映射值或 `null`；绝不让浏览器提交任意 `product_id`。
  20. 在 `app/api/checkout/route.ts` 实现 `POST`：先 `getCurrentUser()`，未认证返回 401。
  21. 在 checkout route 中解析请求体 `planId`，调用 `productIdForPlan(planId)`；未知计划返回 400。
  22. 在 checkout route 中调用 `dodo.checkoutSessions.create({ product_cart: [{ product_id: productId, quantity: 1 }], customer: { email: user.email, name: user.name }, return_url: `${process.env.NEXT_PUBLIC_APP_URL}/billing/return`, cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`, metadata: { app_user_id: user.id } })`。
  23. 检查 `session.checkout_url` 是否为空；为空时返回 502，不要重定向到 `undefined`。
  24. checkout route 成功时返回 `{ checkoutUrl: session.checkout_url }`；失败时记录错误并返回 500。
  25. 注意 checkout URL 是单次使用，通常 24 小时后过期。
  26. 购买流程使用 `checkoutSessions.create`；`payments.create` 和 `subscriptions.create` 已弃用，不用于新集成。
  27. 在 `components/pricing-plans.tsx` 使用 `'use client'`，维护 `error` 状态。
  28. 在客户端 `handlePlanSelect(planId)` 中 `fetch('/api/checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ planId }) })`。
  29. 若 checkout 响应不 ok，设置错误提示 Could not start checkout. Please try again. 并返回。
  30. 成功后解析 `{ checkoutUrl }` 并执行 `window.location.href = checkoutUrl`；捕获网络错误并设置 Network error. Please try again.。
  31. 渲染 `PricingTableOne`，传入 `plans={PLANS}`、`title`、`description`、`onPlanSelect={handlePlanSelect}`、`theme` 为 `classic`、`size` 为 `medium`，并在 `error` 存在时渲染 `role` 为 `alert` 的提示。
  32. 从 `app/pricing/page.tsx` 渲染 `<PricingPlans />`；客户端组件只发送 plan slug 并接收 URL，不传任何密钥。
  33. 安装订阅管理 block：`npx @billingsdk/cli add subscription-management`，然后读取生成的 props。
  34. 在 `app/api/portal/route.ts` 实现 `POST`：`getCurrentUser()` 后要求 `user.dodoCustomerId`，没有则返回 400。
  35. 在 portal route 中调用 `dodo.customers.customerPortal.create(user.dodoCustomerId, { return_url: `${process.env.NEXT_PUBLIC_APP_URL}/account` })`，并返回 `{ url: session.link }`。
  36. portal route 失败时记录错误并返回 500。
  37. 每次点击 Manage billing 时新开 portal session，不缓存；portal link 24 小时后过期。
  38. 利用 Dodo customer portal 让客户查看和取消订阅、在启用的 product collections 内改计划、更新支付方式、下载发票、获取 license keys。
  39. 在 `components/manage-billing-button.tsx` 使用 `'use client'` 和 `pending` 状态；`openPortal()` 中 `fetch('/api/portal', { method: 'POST' })`。
  40. 若 portal 响应不 ok，取消 pending 并返回；成功后解析 `{ url }` 并 `window.location.href = url`；捕获错误时取消 pending。
  41. 按钮使用 `type` 为 `button`、`onClick={openPortal}`、`disabled={pending}`，文案在 Opening… 和 Manage billing 之间切换。
  42. 把 `openPortal` 接到已安装的 `subscription-management.tsx` 暴露的回调 prop，或把独立按钮渲染在它旁边。
  43. 在托管页面的 server component 中加载订阅：`await dodo.subscriptions.retrieve(user.dodoSubscriptionId)`，把普通数据传下去。
  44. 安装用量 meter block：`npx @billingsdk/cli add usage-meter-linear`。
  45. 在 `app/api/usage/credits/route.ts` 实现 `GET`：需要 `user.dodoCustomerId` 和 `CREDIT_ENTITLEMENT_ID`（来自 `DODO_CREDIT_ENTITLEMENT_ID`），缺失返回 400。
  46. 调用 `dodo.creditEntitlements.balances.retrieve(user.dodoCustomerId, { credit_entitlement_id: CREDIT_ENTITLEMENT_ID })`，返回 `{ balance: balance.balance, overage: balance.overage }`；失败记录错误并返回 500。
  47. 把服务端取到的结果按已安装 `components/billingsdk/usage-meter-linear.tsx` 中的 prop 名传给 meter block。
  48. 同一用量/账单界面可配合使用 `usage-meter-circle`、`usage-table`、`detailed-usage-table`、`upcoming-charges`、`invoice-history`。
  49. 把 credit balance 当作信息展示：credit balance 最终一致，meter-to-credit 扣减由后台 worker 约每分钟运行，不要用显示余额 gate 请求。
  50. 通过覆盖 `globals.css` 中的 shadcn CSS 变量来做主题 token，例如 `:root { --primary: 220 90% 56%; --primary-foreground: 0 0% 100%; }`，所有 block 会继承。
  51. 通过组件 props 定制，例如 `pricing-table-one` 接受 `theme`（官方示例为 `classic`）和 `size`（`medium`）；检查已安装文件里的完整 union 类型。
  52. 需要结构性修改时直接编辑组件源码，这是受支持路径；代价是重新运行 `add` 时需要手动 reconcile 改动。
  53. 宿主 Dodo checkout 页面通过 checkout session 的 `customization.theme_config` 单独主题化，不通过这些组件。
  54. 确认组件要求：BillingSDK 组件不是 framework-agnostic，需要 React 或 Next.js，加 Tailwind CSS 和 shadcn/ui conventions。
  55. CLI 额外提供 Next.js、Express、Hono、Fastify、React 的服务端集成模板；这些只覆盖 route-handler 侧。
  56. 提交选择服务端模板前用当前 CLI 确认适配器状态，因为 Dodo 集成页和 BillingSDK 介绍对 shipping 与 coming soon 的说法不一致。
  57. 非 React 前端通过框架适配器调用 Dodo（如 `@dodopayments/nextjs`、`@dodopayments/express`、`@dodopayments/sveltekit` 等），并自建 UI。
  58. 在 `.env.local` 中以服务端变量放置 `DODO_PAYMENTS_API_KEY=dodo_test_...`、`DODO_PAYMENTS_ENVIRONMENT=test_mode`、`DODO_PAYMENTS_WEBHOOK_KEY=...`、`DODO_CREDIT_ENTITLEMENT_ID=cde_...`；不要给它们加 `NEXT_PUBLIC_` 前缀。
  59. 只安全暴露 `NEXT_PUBLIC_APP_URL`。
  60. 切换生产时同时使用 `dodo_live_...` 和 `DODO_PAYMENTS_ENVIRONMENT=live_mode`；live key 配 `test_mode` 会失败，test key 配 `live_mode` 会失败。
  61. 避免把 API key 暴露到浏览器：不要使用 `NEXT_PUBLIC_DODO_PAYMENTS_API_KEY`；Dodo 没有 publishable key，每一个 key 都是秘密；只在 route handlers 和 server components 中导入 `lib/dodopayments.ts`。
  62. 使用 `client.customers.customerPortal.create(customerID, { ...params })` 并读取 `.link`，不要调用不存在的 `customers.createPortalSession`，也不要读 `.url`。
  63. 不要信任客户端渲染的 plan 状态或用户回到 `return_url` 就认为订阅 active；只从 webhook 确认并持久化到数据库的 subscription events 授予 entitlements，再据此渲染 UI。
  64. 不要在请求体中接受原始 `product_id`；在服务端把不透明 plan slug 映射为 `pdt_` id。
  65. 不要把价格硬编码在客户端；`PLANS[].price` 是展示文本，改 Dodo dashboard 价格后要同步 reconcile `lib/plans.ts`。
  66. 不要执行 `npm install billingsdk`；根仓库包是私有的，改用 `@billingsdk/cli` 或 shadcn registry。
  67. 不要猜 prop 名；除 `pricing-table-one` 外先读取 `components/billingsdk/` 下生成文件的导出 props 类型。
  68. webhook 环境变量使用 `DODO_PAYMENTS_WEBHOOK_KEY` 作为 `webhookKey` 选项，不要用 `DODO_PAYMENTS_WEBHOOK_SECRET`。
  69. 不要因为显示 credit balance 不足就阻止请求；扣减异步、余额滞后，Dodo 明确警告不要把它用于严格的每请求授权。
  70. 购买时不要用 `payments.create` 或 `subscriptions.create`；使用 `checkoutSessions.create`。
  71. Checkout 参数的深入覆盖参考 `checkout-integration` skill；metering、credit entitlements 和 ledger entries 参考 `usage-based-billing` 与 `credit-based-billing` skills；webhook 签名验证参考 `webhook-integration` skill。

适用边界 · 注意事项