# @apollo/persisted-query-lists 中文文档

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

版本：1\.2\.0
npm 元数据更新时间：2026-11-06T08:49:09.032Z
中文译文更新时间：2026-11-06T10:59:48.945Z
软件包许可：MIT

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

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

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

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

## 中文简介

支持阿波罗客户端 Web 中的 Persisted 查询列表

## 安装

```sh
npm install @apollo/persisted-query-lists
```

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

## README

# `@apollo/persisted-query-lists`

此套件包含与阿波罗图形QL 持续合作的公用设备 查询。 具体来说,这个软件包包含一个 [阿波罗链接](https://www.apollographql.com/docs/react/api/link/introduction) 可用于核实您对清单的持续询问以及 帮助工作 [错误的查询链接](https://www.apollographql.com/docs/react/api/link/persisted-queries)。 。 。 .

这些职能对应于通过持续询问的不同步骤:

-   `createPersistedQueryManifestVerificationLink` 允许您验证您的配置是否正确 `@apollo/generate-persisted-query-manifest` 工具,而不改变应用程序与您的 GraphQL 服务器的通信方式,也不要求您在 GraphOS/ Router 中设置持续查询。 这可以帮助您构建一个部署工作流程,创建(并选择发布)您的运算表.
-   一旦你确信你的清单 是由你的部署基础设施 生成和公布的, 你可以使用 `generatePersistedQueryIdsAtRuntime` 告诉您的应用程序在 GraphQL 请求中而不是在 GraphQL 文档中发送持续查询ID。 虽然您确实需要生成并发布您的到GraphOS的出品单才能正常工作,但如果您使用此机制,您不需要在运行时向客户端提供出品单,所以设置起来可以比 `generatePersistedQueryIdsFromManifest`然而,这需要您的应用程序在运行时计算出SHA256散列.
-   终于,你可以用 `generatePersistedQueryIdsFromManifest` 告诉您的应用程序发送持续查询 ID, 包括直接在您的应用程序中显示。 它使用您的 GraphQL 操作的名称来选择要发送的坚持查询 ID 。 这能比 `generatePersistedQueryIdsAtRuntime` 不要求客户端计算散列.

## 设置

安装软件包 :

```sh
npm install @apollo/persisted-query-lists
```

## 使用量

### `generatePersistedQueryIdsAtRuntime`

帮助函数传递到 [错误的查询链接](https://www.apollographql.com/docs/react/api/link/persisted-queries) 在运行时生成查询散列,而不使用显示文件。 这个 与 Persisted 查询链接的默认行为不同 自动登记持续存在的询问并排序顶级定义 模仿显示文件的行为。 见 [`generatePersistedQueryIdsFromManifest`](https://npmcn.com/package/%40apollo/persisted-query-lists/#readme-generatepersistedqueryidsfrommanifest) 如果您能够将显示的文件生成集成到您的应用程序的构建过程中.

```ts
import { generatePersistedQueryIdsAtRuntime } from "@apollo/persisted-query-lists";
import { createPersistedQueryLink } from "@apollo/client/link/persisted-queries";
import { sha256 } from "crypto-hash";

const persistedQueryLink = createPersistedQueryLink(
  generatePersistedQueryIdsAtRuntime({ sha256 }),
);
```

如果您使用 `createOperationId` 配置选项到 `@apollo/generate-persisted-query-manifest`。 。 。 .

#### 选项

-   `sha256`: SHA-256散列函数. 可以同步或同步 。 提供SHA-256 需要散列函数.

### `generatePersistedQueryIdsFromManifest`

帮助函数传递到 [错误的查询链接](https://www.apollographql.com/docs/react/api/link/persisted-queries) 这将读取您显示的配置, 以获取持续的查询ID . 注意此函数完全忽略 `body` 在清单中 它只是寻找一个行动 `name` 匹配您代码试图执行的操作,并使用它 `id`。 。 。 . 见 [`@apollo/generate-persisted-query-manifest`](https://www.npmjs.com/package/@apollo/generate-persisted-query-manifest) 以学习如何生成显示文件.

```ts
import { generatePersistedQueryIdsFromManifest } from "@apollo/persisted-query-lists";
import { createPersistedQueryLink } from "@apollo/client/link/persisted-queries";

const persistedQueryLink = createPersistedQueryLink(
  generatePersistedQueryIdsFromManifest({
    loadManifest: () => import("./path/to/persisted-query-manifest.json"),
  }),
);
```

#### 选项

-   `loadManifest`: 返回您持续查询表的函数 配置 。 可以是同步或同步. 我们建议使用动态导入到 避免将显示的配置与您的生产建设相捆绑.

### `createPersistedQueryManifestVerificationLink`

一个 [阿波罗链接](https://www.apollographql.com/docs/react/api/link/introduction) 验证发送到您的服务器的查询可以匹配您的清单 配置 。 见 [`@apollo/generate-persisted-query-manifest`](https://www.npmjs.com/package/@apollo/generate-persisted-query-manifest) 以学习如何生成显示文件.

注: 此链接不是一个终止链接,并将通过 链接链.

```ts
import { createPersistedQueryManifestVerificationLink } from "@apollo/persisted-query-lists";

const verificationLink = createPersistedQueryManifestVerificationLink({
  loadManifest: () => import("./path/to/persisted-query-manifest.json"),
  onVerificationFailed: (details) => {
    console.warn(details.reason);
  },
});
```

#### 选项

-   `loadManifest`: 返回您持续查询表的函数 配置 。 可以通过同步或同步。 我们建议使用动态导入到 避免将显示的配置与您的生产建设相捆绑.
    
-   `onVerificationFailed`: 核查时称为函数 运行失败即将发送到服务器 。 每一个错误 发生时将有一个 `reason` 描述失败的属性。 见 关于各种核查失败的详细情况,见下文.
    

#### 核查失败

核查失败将包含 `reason` 属性 失败 。 此外,每次失败都包含一个 [`operation`](https://www.apollographql.com/docs/react/api/link/introduction#the-operation-object) 属性,用于触发验证失败的操作.

以下失败可能发生如下: `reason` 属性 :

-   `AnonymousOperation`: 当 GraphQL 操作不包含时失败 操作名称。 错误的查询不支持匿名操作.
    
-   `MultipleOperations`: 当 GraphQL 文档包含多个时失败 操作。 错误的查询不支持单个的多个操作 文档.
    
-   `NoOperations`: 当 GraphQL 文档不包含操作时失败, 例如碎片定义。 错误的查询不支持 GraphQL 没有操作的文档.
    
-   `UnknownOperation`: 无法匹配 GraphQL 文档时失败 在显示配置中操作。 这是你可能需要的指标 重新生成您的表单配置.
    
-   `OperationMismatch`: 当您在清单中找到操作失败 配置, 匹配操作名称, 但操作机构没有 匹配显示的配置正文。 此错误还提供了 `manifestOperation` 属性是匹配的运算符 配置 。 这份清单可能含有过时的 询问,您可能需要重新生成您的表单配置 .

## 常见问题

### @apollo/persisted-query-lists 是什么？

支持阿波罗客户端 Web 中的 Persisted 查询列表

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

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

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

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

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

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

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

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

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

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

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

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

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

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