# @bufbuild/protovalidate 中文文档

规范地址：https://npmcn.com/package/%40bufbuild/protovalidate/

版本：1\.3\.0
npm 元数据更新时间：2026-09-16T15:27:34.866Z
中文译文更新时间：2026-11-08T18:24:36.168Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：973 kB，105 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@bufbuild/protobuf ^2\.8\.0
- 首次发布：2025-05-02T11:05:32.237Z
- 最新版本发布：2026-09-16T15:27:34.522Z
- 近 30 天下载量：2495259（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 4 个）

## 中文简介

ECMAScript 协议缓冲验证

## 安装

```sh
npm install @bufbuild/protovalidate
```

也可以使用：`pnpm add @bufbuild/protovalidate`、`yarn add @bufbuild/protovalidate`、`bun add @bufbuild/protovalidate`

## README

# @bufbuilding/protovalidate (英语)

[质子化](https://protovalidate.com/) 提供标准说明,以验证关于消息和字段的共同规则,以及使用 [简历](https://cel.dev/) 写自定义规则。 这是下一代 [原型验证](https://github.com/bufbuild/protoc-gen-validate),是Protobuf唯一被广泛使用的验证库.

通过Protovalidate,您可以使用标准验证规则和自定义验证规则来注释您的Protobuf消息:

```protobuf
syntax = "proto3";

package banking.v1;

import "buf/validate/validate.proto";

message MoneyTransfer {
  string to_account_id = 1 [
    // Standard rule: `to_account_id` must be a UUID.
    (buf.validate.field).string.uuid = true
  ];

  string from_account_id = 2 [
    // Standard rule: `from_account_id` must be a UUID.
    (buf.validate.field).string.uuid = true
  ];

  // Custom rule: `to_account_id` and `from_account_id` can't be the same.
  option (buf.validate.message).cel = {
    id: "to_account_id.not.from_account_id"
    message: "to_account_id and from_account_id should not be the same value"
    expression: "this.to_account_id != this.from_account_id"
  };
}
```

一旦你加进来 `@bufbuild/protovalidate` 对于您的项目,验证很简单:

```ts
import { create } from "@bufbuild/protobuf";
import { createValidator } from "@bufbuild/protovalidate";
import { MoneyTransferSchema } from "./gen/banking_pb";

const transfer = create(MoneyTransferSchema);

const validator = createValidator();
const result = validator.validate(MoneyTransferSchema, transfer);
if (result.kind !== "valid") {
  // Handle failure.
}

```

> \[注\]
> 
> 此版本兼容 [buf. 建设/建设/开发](https://buf.build/bufbuild/protovalidate) 页:1
> 
> 它需要Protobuf运行时间 [@ bufbuilding/ protobuf](https://www.npmjs.com/package/@bufbuild/protobuf)。 。 。 .

## 常见问题

### @bufbuild/protovalidate 是什么？

ECMAScript 协议缓冲验证

### 如何安装 @bufbuild/protovalidate？

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

### @bufbuild/protovalidate 支持 TypeScript 吗？

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

### @bufbuild/protovalidate 支持 ESM 还是 CommonJS？

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

### @bufbuild/protovalidate 可以商用吗？

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

### @bufbuild/protovalidate 的下载量有多少？

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

### @bufbuild/protovalidate 还在维护吗？

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