# @funnelsgrove/runtime 中文文档

规范地址：https://npmcn.com/package/%40funnelsgrove/runtime/

版本：0\.46\.0
npm 元数据更新时间：2026-11-12T09:18:35.010Z
中文译文更新时间：2026-11-15T18:42:47.281Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40funnelsgrove/runtime
原文对照：https://npmcn.com/package/%40funnelsgrove/runtime/?lang=original
项目主页：https://github.com/The-Solid-Grove/funnelsgrove#readme
源码仓库：https://github.com/The-Solid-Grove/funnelsgrove

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

- 包体积（解压后）：869 kB，292 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-04-03T22:28:07.776Z
- 最新版本发布：2026-11-12T09:18:34.786Z
- 近 30 天下载量：9856（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：151（近 12 个月 151 个）

## 中文简介

共享漏斗运行时间合同和助手.

## 安装

```sh
npm install @funnelsgrove/runtime
```

也可以使用：`pnpm add @funnelsgrove/runtime`、`yarn add @funnelsgrove/runtime`、`bun add @funnelsgrove/runtime`

## README

# @ funnelsgrove/ 运行时间

共享漏斗运行时间合同和助手.

在编辑共享漏斗力学前读取此文件. 更深的运行时间行为是 记录 [`docs/product-specs/funnel-template-runtime.md`](https://npmcn.com/package/docs/product-specs/funnel-template-runtime.md)。 。 。 .

## 拥有漏斗力学

`@funnelsgrove/runtime` 拥有每个生成或发布的漏斗所依赖的可重复使用的力学:活性能,路由能,env分辨率,漏斗状态,预览/运行时间检测,以及通用运行时间UI. 漏斗带来自己的复制品,外观设计,计费目录,并步JSX.

## 使用此软件包

-   显示类型和验证
-   路由分辨率和出入口处理
-   运行时模式和公域/配置解析度
-   实验任务助手
-   预览桥解析和预览/运行时间检测
-   已发布的主题合同和 CSS 变量助手
-   漏斗上下文、流量控制器和通用运行时 UI 原始
-   漏斗瞄准镜状态/存储助手
-   浏览器安全 API 客户端帮助器
-   通过被动浏览器查询字符串访问 `useBrowserLocationSearch`
-   订阅交接和订阅管理屏幕,其副本保留为漏斗-本地
-   用于漏斗预览工具的测试模式开发者信息表面

## 不使用此软件包

-   漏斗专用步骤
-   品牌/主题资产
-   计费目录数据
-   分析运输
-   条条检出 UI
-   漏斗专用开发者部件副本
-   直接提供者 SDK 电话

## 公众表面

-   `config/*`:可显示,主题,字体,env,以及构建者-审查合同.
-   `runtime/*`:流出,路由,归属,特征旗,预览桥,URL属性,并显示验证.
-   `runtime/published-runtime-resolution`: 运行中的实验正常化和从定价任务中选择不可改变的报价. 内容 `paymentProvidersByMode` 结果揭示了选定报价的明确测试/使用 提供者; 缺少配置 `null`而非退职.
-   `services/*`:API客户端,运行时模式,公共env,项目env,logger,和漏斗状态帮助器.
-   `components/*`:通用运行时间上下文,订阅交接/管理,编辑面板,dev信息,和基础控制.
-   `content/*` 财务报告和审定财务报表 `steps/types`:共享步骤内容和分类合同.

## 浏览器 SDK 结构

`funnelSdkService` 仍然是公共切入点,采用同样的十八种方法 和导出输入/响应类型。 它是自动同步函数的普通对象; 方法 也可以在不丢失的情况下进行结构调整 `this` 装订.

执行生活 `services/funnel-sdk/`组合 `users`, (中文(简体) ), `uploads`, (中文(简体) ), `checkout`,以及 `subscriptions`。每种用途都有其终点和顺序. 除使用外保留请求映射器(例如, `checkout/requests.ts`),而非在通用绘图层. 只有运行时间身份, 信头、 JSON 传输和 API 错误处理属于 `shared/`。 。 。 .

SDK HTTP请求为漏斗服务. 服务器对服务器集成客户端和直接 付款提供者的电话不属于这里。 不创建工作流程类或文件 这些短请求序列。 照片上传准备通过API上传, 然后将原始的blob直接发送到其已签名的目的地,没有SDK头.

从0.1.2.0起,付款和订阅方法总是使用付款V2,包括: 主机检出 。 继承的 `paymentsApiVersion: 'v1'` 不再选择 V1. 通过公布的要约/简介/提供者/计划选择;订阅变异 需要列表 `subscriptionRef`。 。 。 . `createOneTimePaymentIntent` 删除; 使用情况 `createOneTimeCheckout` 退出会话 UI 而不是通过它的 密于支付意向表。 服务器 V1 路由被移除 。 在0.13.0中,公共配置歧视者 仅为 V2 , 且继承的运行时快照正态化为 V2 。 更新已公布的旧文件 部署服务器退役前的捆绑 。 按键的退出创建可能重放一个传输 失败的尝试相同; 付款错误永远不会回落到 V1. `funnel-sdk.contract.test.ts` 获取电线合同,而 `funnel-sdk.http.test.ts` 练习真正的回回转 HTTP 和签名上传 .

`FunnelSdkHttpError` 与外观一起导出,使消费者可以缩小 错误而不导入运输内部。 它的字段和重放语义 定义在 [公共 SDK 参考](https://npmcn.com/package/apps/docs/funnel-sdk/public-api.md#retryable-responses)。 。 。 .

## 会话 API 结构

`apiService` 保持13种公共方法和4种公共类型的出口。 没错 也是一种简单的函数对象,在 `services/session/`数字 :

-   `bootstrap/`: 验证候选身份,再利用请求范围化的一能键, 拖曳一次,只清除已完成的记录,并映射产生的用户.
-   `users/` 财务报告和审定财务报表 `emailCapture/`: 配置更新和电子邮件抓取,包括 sDK API 先前记录的可选版本寿命周期认可有效载荷 捕获事件有资格产生副作用,并命名为请求/答复 地图员和电子邮件响应验证 .
-   `uploads/`: 将原始文件委托给 SDK 签名的上传, 然后验证 ; 本地对象 URL 仅仅是无键倒置.
-   `subscriptions/`:从管理URL中解析身份,验证身份,以及 打给SDK 永远不要以存储的会话身份取代缺失的链接 .
-   `identity.ts` 财务报告和审定财务报表 `bootstrap/idempotency.ts`: 拥有会话存储力学.
-   `ping/transport.ts`: 拥有同源,最优的ping及其错误处理.

这些是用例文件夹,而不是另一个工作流程或数据层. 继续请求和 响应映射器纯度:通过运行时模式/修改,而不是读取 映射函数内部的浏览器配置 。 SDK请求仍然通过 `funnelSdkService`;只有同源ping拥有单独的HTTP边界. 在持久性之前验证电子邮件/名称。 保存失败的靴子夹 用于明确重试的密钥,绝不在不确定的写入中添加自动重试.

取出前会话测试仍为不变的行为基线. 会议 边界测试保护外观和基础设施所有权; 真正的回路 测试 roottrap/ profile/ 电子邮件、 只使用 URL 的订阅管理, 明确 靴子夹重试,二进制通过两个API外观上传.

## 储存公约

-   运行时用户 id 保持漏斗扫描 `funnel:<funnelId>:user-id`
-   运行时生成的用户 id 使用 `u_` 前缀
-   paywall 状态通过运行时的助手存储 `fg_state:<funnelId>`
-   开发者重置控件时, 应通过 `clearPaywallStateValue`,包括活漏斗仍然需要时的漏斗提供兼容性密钥

## 工程规则

-   不导入 `@funnelsgrove/payments` 或者说 `@funnelsgrove/analytics` 这里的检查或运输管弦乐.
-   运行时 UI 必须通用并可以复制输入.
-   当 SSR 水合物可能受到影响时,只浏览器值必须在挂载后解决.
-   订阅交接应用程序和通用链接时,即使知道漏斗用户电子邮件 配置模板省略 `{email}`。存储链接从未收到电子邮件,包括不区分大小写 `email` 在配置的 URL 或先触控属性中存在的密钥.
-   漏斗代码不能复制 `useSyncExternalStore`编号 :`popstate` 查询串钩. 使用 `useBrowserLocationSearch`;共享控制器也在后面通知 `history.pushState` 财务报告和审定财务报表 `history.replaceState` 导航.
-   将嵌入式映射集中到 `config/env.config.ts`。 。 。 .
-   V2 退出选择需要要约集, 付款配置, 提供者, 提供者 计划的关键. `runtimeConfigRevisionId` 是可选的,不能打开 ; 部署不会使原未改变的提议无效。 继续 转发为旧的 API 版本提供的修订版。 部署相容性 API在推出SDK调用器之前,忽略了它.

## 构建、测试、发布

```bash
npm run test:run --workspace @funnelsgrove/runtime
npm run build --workspace @funnelsgrove/runtime
npm publish --workspace @funnelsgrove/runtime --access public
```

该建筑使产生的相对无害环境管理进口商品正常化,使之明确 `.js` 用于已发布的软件包消费者的文件.

## 供货商的钱

`ProviderMoney` 带有整数 `amountMinor`,已规范化 `currency`,并明确 `minorUnitExponent`。 。 。 . `moneyToMajor` 财务报告和审定财务报表 `formatProviderMoney` 使用此合同而不从当地人那里推断出比例。 提供方适配方拥有特定货币规则. 运行时快照宣布 `moneyContractVersion: 1` 每一个规划的提供者计划都需要有效的资金。 遗产快照保留了明确的标签;缺钱不是假设美元的指示.

### 浏览器提供本地地址

基于语言的要约选择使用浏览器语言,独立于漏斗的内容语言. `useBrowserOfferLocale` 通过水合,然后相匹配 `navigator.language` 准确到其中之一 `OFFER_SET_LOCALES`,地方目录代码(`pt-br` → `pt-BR`· ; `ru-RU` 没有变成 `ru`) (中文(简体) ). 其他语言解决漏斗默认.

已出版的 schema 2 可声明快照 `localeContractVersion: 1`。每套报价随即携带 `locales: null | string[]`; 完全无效。 分配的定价实验优先于明确的地块匹配,然后是指定的活动全地默认. V1不会回到任意的第一组. 未知版本, 缺少地语域和无效的默认失败验证 。 未转换快照保留了后遗症适配器.

支持的来源文物包括: `funnel.runtime-capabilities.json` 与支持的资金, 地方和国家合同版本.

### 游客提供国

访问国在浏览器语言之前选择“ 提供集” . `useVisitorOfferCountry(enabled)` 通过水合待决 `enabled` (使用时 `offerSetsTargetCountries(config.offerSets)`它读了主机的 `<meta name="fg-visitor-country">` 从私人文档中获取,否则请求未标记 `/api/visitor-country` 每页决定一次 `OFFER_SET_COUNTRIES` 代码,或改为 `null` 失败后,未指定代码或2秒超时。 没有以国家为目标的报价,它决心 `null` 没有要求。 过 `country` 选择,连同 `locale`;在测试支付模式下, `?country=XX` 超过QA.

显示快照 `countryContractVersion: 1` 携带 `countries: null | string[]` 在每套提议中,都有一个例外。 选择顺序是指定定价实验,明确的国家,明确的地方,然后是默认. 出版物以不可改变的元数据记录该声明。 本地化的运行时间更新和重试需要该版本的接收;仅更改要约设置并不能部署漏斗.

## 常见问题

### @funnelsgrove/runtime 是什么？

共享漏斗运行时间合同和助手\.

### 如何安装 @funnelsgrove/runtime？

在项目目录运行 npm install @funnelsgrove/runtime，或使用 pnpm add / yarn add / bun add。

### @funnelsgrove/runtime 支持 TypeScript 吗？

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

### @funnelsgrove/runtime 支持 ESM 还是 CommonJS？

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

### @funnelsgrove/runtime 可以商用吗？

@funnelsgrove/runtime 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @funnelsgrove/runtime 的下载量有多少？

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

### @funnelsgrove/runtime 还在维护吗？

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