# @bufbuild/protoc-gen-connect-es 中文文档

规范地址：https://npmcn.com/package/%40bufbuild/protoc-gen-connect-es/

版本：0\.13\.0
npm 元数据更新时间：2026-09-16T06:38:32.998Z
中文译文更新时间：2026-11-08T18:27:46.756Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bufbuild/protoc-gen-connect-es
原文对照：https://npmcn.com/package/%40bufbuild/protoc-gen-connect-es/?lang=original
项目主页：https://github.com/connectrpc/connect-es#readme
源码仓库：https://github.com/connectrpc/connect-es

弃用说明：Connect has moved to its own org @connectrpc and has a stable v1\. Run \`npx @connectrpc/connect-migrate@latest\` to update\. See https://github\.com/connectrpc/connect-es/releases/tag/v0\.13\.1 for details\.

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

- 包体积（解压后）：25.9 kB，13 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=16\.0\.0
- 运行依赖：2 个
- peer 依赖：@bufbuild/connect 0\.13\.0，@bufbuild/protoc-gen-es ^1\.2\.1
- 首次发布：2023-02-16T18:54:26.974Z
- 最新版本发布：2023-08-17T16:06:16.811Z
- 近 30 天下载量：17766（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 0 个）

## 中文简介

连接的代码生成器

## 安装

```sh
npm install @bufbuild/protoc-gen-connect-es
```

也可以使用：`pnpm add @bufbuild/protoc-gen-connect-es`、`yarn add @bufbuild/protoc-gen-connect-es`、`bun add @bufbuild/protoc-gen-connect-es`

## README

# @bufbuilding/protoc-gen-connection-es (英语)

Connect 的代码生成器, 用于服务器和客户端的简单库 在 ECMAScript 中,带有 TypeScript 的类型安全。 它生成兼容的代码 浏览器和Node.js.

更多关于连接的信息 [github.com/连接rpc/连接-es](https://github.com/connectrpc/connect-es)。 。 。 .

## 安装

`protoc-gen-connect-es` 是协议缓冲编译器的代码生成器插件, 喜欢 [库夫](https://github.com/bufbuild/buf) 财务报告和审定财务报表 [原型](https://github.com/protocolbuffers/protobuf/releases)。 。 。 . 它从您的协议缓冲计生成客户端和服务器定义,并与 [@ bufbuilt/ protoc- gen- s](https://www.npmjs.com/package/@bufbuild/protoc-gen-es), (中文(简体) ), 用于所有协议缓冲基准类型的代码生成器插件。 这两位的密码 插件生成需要运行时库 [@ bufbuilding/ 连接](https://www.npmjs.com/package/@bufbuild/connect), (中文(简体) ), 财务报告和审定财务报表 [@ bufbuilding/ protobuf](https://www.npmjs.com/package/@bufbuild/protobuf)。 。 。 .

要安装 `buf`,插件及其运行时库,运行:

```shell
npm install --save-dev @bufbuild/buf @bufbuild/protoc-gen-es @bufbuild/protoc-gen-connect-es
npm install @bufbuild/connect @bufbuild/protobuf
```

如果您想从网页浏览器调用 Connect 或 gRPC-web 服务, 请确保安装 [@ bufbuilding/ 连接- web](https://www.npmjs.com/package/@bufbuild/connect-web)如果您也想要服务器, 安装 [@ bufbuilding/ 连接- 节点](https://www.npmjs.com/package/@bufbuild/connect-node), (中文(简体) ), [@ bufbuilding/ 连接- fastify](https://www.npmjs.com/package/@bufbuild/connect-fastify),或 [@ bufbuilding/ 连接- express](https://www.npmjs.com/package/@bufbuild/connect-express)

我们使用对等依赖,以确保代码生成器和运行时库 相互兼容。 注意 npm 自动安装它们, 但是纱线 和pnpm没有.

## 生成代码

### 与buf (英语)

添加新配置文件 `buf.gen.yaml`数字 :

```yaml
# buf.gen.yaml defines a local generation template.
# For details, see https://docs.buf.build/configuration/v1/buf-gen-yaml
version: v1
plugins:
  # This will invoke protoc-gen-es and write output to src/gen
  - plugin: es
    out: src/gen
    opt: target=ts
  # This will invoke protoc-gen-connect-es
  - plugin: connect-es
    out: src/gen
    opt:
      # Add more plugin options here
      - target=ts
```

要生成您项目中所有 protobuf 文件的代码, 只需运行 :

```bash
npx buf generate
```

请注意: `buf` 可以从各种 [投入](https://docs.buf.build/reference/inputs), (中文(简体) ), 不只是本地原生文件。 譬如说, `npx buf generate buf.build/connectrpc/eliza` 生成模块的代码 [连接/ eliza](https://buf.build/connectrpc/eliza) 在布夫斯克马 书记官处.

### 带着原生物

```bash
PATH=$PATH:$(pwd)/node_modules/.bin \
  protoc -I . \
  --es_out src/gen \
  --es_opt target=ts \
  --connect-es_out src/gen \
  --connect-es_opt target=ts \
  a.proto b.proto c.proto
