# @fluid-tools/build-infrastructure 中文文档

规范地址：https://npmcn.com/package/%40fluid-tools/build-infrastructure/

版本：0\.68\.0
npm 元数据更新时间：2026-10-15T19:08:56.386Z
中文译文更新时间：2026-11-15T02:36:33.197Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：297 kB，72 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：17 个
- 首次发布：2025-02-11T01:18:29.560Z
- 最新版本发布：2026-10-15T19:08:56.190Z
- 近 30 天下载量：3371（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 8 个）

## 中文简介

Fluid 建设基础设施

## 安装

```sh
npm install @fluid-tools/build-infrastructure
```

也可以使用：`pnpm add @fluid-tools/build-infrastructure`、`yarn add @fluid-tools/build-infrastructure`、`bun add @fluid-tools/build-infrastructure`

## README

# @fluid-tools/建设-基础设施

此软件包包含跨多个构建工具包使用的类型和帮助器功能,包括 `@fluidframework/build-tools` 财务报告和审定财务报表 `@fluid-tools/build-cli`。 。 。 .

本套件的主要目的是提供一种将 npm 套件组织成称为放出组的共同方式 组合,并利用 npm, 纱线等软件包管理器提供的工作空间功能来管理 整个建设项目的软件包之间的相互依存关系。 然后它提供 API 来选择、过滤和与这些 软件包组合.

## API 概览

API是围绕四个关键类型构建的,这四个类型构成了等级: `IBuildProject`, (中文(简体) ), `IWorkspace`, (中文(简体) ), `IReleaseGroup`,以及 `IPackage`。为本文件的目的,“建设项目”、“工作空间”、“释放组”和“包装”等术语 一般是指这些类型.

概念上,a **建设项目** 是将 npm 软件包组织成组用于版本、发布和依赖性的一种方法 管理层。 建设项目可以包含多个 **工作空间**,每个可能包含一个或多个 **释放组**。 。 。 .

### 建设项目

API的主要入口是: `IBuildProject` 类型。 一个构建项目可以包含多个工作空间并发布 组合。 工作空间和发布组都代表了在repo中组织软件包的方式,但其目的和 函数不同.

### 工作空间

工作空间一般是由包管理器(npm,纱线,pnpm等)提供的一个特性. 工作空间定义 _物理布局_ 里面的包裹 里面的包裹 工作空间根植于特定文件夹,并使用配置 在该文件夹中确定它包含什么软件包。 使用的配置是包管理器特有的.

工作空间也是安装和管理依赖关系的边界. 当您为 a 安装依赖时 软件包在工作空间中,将安装工作空间中所有软件包的所有依赖。 在一个工作空间里,它是 将多个软件包连接起来,这样它们就可以互相依赖,这微不足道。 这个 `IWorkspace` 类型是一个薄薄的包装,上面是 这些软件包管理器特性 .

重要的是,这一一揽子方案并不试图重新实施工作空间本身提供的任何特征。 用户是 除了构建项目配置外,预计还会配置其软件包管理器的工作空间特性.

一个构建项目将只装入由软件包管理器的工作空间特性所识别的软件包. 也就是说,任何包裹 未配置为工作空间部分的回波对于使用构建项目的工具来说是看不见的.

### 释放组

虽然工作空间管理软件包的依赖性和物理布局,但发行组侧重于软件包组 这是 _版本并一起发布_。释放组总是工作空间的一个子集,必须至少包含 一个包裹. **释放组不能跨越多个工作空间.**

