# @fantastic\.dev/better-stripe 中文文档

规范地址：https://npmcn.com/package/%40fantastic.dev/better-stripe/

版本：0\.111\.0
npm 元数据更新时间：2026-11-01T01:48:06.110Z
中文译文更新时间：2026-11-01T03:20:23.962Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fantastic.dev/better-stripe
原文对照：https://npmcn.com/package/%40fantastic.dev/better-stripe/?lang=original
项目主页：https://github.com/FantasticDevHQ/better-stripe#readme
源码仓库：https://github.com/FantasticDevHQ/better-stripe

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：23.5 MB，4878 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：9 个
- peer 依赖：react ^18\.3\.1 \|\| ^19\.0\.0，convex ^1\.46\.0，react-dom ^18\.3\.1 \|\| ^19\.0\.0
- 首次发布：2026-09-26T07:42:06.475Z
- 最新版本发布：2026-11-01T01:48:05.685Z
- 已发布版本数：147（近 12 个月 147 个）

## 中文简介

凸组件用于Stripe Accounts v2，订阅，计量计费和连接市场，与React工作流。

## 安装

```sh
npm install @fantastic.dev/better-stripe
```

也可以使用：`pnpm add @fantastic.dev/better-stripe`、`yarn add @fantastic.dev/better-stripe`、`bun add @fantastic.dev/better-stripe`

## README

# better-stripe

