# @apollo/generate-persisted-query-manifest 中文文档

规范地址：https://npmcn.com/package/%40apollo/generate-persisted-query-manifest/

版本：2\.0\.0
npm 元数据更新时间：2026-11-06T08:47:59.583Z
中文译文更新时间：2026-11-06T11:00:22.495Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40apollo/generate-persisted-query-manifest
原文对照：https://npmcn.com/package/%40apollo/generate-persisted-query-manifest/?lang=original
项目主页：https://github.com/apollographql/apollo-utils#readme
源码仓库：https://github.com/apollographql/apollo-utils

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

- 包体积（解压后）：116 kB，14 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.15
- 运行依赖：11 个
- peer 依赖：graphql 14\.x \|\| 15\.x \|\| 16\.x \|\| 17\.x，@apollo/client ^3\.7\.0 \|\| ^4\.0\.0
- 首次发布：2023-05-26T17:20:43.177Z
- 最新版本发布：2026-11-06T08:47:59.300Z
- 近 30 天下载量：391609（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 2 个）

## 中文简介

从一个阿波罗客户端 Web 项目创建 Persisted 查询表

## 安装

```sh
npm install @apollo/generate-persisted-query-manifest
```

也可以使用：`pnpm add @apollo/generate-persisted-query-manifest`、`yarn add @apollo/generate-persisted-query-manifest`、`bun add @apollo/generate-persisted-query-manifest`

## README

# `@apollo/generate-persisted-query-manifest`

