# @gqlts/runtime 中文文档

规范地址：https://npmcn.com/package/%40gqlts/runtime/

版本：3\.4\.2
npm 元数据更新时间：2026-06-01T01:22:30.353Z
中文译文更新时间：2026-11-17T19:08:44.525Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gqlts/runtime
原文对照：https://npmcn.com/package/%40gqlts/runtime/?lang=original
项目主页：https://gqlts.vercel.app/
源码仓库：https://github.com/meabed/gqlts

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

- 包体积（解压后）：239 kB，106 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：graphql \*
- 首次发布：2022-05-29T03:18:40.989Z
- 最新版本发布：2026-06-01T01:22:30.228Z
- 近 30 天下载量：4498（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：503（近 12 个月 7 个）

## 中文简介

Gqlts 运行时客户端

## 安装

```sh
npm install @gqlts/runtime
```

也可以使用：`pnpm add @gqlts/runtime`、`yarn add @gqlts/runtime`、`bun add @gqlts/runtime`

## README

  
  
![](https://gqlts.vercel.app/banner.jpg)  
  

### 类型安全 Graphql 查询构建器

#### 以类型验证方式写入 Graphql 查询,并使用电池自动完成

  
  

[![CI](https://github.com/meabed/gqlts/actions/workflows/ci.yml/badge.svg)](https://github.com/meabed/gqlts/actions/workflows/ci.yml) [![RELEASE](https://github.com/meabed/gqlts/actions/workflows/release.yml/badge.svg)](https://github.com/meabed/gqlts/actions/workflows/release.yml)

### @gqlts/ cli (英语)

[![Latest NPM version](https://img.shields.io/npm/v/@gqlts/cli/latest.svg?label=latest)](https://www.npmjs.com/package/@gqlts/cli) [![Beta NPM version](https://img.shields.io/npm/v/@gqlts/cli/beta.svg?label=beta)](https://www.npmjs.com/package/@gqlts/cli) [![Downloads](https://img.shields.io/npm/dm/@gqlts/cli.svg)](https://www.npmjs.com/package/@gqlts/cli) [![UNPKG](https://img.shields.io/badge/UNPKG-CLI%20Files-179BD7.svg)](https://unpkg.com/browse/@gqlts/cli@latest/)

### @ gqlts/ 运行时间

[![Latest NPM version](https://img.shields.io/npm/v/@gqlts/runtime/latest.svg?label=latest)](https://www.npmjs.com/package/@gqlts/runtime) [![Beta NPM version](https://img.shields.io/npm/v/@gqlts/runtime/beta.svg?label=beta)](https://www.npmjs.com/package/@gqlts/runtime) [![Downloads](https://img.shields.io/npm/dm/@gqlts/runtime.svg)](https://www.npmjs.com/package/@gqlts/runtime) [![UNPKG](https://img.shields.io/badge/UNPKG-RUNTIME%20Files-179BD7.svg)](https://unpkg.com/browse/@gqlts/runtime@latest/)

> 此软件包为预留版本 [学名](https://github.com/remorses/genql/)
> 
> 它已经更新, 固定了少数错误, 在最新的软件包中积极添加特性并更新依赖性和代码库

读取 [快速启动引导](https://gqlts.vercel.app/quick-start) 以本地生成客户端.

## 文档

-   [文档网站](https://gqlts.vercel.app/):快速起步,实例,专题报道,以及使用指南.
-   [发展指南](https://npmcn.com/package/%40gqlts/runtime/DEVELOPMENT.md):本地设置,发布工作流程,以及贡献命令.
-   [建筑](https://npmcn.com/package/%40gqlts/runtime/docs/architecture.md):包图,生成流,运行时流,并放出图.
-   [测试](https://npmcn.com/package/%40gqlts/runtime/docs/testing.md):测试矩阵,更改核对表,以及全演示程序.
-   [API 流量](https://npmcn.com/package/%40gqlts/runtime/docs/api-flow.md):今天API行为报道所住的地方.

## **特征**

-   类型完成
-   类型验证
-   轻松地获取类型中的所有字段
-   支持订阅( ws, 图克- ws, 可观察等)
-   已建入文件上传支持
-   Graphql 客户端构建于
-   与任何客户端合作
-   在节点和浏览器中工作
-   建于Axios客户端,并用截取器导出以延伸.
-   对Axios配置的客户端操作支持,如头,超时,取消Token,中止Signal等.
-   支持批量查询
-   一致的响应格式{数据、错误、扩展}

> 在其中查找更多服务器客户端示例 [实例重播](https://github.com/meabed/graphql-examples) 您将找到多个实例, 拥有不同的构建策略、 查询、 突变、 网页订阅等工具 .

## 示例用途

首先生成您的客户端执行

```sh
npm install -D @gqlts/cli # cli to generate the client code
npm install @gqlts/runtime graphql # runtime dependencies
npx gqlts --schema ./schema.graphql --output ./generated
```

对您的软件包管理器使用等效命令 : `pnpm dlx gqlts`, (中文(简体) ), `yarn gqlts`,或 `bunx gqlts` 所有的工作也一样.

那你就用你的客户

```js
import { createClient, everything } from './generated';
const client = createClient();

client
  .query({
    countries: {
      name: true,
      code: true,
      nestedField: {
        ...everything, // same as __scalar: true
      },
    },
  })
  .then(console.log);
```

上面的代码将获取下面的图克l查询

```graphql
query {
  countries {
    name
    code
    nestedField {
      scalarField1
      scalarField2
    }
  }
}
```

## 软件包

此repo包含两个已公布的软件包:

-   `@gqlts/cli`:读取GraphQL schema并生成已输入客户端文件.
-   `@gqlts/runtime`:权力在运行时生成客户端,用于查询,突变,订阅,分批,上传,以及自定义取取用器.

生成的客户端通常包含:

-   `schema.graphql`: 用于生成的图案快照.
-   `schema.ts`:生成了"计划","请求","响应","守卫"等类型.
-   `index.js` 编号 : `index.esm.js`:生成通用JS和无害环境管理客户切入点.
-   `index.d.ts`:生成公开的TypeScript声明.
-   `types.cjs.js` 编号 : `types.esm.js`: 压缩运行时类型映射.
-   `guards.cjs.js` 编号 : `guards.esm.js`: 生成运行时类型守护.

## 发展

用 Bun 从 repo 根安装 :

```sh
bun ci
```

常见命令 :

```sh
bun run buildall
bun run test
bun run typecheck
bun run --cwd website build
./demo-apps/build-and-test.sh
```

运行 `./demo-apps/build-and-test.sh` 在驱动生成器、运行时间、上传、订阅、SDK或Next.js更改之前。 它运行后端演示,SDK生成,独立浏览器捆绑,Next.js dev和生产测试,以及集成测试.

详情见 [发展.md](https://npmcn.com/package/%40gqlts/runtime/DEVELOPMENT.md), (中文(简体) ), [文件/建筑图](https://npmcn.com/package/%40gqlts/runtime/docs/architecture.md),以及 [文件/测试](https://npmcn.com/package/%40gqlts/runtime/docs/testing.md)。 。 。 .

## 释放

Gqlts 使用 `semantic-release` 协调释放 `@gqlts/runtime` 财务报告和审定财务报表 `@gqlts/cli`。 。 。 .

-   `develop` 财务报告和审定财务报表 `beta` 发布 beta 预释像 `x.y.z-beta.n` 改为npm `beta`。 。 。 .
-   `alpha` 发布 alpha 预释像 `x.y.z-alpha.n` 改为npm `alpha`。 。 。 .
-   `master` 财务报告和审定财务报表 `main` 发布稳定的释放,如 `x.y.z` 改为npm `latest`。 。 。 .
-   一个语义上的放出运行计算整个回放的版本.
-   `release:stamp` 将准确的版本写入根,运行时间和CLI显示.
-   `release:publish` 发表 `@gqlts/runtime` 先说 `@gqlts/cli`,两者在同一版本.

有用命令 :

```sh
bun run release:verify
bun run release:dry
bun run release:local 3.5.0-beta.1 --dry-run --tag beta
```

正常流量 :

1.  使用常规承诺. `feat`, (中文(简体) ), `fix`, (中文(简体) ), `perf`, (中文(简体) ), `refactor`,以及 `revert` 创建释放; `docs`, (中文(简体) ), `test`, (中文(简体) ), `ci`, (中文(简体) ), `build`, (中文(简体) ), `style`,以及 `chore` 别.
2.  合并到 `develop` 或者说 `beta` 以发布下一个β.
3.  合并到 `alpha` 以发布下一个 alpha.
4.  合并到 `master` 或者说 `main` 以发布下一个稳定发行.

发布工作流程首先验证,然后让语义-放出印花,构建,标记,创建"GitHub"发布,并从同一种计算版本发布两个npm包.

* * *

## 许可证

这是根据麻省理工学院的许可. [详情见](https://npmcn.com/package/%40gqlts/runtime/LICENSE)

## 常见问题

### @gqlts/runtime 是什么？

Gqlts 运行时客户端

### 如何安装 @gqlts/runtime？

在项目目录运行 npm install @gqlts/runtime，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：graphql（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gqlts/runtime 支持 TypeScript 吗？

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

### @gqlts/runtime 支持 ESM 还是 CommonJS？

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

### @gqlts/runtime 可以商用吗？

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

### @gqlts/runtime 的下载量有多少？

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

### @gqlts/runtime 还在维护吗？

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

