# @graphql-tools/external-fragment-loader 中文文档

规范地址：https://npmcn.com/package/%40graphql-tools/external-fragment-loader/

版本：1\.0\.10
npm 元数据更新时间：2026-11-10T01:42:40.380Z
中文译文更新时间：2026-11-16T23:11:37.705Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40graphql-tools/external-fragment-loader
原文对照：https://npmcn.com/package/%40graphql-tools/external-fragment-loader/?lang=original
项目主页：https://github.com/ardatan/graphql-tools#readme
源码仓库：https://github.com/ardatan/graphql-tools

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

- 包体积（解压后）：83.2 kB，19 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：6 个
- peer 依赖：graphql ^16\.0\.0 \|\| ^17\.0\.0
- 首次发布：2026-10-15T11:45:50.990Z
- 最新版本发布：2026-11-10T01:42:40.058Z
- 近 30 天下载量：21648（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：185（近 12 个月 185 个）

## 中文简介

解决外部包中跨包碎片依赖性的图形QL 加载器

## 安装

```sh
npm install @graphql-tools/external-fragment-loader
```

也可以使用：`pnpm add @graphql-tools/external-fragment-loader`、`yarn add @graphql-tools/external-fragment-loader`、`bun add @graphql-tools/external-fragment-loader`

## README

# @graphql-tools/ 外部碎片加载器

通过跟踪直接和中转依存于 `package.json`,只装入软件包所需的外部碎片.

## 安装

```sh
npm install @graphql-tools/external-fragment-loader
```

解析器需要一个目标(消费者)包目录和一个或多个包含 其依赖软件包:

```ts
const options = {
  packageDir: '/path/to/packages/my-app',
  externalPackagesDirs: ['/path/to/packages']
}
```