一、 [凸组件](https://docs.convex.dev/components) 对于Stripe Accounts v2， 计费和连接市场。它提供结帐，订阅，webhook 与React同步，市场费用和分割，支付，退款和争议 钩子和无头UI组件。

**版本**： `0.111.0` (pre - 1.0)。在1.0之前，API可能会在小版本之间发生变化。

连接平台使用默认的GA API版本。非联网商户使用 仅限客户的帐户v2需要预览访问权限和显式预览版本。 读了 [Accounts v2安装指南](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/accounts-v2-preview.md) 在集成之前。

## 包和应用程序职责

BetterStripe拥有可重复使用的支付协议、财务记录、持久执行、 和无样式的React工作流。示例应用程序演示了这些公共api 凸绑定和样式渲染器。消费者不需要复制其付款方式 或UI控制器来使用包。

您的应用程序验证呼叫者，授权原始帐户或付款， 选择产品和业务策略，并决定付费购买解锁的内容。 一次性购买使用付款结账；订阅使用订阅签出。 数字下载、访问授权、许可密钥、运输和履行属于 消费应用程序。一个成功的结帐页面本身并不是付款的证明。 使用经过验证的支付状态并使履行幂等。

看到 [示例边界审计](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/react-workflows-audit.md#package-and-example-boundary) 获取具体的所有权规则和其余的应用程序适配器。

## 安装

```bash
npm install @fantastic.dev/better-stripe
```

需要Node.js 20+，凸 `^1.46.0`，以及React/React DOM `^18.3.1` 或者 `^19.0.0`. 条带sdk作为依赖项包含。

## 快速启动

集 `STRIPE_SECRET_KEY` 在您的Convex部署中，然后连接组件、客户端、 而webhook路由如下。看到 [配置](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/configuration.md) 对所有 环境变量和TypeScript设置。

### 步骤1：注册组件

```typescript
// convex/convex.config.ts
import betterStripe from "@fantastic.dev/better-stripe/convex.config";
import { defineApp } from "convex/server";
import { v } from "convex/values";

// betterStripe requires STRIPE_SECRET_KEY; declare it at the app level and pass
// it to the component by reference.
const app = defineApp({
  env: { STRIPE_SECRET_KEY: v.string() },
});
app.use(betterStripe, {
  env: { STRIPE_SECRET_KEY: app.env.STRIPE_SECRET_KEY },
});

export default app;
```

### 步骤2：创建BetterStripe实例

```typescript
// convex/stripe.ts
import { BetterStripe } from "@fantastic.dev/better-stripe";

import { components } from "./_generated/api";

export const stripe = new BetterStripe(components.betterStripe, {
  STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
  triggers: {
    checkoutSession: {
      onCompleted: async (ctx, session) => {
        // App-specific transactional logic (same DB transaction)
      },
    },
  },
});

// Export the webhook handler pair; http.ts passes their refs to registerRoutes.
// `syncWebhook` runs your sync triggers in the same transaction as the component
// upsert; `asyncWebhook` runs your async hooks after commit.
export const { syncWebhook, asyncWebhook } = stripe.webhookHandlers();
```

### 步骤3：注册webhook路由

```typescript
// convex/http.ts
import { registerRoutes } from "@fantastic.dev/better-stripe";
import { httpRouter } from "convex/server";

import { components, internal } from "./_generated/api";

const http = httpRouter();

registerRoutes(http, components.betterStripe, {
  webhookPath: "/stripe/webhook",
  stripeSecretKey: process.env.STRIPE_SECRET_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
  webhookSecretV2: process.env.STRIPE_WEBHOOK_SECRET_V2,
  webhooks: internal.stripe,
});

export default http;
```

通过 `webhooks: internal.stripe` 在同一事务中运行同步触发器 作为组件写入。异步钩子在提交后运行。看到 [webhook和触发器](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/webhooks.md) 用于事件目的地、签名秘密和钩子示例。

创建指向的单独的V1快照和V2瘦事件目的地 `https://<your-deployment>.convex.site/stripe/webhook`． 存储他们的签名秘密 作为 `STRIPE_WEBHOOK_SECRET` 和 `STRIPE_WEBHOOK_SECRET_V2` 在您的凸部署中。 遵循 [webhook设置](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/webhooks.md#webhook-setup) 配置两个目的地。

## 文档

这个 [文档索引](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/README.md) 列出所有指南。开始:

-   [配置](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/configuration.md)、环境变量和API版本。
-   [客户端API](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/client-api.md)、服务器方法和恢复工作流。
-   [webhook和触发器](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/webhooks.md)、事件设置和事务回调。
-   [反应API](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/react-api.md) 和 [工作流实例](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/react-workflows.md).
-   [市场经济](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/marketplace.md) 和 [结算和支付](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/settlement.md).
-   [金融的观察](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/financial-observations.md) 和 [支出修正迁移](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/payout-revision-migration.md).
-   [迁移指南](https://npmcn.com/package/%40fantastic.dev/better-stripe/MIGRATION.md) 和 [版本切换](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/release-handoff.md).

这个 [示例应用程序](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md) 演示客户、卖家、联盟和管理流程，包括几个结帐 集成风格。

### 计量使用

使用本地的Stripe账单，即付即付，包括每月单位的超额费用。 以及预付信用卡。开发商选择单位、精度、费率和政策； BetterStripe拥有持久的使用/交付，津贴和信用会计， 更正，原始支付结算和可重用的React工作流。你的应用 拥有身份验证、计费活动和授权。

从……开始 [为开发人员和AI代理设置](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/metering-setup.md)，然后是 [可复制的三模式食谱](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/metered-usage.md) 和 [可运行的例子](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/usage-example.md)． 使用现有的条纹沙盒和 凸凭证。节拍器是可选的，从来不是先决条件。

看到 [反应的观点](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/usage-react.md) 和 [配置界面](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/usage-configuration.md) 表格，确切的使用，津贴，预付余额和分页历史。 [验证矩阵](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/usage-verification.md) 记录本地付费来源 证明，包装消费者和帐户/时钟限制。现有的应用程序应该跟进 [选择采用、模型转换和回滚](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/usage-rollout.md).

## 贡献

看到 [开发指南](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/development.md) 对于本地设置和代码生成， [测试工具](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/testing.md) 对于固定装置，和 [发布指南](https://npmcn.com/package/%40fantastic.dev/better-stripe/docs/releasing.md) 出版。运行 `pnpm run check:all` 在提交更改之前。

## 许可证

麻省理工学院

## 常见问题

### @fantastic\.dev/better-stripe 是什么？

凸组件用于Stripe Accounts v2，订阅，计量计费和连接市场，与React工作流。

### 如何安装 @fantastic\.dev/better-stripe？

在项目目录运行 npm install @fantastic\.dev/better-stripe，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.3\.1 \|\| ^19\.0\.0）、convex（^1\.46\.0）、react-dom（^18\.3\.1 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fantastic\.dev/better-stripe 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fantastic\.dev/better-stripe 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fantastic\.dev/better-stripe 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fantastic\.dev/better-stripe 可以商用吗？

@fantastic\.dev/better-stripe 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fantastic\.dev/better-stripe 还在维护吗？

最新版本 0\.111\.0 发布于 2026/11/01（2 天前）；至今共发布 147 个版本，其中过去 12 个月发布了 147 个；首次发布于 2026/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。