# @fluid-internal/client-utils 中文文档

规范地址：https://npmcn.com/package/%40fluid-internal/client-utils/

版本：3\.12\.0
npm 元数据更新时间：2026-11-10T22:14:44.357Z
中文译文更新时间：2026-11-15T01:38:43.897Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fluid-internal/client-utils
原文对照：https://npmcn.com/package/%40fluid-internal/client-utils/?lang=original
项目主页：https://fluidframework.com/
源码仓库：https://github.com/microsoft/FluidFramework

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

- 包体积（解压后）：425 kB，195 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2023-09-07T20:03:26.937Z
- 最新版本发布：2026-11-10T22:14:44.180Z
- 近 30 天下载量：42202（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：281（近 12 个月 48 个）

## 中文简介

无意在流体框架外使用.

## 安装

```sh
npm install @fluid-internal/client-utils
```

也可以使用：`pnpm add @fluid-internal/client-utils`、`yarn add @fluid-internal/client-utils`、`bun add @fluid-internal/client-utils`

## README

# @ fluid- 内部/ 客户用户

这套软件包的目的是在流体框架Repo, 主要在客户发布组内.

**重要:流体框架将本套件作为实施细节.** **不要把它当作公众的依赖.** **我们不保证这一一揽子计划或其API的稳定.**

## 在此软件包中添加代码

作为一个通用软件包,这个软件包没有很强的特性. 也就是说很容易变成"被倾销" 我们觉得应该共享的代码 但没有明显的家 我们尽量避免把东西丢进 工具包, 这个也不例外 .

新的代码只应在罕见的情况下添加到这个包中. 在大多数情况下,编码最好放在 具有明确身份的软件包(如共享事件基础设施的"事件"软件包)或完全不共享.

## 所需资源

这个包对里面的代码有重要要求.

1.  本套件中的代码应当要求一些外部依赖性. 如果它没有,那么 **核心用途** 软件包 是一个更好的地点.
2.  **所有出口必须指定 `@internal`。 。 。 .** 此代码仅用于流体框架中. **排出 API 的小型事件** 由遗留测试支持使用.
3.  这个包应该 **只包含"执行"代码,而不是类型定义.** 这是最灵活的规则,和 有一些例外。 如果类型是 _仅限_ 当使用此软件包时, 可能还有必要。 不过, 这类类型通常最好放在核心界面或符合目的的包中.

如果您想要添加不符合这些要求的代码,这些其他软件包可能是一个更好的选择:

-   **类型和接口** 应把打算广泛共享的客户发布组放入 **核心接口** 软件包.
-   **零依赖共享代码** 应放入 **核心用途** 软件包.

## 异形码

这一一揽子方案存在的主要原因之一,是提供异构执行 在浏览器和Node.js环境中同时工作的缓冲器和相关公用设备.

我们在这方面的总体战略如下:

-   我们使用 package.json 中的导出映射为浏览器提供不同的切入点(indexBrowser.js) vs. Node.js (index Node.js) (英语).
    
-   因为浏览器生态系统更复杂(捆绑等),我们通过制作 浏览器默认值。 只有Node.js依靠通过导出地图进行再映射.
    
-   我们只是用出口图来解决最初的入站点,从而进一步简化事情。 我们没有 依赖导出地图重新映射模块中的导入。 (基本上,浏览器/节点.js具体 在入口处和从该点开始明确导入浏览器或节点的执行叉 特定文件. )
    

重要的是要意识到的是,我们的CJS支持依赖于复制一个 stub 包. json 将模块类型设置为普通j。 在解决CJS的内部进口时 软件包,模块解析会从 \*.js 文件上行并发现此 stub 软件包.json 。 因为 json 缺少出口图, 内部的进口不会被重新配置.

## 导出报告和林定

目前存在遗留的 API 以及同位素浏览器和 Node.js 支持, 生成和检查API在客户组中是独一无二的. `lib/client-utils.(browser|node).*.d.ts` 文件 用于生产(不包括npm包).

对于本地(开发)构建的浏览器报告,首先生成,然后将Node.js报告核实为 与浏览器相同。 (两套报告使用相同的目标文件. )

软件包脚本 `check:exports:esm:indexBrowser:legacy` 财务报告和审定财务报表 `check:exports:esm:indexNode:legacy` 没有 验证实际出口,但验证遗留的 API 集内标记的一致性.

## 贡献准则

你们可以 [贡献](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) 通过这些方式实现流体框架:

-   回答问题 [GitHub 讨论](https://github.com/microsoft/FluidFramework/discussions)。 。 。 .
-   [提交错误报告](https://github.com/microsoft/FluidFramework/issues) 并且帮助验证修正.
-   审查 [源代码更改](https://github.com/microsoft/FluidFramework/pulls)。 。 。 .
-   [贡献错误修正](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md)。 。 。 .

详细指示改为: [repo 文档](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md)。 。 。 .

本项目遵循 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息,改为: [《行为守则》经常被问到的问题](https://opensource.microsoft.com/codeofconduct/faq/)。 。 。 . 问题或评论,联系 [打开码@ microsoft.com](mailto:opencode@microsoft.com)。 。 。 .

这个项目可能包含微软项目的商标或标志,产品,或服务. 这些商标或标志的使用必须遵循微软 [商标和品牌准则](https://www.microsoft.com/trademarks)。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 帮助

读取 [流体框架文件](https://fluidframework.com/docs/) 用于了解流体框架概念和API.

要求提供文件未载列的资料, [创建问题](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md)。 。 。 .

## 商标

这个项目可能包含微软项目的商标或标志,产品,或服务.

这些商标或标志的使用必须遵循微软的 [商标和品牌准则](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)。 。 。 .

在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 常见问题

### @fluid-internal/client-utils 是什么？

无意在流体框架外使用\.

### 如何安装 @fluid-internal/client-utils？

在项目目录运行 npm install @fluid-internal/client-utils，或使用 pnpm add / yarn add / bun add。

### @fluid-internal/client-utils 支持 TypeScript 吗？

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

### @fluid-internal/client-utils 支持 ESM 还是 CommonJS？

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

### @fluid-internal/client-utils 可以商用吗？

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

### @fluid-internal/client-utils 的下载量有多少？

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

### @fluid-internal/client-utils 还在维护吗？

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