> \[大 工作空间 _必须_ 至少有一个释放组,所有软件包必须是释放组的一部分.

> \[注\] 在v0版本的构建工具中,发布组和工作空间有1:1的关系. 对比而言,与类型 这里定义在构建-基础设施中,工作空间可以包含多个释放组.

### 软件包

软件包是建筑基础设施中最低层的实体. 一个软件包 _必须_ 既是释放组的一部分,也是释放组的一部分 工作空间,以便用建筑基础设施管理。 一般来说,开发者应该倾向于使用发布组 - 最终只是一组包 - 与单个包合作.

### "独立包"

在v0版本的建设工具中,我们有一个概念: _独立软件包_: 不属于释放内容的软件包 组合并独立释放. **这一概念已不复存在。 只有释放组.** 包裹 独立释放可以是单包工作空间(和释放组)的一部分,也可以是其中的一部分 另一个更大的工作空间, 包含在一个单包释放组.

## 特征

### Git 重播能力

构建项目通常包含在一个 Git 存储器内,一些功能预计将在 Git 内使用 仓库。 需要执行 Git 操作的特性可以同步取回 SimpleGit 实例 `IBuildProject.getGitRepository` API (英语). 如果建设项目不在Git Repo范围内 那这个电话就会发出 `NotInGitRepository` 但打电话者应妥善处理的除外。 如果他们不这样做, 例外是它 清楚发生了什么.

> \[注\]
> 
> 这种设计解决了建设工具v0的一个主要问题,即代码常常假设它是 运行在 Git repo 中。 这常常是真实的,一些特征能够而且应该只在这种背景下起作用,但 执行试图盲目地加载 Git 功能,并在 Git 上下文之外彻底失败。 与 `IBuildProject`Git的整合比较松散 API更清楚地说明 假设是不安全的 吉特雷波的存在.

### 软件包选择和过滤 API

这个 `IBuildProject` 对象提供对工作空间、发布组及其组成包的访问,但人们往往想要 可以在 repo 中的所有软件包的子集上运行。 为支持这项工作,建设基础设施提供选择和 过滤 API. 软件包可以根据工作空间和发布组等标准选择,清单还可以进一步列出 通过范围或私人/非私人过滤。 可执行内置过滤器未覆盖的高级过滤 使用 `Array.prototype.filter` 的选项.

### 内置命令行工具,以检查项目布局和配置

包含的CLI工具便于检查建设项目的内容和布局. 见 [国家行动倡议 文档](https://npmcn.com/package/%40fluid-tools/build-infrastructure/docs/cli.md) 更多信息.

### 装入旧配置格式

这个 `repoPackages` 流体构建当前使用的配置如果更新, 将加载 `buildProject` 无法配置 发现。 这只用于反相比,不会无限期地维持. 用户应转换为 `buildProject` 何时 也许吧.

## 配置

构建工程的配置存储在repo根的配置文件中. 这可能是其中的一部分 `fluidBuild.config.cjs` 文档中 `buildProject` 属性,或者在命名的独立配置文件中 `buildProject.config.cjs` (或为mjs.

### 示例

以下示例配置了三个工作空间, 演示三个典型类型 - 一个工作空间, 有多个释放 组,包含多个软件包的单一发布组的工作空间,以及包含单个发布的工作空间 包含单个软件包的组.

```js
buildProject: {
  workspaces: {
    // This is the name of the workspace which is how it's referenced in the API. All workspaces in a build project must
    // have a unique name.
    "client": {
      // This workspace is rooted at the root of the Git repo.
      directory: ".",
      releaseGroups: {
        // This key is the name of the release group. All release groups in a build project must have a unique name.
        client: {
          // The include property can contain package names OR package scopes. If
          // a scope is provided, all packages with that scope will be a part of
          // the release group.
          include: [
            // Include all the Fluid Framework scopes and packages except for
            // @fluid-example.
            "@fluidframework",
            "@fluid-experimental",
            "@fluid-internal",
            "@fluid-private",
            "@fluid-tools",
            // This private package is part of the client release group
            "@types/jest-environment-puppeteer"
            "fluid-framework",
          ],
          // A release group can have an OPTIONAL root package. This package
          // is typically private and is similar to the root package for a workspace.
          // This release group root package may be useful to store scripts or other
          // configuration that only applies on the release group,
          rootPackageName: "client-release-group-root",

          // A release group may have an ADO pipeline URL associated with it. This
          // URL is used to provide direct links to the pipeline when running releases.
          adoPipelineUrl:
            "https://dev.azure.com/fluidframework/internal/_build?definitionId=12",
        },
        examples: {
          // This release group contains only the @fluid-example packages.
          include: ["@fluid-example"],
          // Release group root packages are optional but can be useful to store scripts that are tuned to
          // apply to only that release group.
          rootPackageName: "examples-release-group-root",
        },
        // If any packages in the workspace don't match a release group, loading the
        // build project config will throw an error.
      },
    },
    "build-tools": {
      // This workspace is rooted in the build-tools folder. This folder must contain
      // a workspace config. The specific config depends on the package manager being used.
      directory: "./build-tools",
      releaseGroups: {
        // Release groups can have the same name as workspaces, but all release group names
        // must be unique regardless of the workspace they belong to.
        "build-tools": {
          include: [
            // Include all Fluid Framework scopes. Only packages contained in the workspace
            // will be included, so it is safe to use the same scopes in multiple release
            // group definitions as long as they're in different workspaces.
            "@fluidframework",
            "@fluid-example",
            "@fluid-experimental",
            "@fluid-internal",
            "@fluid-private",
            "@fluid-tools",
          ],
          rootPackageName: "build-tools-release-group-root",
          adoPipelineUrl:
            "https://dev.azure.com/fluidframework/internal/_build?definitionId=14",
        },
      },
    },
  },
}
```

### 从配置文件装入构建工程

要装入构建工程,请使用 `loadBuildProject` 函数。 您可以在路径中传递到 Git 寄存器根, 或者如果 不提供,则可以使用离工作目录最近的 Git 寄存器.

此功能将寻找该文件夹中的构建工程配置,并加载工作空间,发布组,以及 软件包相应返回 `IBuildProject` 对象,包括工作空间地图、释放组和软件包 属性.

## 其他 APIs

### 类型警卫

你可以用这个 `isIPackage` 财务报告和审定财务报表 `isIReleaseGroup` 函数来确定对象是否为 `IPackage` 或者说 `IReleaseGroup` 页:1.

### 基础班

这个 `PackageBase` 抽象类可以用作创建自定义的基础类 `IPackage` 课程.

## 杂项改进

### 建设项目可以扎根于任何地方

构建项目根植于其配置文件所在之处, _没有_ 在基特雷波的根部。 有多种流体 在Git repo内重置,虽然这通常只用于测试. 在典型的使用中,每个建筑项目只有一个 Git Repo是必需的。 然而,建设项目确实 _没有_ 需要扎根于 Git repo 的根, 代码不应该 假设构建工程的根与 Git repo 的根相同.

### 更好的测试

现在雷波内部有一个测试项目,是一个功能完备的建设项目. 有基本的单位测试来验证 装入构建项目配置, 包按预期排列 。 这比V0有了巨大的改善 构建工具,其中所有软件包的倒转逻辑实际上都没有经过测试.

也有选择和过滤API的测试.

这种基础设施也为进一步改进测试和测试Fluid的其他新特征奠定了基础 重现。 过去,增加新的特征具有挑战性,因为无法有效检验这些特征. 这应该容易得多了.

## 已知差距

-   对git相关API的测试不足?

## 常见问题

### @fluid-tools/build-infrastructure 是什么？

Fluid 建设基础设施

### 如何安装 @fluid-tools/build-infrastructure？

在项目目录运行 npm install @fluid-tools/build-infrastructure，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 buildProject，可以用 npx buildProject 直接运行。

### @fluid-tools/build-infrastructure 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fluid-tools\_\_build-infrastructure 是否存在。

### @fluid-tools/build-infrastructure 支持 ESM 还是 CommonJS？

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

### @fluid-tools/build-infrastructure 可以商用吗？

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

### @fluid-tools/build-infrastructure 的下载量有多少？

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

### @fluid-tools/build-infrastructure 还在维护吗？

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