`packageDir` 财务报告和审定财务报表 `externalPackagesDirs` 应该是绝对的路径。 默认情况下, 加载器扫描 `src` 上述软件包中的目录 `.ts`, (中文(简体) ), `.tsx`, (中文(简体) ), `.js`, (中文(简体) ), `.jsx`, (中文(简体) ), `.graphql`,以及 `.gql` 文档. 这些默认选项可随下列选项而更改: [`options.ts`](https://npmcn.com/package/%40graphql-tools/external-fragment-loader/src/options.ts)。 。 。 .

## 3个API入境点

| 入境点 | 回返 | 用它当 |
| --- | --- | --- |
| 默认导出 | `DocumentNode` (或 `Promise<DocumentNode>` 与 `async: true`(中文(简体) ) | 配置 Codegen 或 GraphQL 工具自定义加载器; 默认使用同步解析器 |
| `ExternalFragmentLoader` | `Source[]` 与 `document`, (中文(简体) ), `rawSDL`,以及 `location` | 使用 `@graphql-tools/load` 在方案方面(可以是合成) |
| `resolveExternalFragments` | 文件元数据,包括 `filePath` 和碎片定义 | 构建文件列表或其他自定义工作流程 |

每个切入点都有一个可适用的同步变体。 同步和同步变体为:

-   `async: true` 编号 : `async: false`
-   `ExternalFragmentLoader.load()` 编号 : `ExternalFragmentLoader.loadSync()`
-   `resolveExternalFragments()` 编号 : `resolveExternalFragmentsSync()`

### 1\. 默认加载器导出(用于GraphQL代码生成器)

默认导出返回一个合并的 `DocumentNode`。这是 GraphQL 最简单的选项 代码生成器, 因为 Codegen 的自定义装入器路径期望一个 `DocumentNode` 或一个 `Source`。 。 。 .

这是一个代码生成样本,用于 `packages/my-package`。脚本来自单曲 树根.

```ts
import { resolve } from 'node:path'
import type { CodegenConfig } from '@graphql-codegen/cli'

const packageDir = resolve('packages/my-package')
const externalPackagesDir = resolve('packages')

const config: CodegenConfig = {
  schema: './schema.graphql',
  documents: ['./packages/my-package/src/**/*.graphql'],
  externalDocuments: [
    {
      // a pointer that triggers the custom loader for the consumer package
      [packageDir]: {
        loader: '@graphql-tools/external-fragment-loader',
        packageDir,
        externalPackagesDirs: [externalPackagesDir],
        async: true // codegen can consume Promise<DocumentNode> directly
      }
    }
  ],
  generates: {
    './packages/my-package/src/__generated__/types.ts': {
      plugins: ['typescript', 'typescript-operations']
    }
  }
}

export default config
```

最多使用一个外部分解指针 `packageDir` 在代码配置中。 这个 加载器返回该包所需的全部外部碎片; 重复指针导致这些碎片 碎片要装入不止一次,并可产生重复的碎片定义。 常规 文档指针仍然可以和单一的外部分解指针一起列出.

默认导出使用同步解析器, 除非 `async: true` 已经设定。 与 `async: true`,这个 返回 a `Promise<DocumentNode>` 并使用同步解析器。 用 Codegen 使用此选项 或同步加载 API; 省略或设置为 `false` 使用时 `loadDocumentsSync`。 。 。 .

### 2\. 基于等级的装载机

使用 `ExternalFragmentLoader` 调用时 `@graphql-tools/load` 直接或当你需要时 个人 `Source` 对象 :

```ts
import { ExternalFragmentLoader } from '@graphql-tools/external-fragment-loader'

const loader = new ExternalFragmentLoader()

const sources = await loader.load('.', {
  packageDir,
  externalPackagesDirs: [externalPackagesDir]
})
```

注册该类 `@graphql-tools/load`传入 `loaders` 指针选项 代表外部碎片文档:

```ts
import { loadDocuments } from '@graphql-tools/load'

const sources = await loadDocuments(['./external-fragments.graphql'], {
  loaders: [loader],
  packageDir,
  externalPackagesDirs: [externalPackagesDir]
})
```

装填器还暴露了 **同步** 方法 :

```ts
const syncSources = loader.loadSync('.', options)
```

每个返回的来源包含解析 `document`匹配时 `rawSDL`,并且提供者的文件 `location`。在向 `@graphql-tools/load`,使用一个外部分解指针 对于正在解决的每个软件包。 装载器不重复重复的单独引用 指针.

### 3\. 直接解决者API

需要外部文件列表或片段元数据而不是一个时使用解析器函数 图QL 工具加载器结果 :

```ts
import {
  resolveExternalFragments,
  resolveExternalFragmentsSync
} from '@graphql-tools/external-fragment-loader'

const files = await resolveExternalFragments(options)
const syncFiles = resolveExternalFragmentsSync(options)
```

结果有这样的形状:

```text
[
  {
    filePath: '/path/to/packages/shared/src/user-fields.graphql',
    packageName: '@example/shared',
    definitions: [{ name: 'UserFields', typeCondition: 'User' }]
  }
]
```

此 API 返回文件元数据, 而不是解析 AST 。 传回 `filePath` 作为代码的值 `documents`编号 :`externalDocuments` 但Codegen会再读一遍 分析这些文件 使用 默认加载器或基于类的加载器,用于重用解析文档.

## AST 地点

`noLocation` 默认为 `true`设置它 `false` 将源位置保留在已解析的碎片上.

和Codegen一样 [`extractAllFieldsToTypesCompact: true`](https://the-guild.dev/graphql/codegen/plugins/typescript/typescript-operations#extractallfieldstotypescompact), (中文(简体) ), 这可能影响类型重复使用相同的选择。 以下示例使用简化名称;准确 输出取决于 Codegen 版本和配置.

```ts
// noLocation: true — both fields reuse the same generated type
type AddressFields = { street: string; city: string }
type QueryResult = {
  primaryAddress: AddressFields
  secondaryAddress: AddressFields
}
```

```ts
// noLocation: false — separate locations can produce separate types with the same shape
type PrimaryAddressFields = { street: string; city: string }
type SecondaryAddressFields = { street: string; city: string }
type QueryResult = {
  primaryAddress: PrimaryAddressFields
  secondaryAddress: SecondaryAddressFields
}
```

## 缓存

包片地图、解析出的来源和 `package.json` 依赖性元数据缓存于 解析器呼叫。 消费者包装图通常不保留,除非消费者包装是 先前作为提供者装入.

当运行装入器时 **监视模式** 例如,在背景中运行 Codegen 时 使用 IDE 使软件包生成的 GraphQL 类型在每次出现时自动重生 文件更改 — 考虑设置以下选项:

-   设定 `invalidateTargetPackageCache: true` 使已缓存的碎片映射无效 `package.json` 指定目标包的依赖性元数据 `packageDir` 在每项决议发出呼吁之前. 这可以防止先前作为提供者被缓存的软件包后来被扫描时出现陈旧数据 作为消费者.
    
-   设定 `cacheTTL` (例如,改为: `10000` 因此,缓存提供者数据最终 过期。 这有助于避免当一个提供者软件包被间接更新时的陈旧数据,例如通过 (单位:千美元) `git merge`,而手表进程仍在运行中.
    

## 使用过滤器

过滤器是可选的前过滤器:在昂贵的依赖扫描和GraphQL之前运行 解析工作。 提前限制软件包名称和文件比分析每个源要快 每个依赖软件包中的文件.

在大型单雷波的基准中,这个装载器是用来绘制的,大约观测时间 削减情况如下(共减少68%):

-   `fileContentFilter`:60%
-   `packageNameFilter`妇女:4%
-   `packageDependencyFilter`妇女:4%

### 按内容过滤文件

使用 `fileContentFilter` 以跳过未包含 GraphQL 的源文件。 文件内容已读取 一次并传递到上游,但文件返回 `false` 不为图QL 解析或提取 文档:

```ts
const options = {
  packageDir,
  externalPackagesDirs,
  fileContentFilter: (content, filePath) => {
    // Keep standalone GraphQL files and match GraphQL tags or magic comments in code files.
    return (
      /\.(graphql|gql)$/.test(filePath) ||
      /\b(?:gql|graphql)\s*`/.test(content) ||
      /\/\*\s*graphql\s*\*\//i.test(content)
    )
  }
}
```

当软件包包含许多类型脚本或JavaScript文件但只包含一个小文件时,这尤其有用 其中数字包含 GraphQL 标记。 文件内容过滤器应足够宽而不排除 自定义图形QL 标记标识符 `pluckConfig`。 。 。 .

### 按名称过滤依赖性包

使用 `packageNameFilter` 限制哪些 `package.json` 依赖被视为提供者。 这个 过滤器在文件扫描前应用于直接和中转依赖名称:

```ts
const options = {
  packageDir,
  externalPackagesDirs,
  packageNameFilter: packageName =>
    packageName.startsWith('my-company-name-') || packageName === 'shared-graphql'
}
```

此过滤器拒绝的软件包不搜索 。 如果在否决中定义了所需的碎片 软件包,解析器报告为未解决.

### 按软件包依赖性过滤

使用 `packageDependencyFilter` 在不影响的情况下跳过不使用 GraphQL 的扫描包 依赖性横跨。 过滤器接收合并 `dependencies` 财务报告和审定财务报表 `devDependencies` 记录 从每个包的 `package.json` 默认,或仅 `dependencies` 何时 `includeDevDependencies` 实值 `false`返回时返回 `boolean`。返回的软件包 `false` 仍然为自己而穿越 过渡性依赖性——它们只是没有被扫描到碎片定义:

```ts
const options = {
  packageDir,
  externalPackagesDirs,
  packageDependencyFilter: deps => '@apollo/client' in deps
}
```

这对大型单体很有用,因为许多软件包不包含GraphQL,而是坐在 消费者和包之间的依赖链。 没有这个过滤器,每个可以到达 软件包得到其源文件被擦去并读取。 只有通过过滤器的软件包 上游被扫描, 而非 GraphQL 中间体仍然在穿行, 这样 GraphQL 包 后面有:

```text
A (consumer) → B (no GraphQL) → C (has GraphQL)
```

## 常见问题

### @graphql-tools/external-fragment-loader 是什么？

解决外部包中跨包碎片依赖性的图形QL 加载器

### 如何安装 @graphql-tools/external-fragment-loader？

在项目目录运行 npm install @graphql-tools/external-fragment-loader，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：graphql（^16\.0\.0 \|\| ^17\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @graphql-tools/external-fragment-loader 支持 TypeScript 吗？

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

### @graphql-tools/external-fragment-loader 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @graphql-tools/external-fragment-loader 需要什么版本的 Node\.js？

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

### @graphql-tools/external-fragment-loader 可以商用吗？

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

### @graphql-tools/external-fragment-loader 的下载量有多少？

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

### @graphql-tools/external-fragment-loader 还在维护吗？

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