```

请注意,我们正在增加 `node_modules/.bin` 页:1 `$PATH`,以便协议 缓冲编译器可以找到它们. Npm 脚本会自动发生这种情况.

由于线条v2及以上不使用 `node_modules` 目录,您需要 将变量更改一点 :

```bash
PATH=$(dirname $(yarn bin protoc-gen-es)):$(dirname $(yarn bin protoc-gen-connect-es)):$PATH
```

## 插件选项

### `target`

此选项控制插件是否生成 JavaScript, TypeScript, 或类型脚本声明文件.

可能的值 :

-   `target=js` - 生成一个 `_connect.js` 每个文件 `.proto` 输入文件.
-   `target=ts` - 生成一个 `_connect.ts` 每个文件 `.proto` 输入文件.
-   `target=dts` - 生成一个 `_connect.d.ts` 每个文件 `.proto` 输入文件.

可以通过将它们与 `+`,例如 `target=js+dts`。 。 。 .

默认情况下, 我们生成 JavaScript 和 TypeScript 声明文件, 该文件 生成最小的代码大小, 并且与各种代码最相容 捆绑配置. 如果您喜欢生成类型脚本, 请使用 `target=ts`。 。 。 .

### `import_extension=.js`

默认, [原生基因连接](https://www.npmjs.com/package/@bufbuild/protoc-gen-connect-es) (和基于 [@ bufbuilding/ protoplugin (英语)](https://www.npmjs.com/package/@bufbuild/protoplugin)(中文(简体) ) 使用a `.js` 导入路径中的文件扩展名,甚至在TypeScript文件中.

这是不直观的,但必需的 [节点.js中的ECMAScript模块](https://www.typescriptlang.org/docs/handbook/esm-node.html)。 。 。 . 不幸的是,并非所有的捆绑者和工具都赶上了,而德诺 需求 `.ts`。使用此插件选项,可以替换 `.js` 扩展 在带有给定值的导入路径中。 例如,设定

-   `import_extension=none` 删除 `.js` 扩展
-   `import_extension=.ts` 替换 `.js` 扩展名 `.ts`

### `keep_empty_files=true`

默认, [原生基因连接](https://www.npmjs.com/package/@bufbuild/protoc-gen-connect-es) (和基于 [@ bufbuilding/ protoplugin (英语)](https://www.npmjs.com/package/@bufbuild/protoplugin)(中文(简体) ) 从插件输出中删除空文件 。 此选项禁用运行 空文件,以便与 Bazel 和类似文件进行平稳的交互 工具,该工具需要所有输出文件提前宣布. 除非你用Bazel 否则你不可能需要这个选择.

## 生成代码示例

`eliza.proto`

```protobuf
syntax = "proto3";

package connectrpc.eliza.v1;

// ElizaService provides a way to talk to Eliza, a port of the DOCTOR script
// for Joseph Weizenbaum's original ELIZA program. Created in the mid-1960s at
// the MIT Artificial Intelligence Laboratory, ELIZA demonstrates the
// superficiality of human-computer communication. DOCTOR simulates a
// psychotherapist, and is commonly found as an Easter egg in emacs
// distributions.
service ElizaService {
  // Say is a unary RPC. Eliza responds to the prompt with a single sentence.
  rpc Say(SayRequest) returns (SayResponse) {}
}

// SayRequest is a single-sentence request.
message SayRequest {
  string sentence = 1;
}

// SayRequest is a single-sentence response.
message SayResponse {
  string sentence = 1;
}
```

`eliza_connect.ts`

```ts
/**
 * ElizaService provides a way to talk to Eliza, a port of the DOCTOR script
 * for Joseph Weizenbaum's original ELIZA program. Created in the mid-1960s at
 * the MIT Artificial Intelligence Laboratory, ELIZA demonstrates the
 * superficiality of human-computer communication. DOCTOR simulates a
 * psychotherapist, and is commonly found as an Easter egg in emacs
 * distributions.
 *
 * @generated from service connectrpc.eliza.v1.ElizaService
 */
export const ElizaService = {
  typeName: "connectrpc.eliza.v1.ElizaService",
  methods: {
    /**
     * Say is a unary RPC. Eliza responds to the prompt with a single sentence.
     *
     * @generated from rpc connectrpc.eliza.v1.ElizaService.Say
     */
    say: {
      name: "Say",
      I: SayRequest,
      O: SayResponse,
      kind: MethodKind.Unary,
    },
  }
} as const;
```

## 常见问题

### @bufbuild/protoc-gen-connect-es 是什么？

连接的代码生成器注意：该包已被作者标记为弃用——Connect has moved to its own org @connectrpc and has a stable v1\. Run \`npx @connectrpc/connect-migrate@latest\` to update\. See https://github\.com/connectrpc/connect-es/releases/tag/v0\.13\.1 for details\.

### 如何安装 @bufbuild/protoc-gen-connect-es？

在项目目录运行 npm install @bufbuild/protoc-gen-connect-es，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 protoc-gen-connect-es，可以用 npx protoc-gen-connect-es 直接运行。

### @bufbuild/protoc-gen-connect-es 支持 TypeScript 吗？

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

### @bufbuild/protoc-gen-connect-es 需要什么版本的 Node\.js？

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

### @bufbuild/protoc-gen-connect-es 可以商用吗？

@bufbuild/protoc-gen-connect-es 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bufbuild/protoc-gen-connect-es 的下载量有多少？

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

### @bufbuild/protoc-gen-connect-es 还在维护吗？

最新版本 0\.13\.0 发布于 2023/08/18（3 年前）；至今共发布 15 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/02/17。作者已将其标记为弃用，新项目建议寻找替代方案。