# @frigear-nu/stripe 中文文档

规范地址：https://npmcn.com/package/%40frigear-nu/stripe/

版本：0\.4\.0
npm 元数据更新时间：2026-11-12T15:49:38.546Z
中文译文更新时间：2026-11-15T14:29:18.538Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40frigear-nu/stripe
原文对照：https://npmcn.com/package/%40frigear-nu/stripe/?lang=original
项目主页：https://docs.frigear.dev/modules/commerce/stripe
源码仓库：https://github.com/Frigear-nu/frigear-nu

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

- 包体积（解压后）：24.3 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：@nuxthub/core ^0\.10\.12
- 首次发布：2026-10-09T14:39:55.190Z
- 最新版本发布：2026-11-12T15:49:38.034Z
- 近 30 天下载量：2688（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

Frigear生态系统的核心花纹管:SDK接入,客户连接,以及经核实的,能被其他模块订阅的一等元的网页hook.

## 安装

```sh
npm install @frigear-nu/stripe
```

也可以使用：`pnpm add @frigear-nu/stripe`、`yarn add @frigear-nu/stripe`、`bun add @frigear-nu/stripe`

## README

# @frigear-nu/ stripe (英语)

用于 friger 生态系统的核心花纹管. 拥有 SDK, 用户 <- > 条纹客户链接和单一 已校验, 等同于其它模块( 订阅、 支付、...) 所订阅的 。 没有产品 逻辑本身.

## 设置

```ts
export default defineNuxtConfig({
  modules: ['@nuxthub/core', '@frigear-nu/users', '@frigear-nu/stripe'],
  hub: { db: { dialect: 'sqlite', driver: 'libsql' }, kv: true }, // kv is required (webhook idempotency)
  stripe: { settings: { webhookPath: '/api/stripe/webhook' } }, // optional, this is the default
})
```

`unstorage` 必须由主机应用程序(NuxtHub KV需要它)解决.

环境变量:

| 变量 | 目的 |
| --- | --- |
| `NUXT_STRIPE_SECRET_KEY` | 条纹密钥( O)`runtimeConfig.stripe.secretKey`(中文(简体) ) |
| `NUXT_STRIPE_WEBHOOK_SECRET` | Webhook 签名秘密( Name`whsec_...`(中文(简体) ) |
| `NUXT_STRIPE_API_VERSION` | 可选的覆盖, 默认为被锁定 `2026-09-30.endive` |
| `NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | 可公布的密钥( E)`runtimeConfig.public.stripe.publishableKey`(中文(简体) ) |

## 数据库

扩展 `users` 带有无效的表格 `stripe_customer_id` 栏。 在主机应用中生成并实现迁移.

## 服务器 utils( 自动导入于硝基)

-   `useStripe()` - Frede SDK,使用取取的HTTP客户端(Cloudflare Workers相容).
-   `ensureStripeCustomer(userId)` - 返回用户的 Streape 客户端 ID: 存储 id, 或者通过电子邮件进行 Streape 搜索, 或者一个新的客户端( 持久性) .
-   `getStripeCustomerUser(customerId)` - 条纹客户身份的本地用户行,或 `null`。 。 。 .

## 网页

`POST /api/stripe/webhook` 读取生体,验证签名(`constructEventAsync` + 亚晶体,并 发送到处理者。 被处理的事件ID被存储在NuxtHub KV中长达7天,因此重复被忽略. 如果有的话 处理器抛出,其他仍然运行,响应是500(Stripe retrits),事件没有被标记处理 - **处理者必须是一能的**. 硝基钩 `stripe:event` 每一次事件都会被发射.

## 订阅事件

从一个模块( 构建时间, 捆绑到服务器中 - 没有运行时间扫描) :

```ts
import { registerStripeEventHandler } from '@frigear-nu/stripe/utils'

registerStripeEventHandler(nuxt, {
  events: ['customer.subscription.updated', 'checkout.session.completed'], // or '*'
  handler: resolver.resolve('./runtime/server/stripe/subscription-events'),
  order: 100, // optional, lower runs first
})
```

```ts
// runtime/server/stripe/subscription-events.ts
import { defineStripeEventHandler } from '@frigear-nu/stripe/utils'

export default defineStripeEventHandler<'customer.subscription.updated' | 'checkout.session.completed'>(
  async (event, { stripe, userId, event: h3Event }) => {
    // `event` is narrowed by `event.type`; `userId` is null for unknown customers
  },
)
```

从主机应用程序的 Nitro 插件 :

```ts
export default defineNitroPlugin(() => {
  onStripeEvent('invoice.payment_failed', (event, ctx) => { /* ... */ })
})
```

## 常见问题

### @frigear-nu/stripe 是什么？

Frigear生态系统的核心花纹管:SDK接入,客户连接,以及经核实的,能被其他模块订阅的一等元的网页hook\.

### 如何安装 @frigear-nu/stripe？

在项目目录运行 npm install @frigear-nu/stripe，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@nuxthub/core（^0\.10\.12）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frigear-nu/stripe 支持 TypeScript 吗？

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

### @frigear-nu/stripe 支持 ESM 还是 CommonJS？

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

### @frigear-nu/stripe 可以商用吗？

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

### @frigear-nu/stripe 的下载量有多少？

根据 npm 官方下载统计，@frigear-nu/stripe 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,688 次，日均约 90 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @frigear-nu/stripe 还在维护吗？

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