`generate-persisted-query-manifest` 是生成工具 [持续查询表](https://www.apollographql.com/docs/graphos/operations/persisted-queries) 来源于阿波罗客户端网络项目的源代码. 它扫描一个寻找GraphQL操作的源代码目录,对操作进行与阿波罗客户端Web运行时所做的相同的转换,并将其编译为持续查询的JSON文件.

(这不是从任意的GraphQL操作创建PQM JSON文件的通用工具:它专门针对阿波罗客户端网络在发送到服务器之前如何转换操作. )

## 设置

首先,安装 `@apollo/generate-persisted-query-manifest` 作为 dev 依赖的软件包 :

```sh
npm install --save-dev @apollo/generate-persisted-query-manifest
```

使用它的 CLI 从您的应用程序中提取询问:

```sh
npx generate-persisted-query-manifest
```

## CLI 配置

要覆盖默认选项, 您可以提供配置文件 。 创建一个 `persisted-query-manifest.config.json` 在您的项目根中的文件.

```json
{
  "documents": [
    "src/**/*.{graphql,gql,js,jsx,ts,tsx}",
    "!**/*.d.ts",
    "!**/*.spec.{js,jsx,ts,tsx}",
    "!**/*.story.{js,jsx,ts,tsx}",
    "!**/*.test.{js,jsx,ts,tsx}"
  ],
  "output": "persisted-query-manifest.json"
}
```

> 注:配置文件是可选的。 上方显示每个选项的默认值 .

如果您想在根以外的目录中定义配置文件, 您可以使用 : `--config` 选项.

```
npx generate-persisted-query-manifest --config path/to/persisted-query-manifest.config.json
```

### 支持的配置文件格式

配置文件可以多种格式提供,并且可以选择前缀为点(`.`) (中文(简体) ). CLI将在这些位置搜索一个配置文件:

-   `.persisted-query-manifest.config.json`
-   `persisted-query-manifest.config.json`
-   `.persisted-query-manifest.config.yml`
-   `persisted-query-manifest.config.yml`
-   `.persisted-query-manifest.config.yaml`
-   `persisted-query-manifest.config.yaml`
-   `.persisted-query-manifest.config.js`
-   `persisted-query-manifest.config.js`
-   `.persisted-query-manifest.config.ts`
-   `persisted-query-manifest.config.ts`
-   `.persisted-query-manifest.config.cjs`
-   `persisted-query-manifest.config.cjs`
-   A 类 `persisted-query-manifest` 键入 `package.json`

## 配置

要自定义 CLI, 请使用您目录根上描述的一种格式创建配置文件 。 如果使用一个 `.js` , (中文(简体) ), `.cjs`,或 `.ts` 配置文件, 您的配置对象必须是默认导出 .

### 类型脚本

如果您将配置文件定义为 TypeScript 文件, 您可以通过导入选项获取自动补全和选项上的文档 `PersistedQueryManifestConfig` 从包中键入.

```ts
// persisted-query-manifest.config.ts
import { PersistedQueryManifestConfig } from "@apollo/generate-persisted-query-manifest";

const config: PersistedQueryManifestConfig = {
  // options
};

export default config;
```

### 选项

-   `documents` - 说吧 `string | string[]`

告诉CLI去哪里找你的文件 您可以使用 glob 模式来决定查找位置 。 前缀图案 `!` 忽略用于忽略测试或故事书故事中可能定义的询问的路径.

路径相对于当前工作目录进行解释,而不是配置文件的目录. 我们建议永远跑 `generate-persisted-query-manifest` 通过一个 `npm run` 脚本,用包含的目录运行命令 `package.json` 作为当前目录.

默认 :

```json
[
  "src/**/*.{graphql,gql,js,jsx,ts,tsx}",
  "!**/*.d.ts",
  "!**/*.spec.{js,jsx,ts,tsx}",
  "!**/*.story.{js,jsx,ts,tsx}",
  "!**/*.test.{js,jsx,ts,tsx}"
]
```

#### 使用 GraphQL 编码源文件的情况持续存在

[图QL 编码源](https://the-guild.dev/graphql/codegen) 是一个流行的代码 用于 GraphQL 的生成工具。 您可以使用 GraphQL 编码源 [持续 文档](https://the-guild.dev/graphql/codegen/plugins/presets/preset-client#persisted-documents) 特性为 `generate-persisted-query-manifest` 通过提供 `documents` 选项 `fromGraphQLCodegenPersistedDocuments` 此套件导出的工具值 。 由于 GraphQL Codegen 已经为您做了大量的工作, 这有助于防止文件系统翻转来解析 GraphQL 文档 .

```ts
import type { PersistedQueryManifestConfig } from "@apollo/generate-persisted-query-manifest";
import { fromGraphQLCodegenPersistedDocuments } from "@apollo/generate-persisted-query-manifest";

const config: PersistedQueryManifestConfig = {
  documents: fromGraphQLCodegenPersistedDocuments(
    "./src/gql/persisted-documents.json",
  ),
};

export default config;
```

> 注:需要通过这个软件包运行这些文件,以确保阿波罗客户端发送给服务器的GraphQL文档与清单中的文件相匹配。 虽然GraphQL Codegen所坚持的文档变换意在与阿波罗客户端相似,但有些细微的差别可能会妨碍正确使用阿波罗坚持的询问. 这也确保了与阿波罗客户端引入的任何可能改变GraphQL文档输出的未来变换的向前兼容.

-   `output` - 说吧 `string`

告诉CLI你在哪里写清单文件 路径相对于当前工作目录进行解释.

默认 : `persisted-query-manifest.json`

-   `createOperationId` - 函数 `(query: string, options: CreateOperationIdOptions) => string`

自定义函数允许您自定义 `id` 用于查询操作。 默认情况下,将使用查询字符串的 SHA 256 散列来生成 `id`。只有在您的配置文件使用一个 `.js`, (中文(简体) ), `.cjs` 或者说 `.ts` 扩展名.

当您使用此选项时, 您无法使用 `generatePersistedQueryIdsAtRuntime` 函数从 `@apollo/persisted-query-lists` 在客户端中,因为该函数假设您正在使用默认的ID生成(身体的SHA256散列). 与 `generatePersistedQueryIdsFromManifest`。 。 。 .

```ts
interface CreateOperationIdOptions {
  /**
   * The name of the operation.
   */
  operationName: string;

  /**
   * The type of operation.
   */
  type: "query" | "mutation" | "subscription";

  /**
   * Helper function that returns the default generated ID for the operation.
   */
  createDefaultId: () => string;
}
```

这里的一个例子是,对命名的操作使用一个 Base 64 编码字符串 `TestOperation`,但将默认生成的ID用于所有其他人.

```ts
import { Buffer } from "node:buffer";

const config = {
  createOperationId(query, { operationName, type, createDefaultId }) {
    switch (operationName) {
      case "TestOperation":
        return Buffer.from(query).toString("base64");
      default:
        return createDefaultId();
    }
  },
};
```

-   `documentTransform` - 说吧 `DocumentTransform`

一个 `@apollo/client` `DocumentTransform` 实例,用于转换 GraphQL 文档,然后将其保存到清单中。 如果您通过一个选项, 请使用此选项 `documentTransform` 选项.

更多信息见阿波罗客户端 [文件转换](https://www.apollographql.com/docs/react/data/document-transforms) 文档.

> 注: 只有在使用3.8.0或以上的阿波罗客户端时,此特性才可用.

```ts
import { DocumentTransform } from "@apollo/client/core";

const config = {
  // Inlined for this example, but ideally this should use the same instance
  // that is passed to your Apollo Client instance
  documentTransform: new DocumentTransform((document) => {
    // ... transform the document

    return transformedDocument;
  }),
};
```

-   `addTypename`数字 : `boolean`

是否添加 `__typename` 字段到操作中的选择设置。 默认为真; 如果您也通过, 您应该将此设定为虚假 `addTypename: false` 给您的 `InMemoryCache` 在您的应用程序中构建器.

> \[注\] 如果您在不使用阿波罗客户端的代码库上使用此工具,此选项将会有所帮助. 请注意,此工具不支持此使用例 .

注意通过的能力 `addTypename: false` 将不会使用 Aporo 客户端 v4 支持 .

## 常见问题

### @apollo/generate-persisted-query-manifest 是什么？

从一个阿波罗客户端 Web 项目创建 Persisted 查询表

### 如何安装 @apollo/generate-persisted-query-manifest？

在项目目录运行 npm install @apollo/generate-persisted-query-manifest，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：graphql（14\.x \|\| 15\.x \|\| 16\.x \|\| 17\.x）、@apollo/client（^3\.7\.0 \|\| ^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 generate-persisted-query-manifest，可以用 npx generate-persisted-query-manifest 直接运行。

### @apollo/generate-persisted-query-manifest 支持 TypeScript 吗？

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

### @apollo/generate-persisted-query-manifest 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @apollo/generate-persisted-query-manifest 需要什么版本的 Node\.js？

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

### @apollo/generate-persisted-query-manifest 可以商用吗？

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

### @apollo/generate-persisted-query-manifest 的下载量有多少？

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

### @apollo/generate-persisted-query-manifest 还在维护吗？

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