# @coralogix/protofetch 中文文档

规范地址：https://npmcn.com/package/%40coralogix/protofetch/

版本：0\.1\.22
npm 元数据更新时间：2026-10-29T16:47:25.564Z
中文译文更新时间：2026-11-10T18:36:09.675Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：26.5 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- 首次发布：2025-11-17T12:12:09.708Z
- 最新版本发布：2026-10-29T16:47:25.094Z
- 近 30 天下载量：37210（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Protobuf的源依赖管理工具.

## 安装

```sh
npm install @coralogix/protofetch
```

也可以使用：`pnpm add @coralogix/protofetch`、`yarn add @coralogix/protofetch`、`bun add @coralogix/protofetch`

## README

# 铺垫

![CI](https://github.com/coralogix/protofetch/workflows/CI/badge.svg) [![Apache 2 License License](http://img.shields.io/badge/license-APACHE2-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) [![Crates.io](https://img.shields.io/crates/v/protofetch.svg)](https://crates.io/crates/protofetch) [![npm version](https://img.shields.io/npm/v/@coralogix/protofetch.svg??style=flat)](https://www.npmjs.com/package/@coralogix/protofetch) ![GitHub Stars](https://img.shields.io/github/stars/coralogix/protofetch.svg)

Protobuf文件的源依赖管理工具.

## 动机

如果您广泛使用原生生物作为服务的数据格式,与外界通信或分享你的API, 您需要一个方法为每个服务获取正确的原生文件版本,并且能够依赖特定版本. 服务器和客户端都需要这样做. 没有自动化,它可以很快地变得繁琐,容易出错,而且整体上无法管理.

要使它具有可承受性、可用性和稳定性,就需要工具化,使这项工作自动化并具有可预测性。 这就是Protofetch的目的.

## 为什么是Protofetch?

Protofetch旨在以宣示方式处理原生生物依赖的复杂性. 宣布依赖关系和管理依赖关系是微不足道的.

它让你有能力拥有:

-   依赖特定版本/小时;
-   依靠原生取料的可预见建筑/试验/碳化物;
-   易读取原生生物依赖性的声明性说明;
-   自动获取依赖本身及其过渡性依赖.
-   缓存依赖关系,以便能够在多个项目中共享.

## 路线图

这个项目仍在发展之中,今后可能会有变化. 我们的目标是在发布第一个稳定版本之前至少实现以下目标.

-   [x] 基于 git 标记或分支获取依赖性
-   [x] 通过修订本地缓存依赖性
-   [x] 获取过渡性依赖性
-   [x] 每个受扶养人申报规则
    -   [x] 允许政策
    -   [x] 拒绝政策
    -   [x] 依赖性修剪( 移除) `proto` 不需要的文件)
-   [ ] 防止循环依赖

## 开始

**无 :**

```bash
npm install @coralogix/protofetch
```

**货物 :**

Protofetch也被释放到 [货箱.io](https://crates.io/crates/protofetch),所以如果安装了 Rust 工具链,可以从源代码中构建Protofetch:

```bash
cargo install protofetch
```

**预建二进制 :**

您可以下载预建的二进制 [GitHub 发布](https://github.com/coralogix/protofetch/releases/latest) 页 次.

### 使用量

```sh
# Fetch proto sources, updating the lock file if needed.
protofetch fetch

# Verify the lock file, and fetch proto sources. Useful for CI.
protofetch fetch --locked

# Validate dependencies against their source repositories and reconcile the lock file.
protofetch lock

# Update all locked dependencies.
protofetch update

# Update only selected dependencies.
protofetch update module-a module-b

# Update one dependency to an exact commit.
protofetch update module-a --precise abc123
```

`fetch` 使用不与源寄存器联系的缓存锁定承诺 。 它会回收 需要时缺少依赖关系. `lock` 财务报告和审定财务报表 `update` 刷新远程校对并验证 分支和修订限制,即使承诺被缓存. `lock` 保持现有 有锁的,如果有效; `update` 为所有或选定的依赖选择新承诺.

## Protofetch模块

使用前缀的每个服务需要使用模块描述符 `toml` 格式. 此描述符默认为 `protofetch.toml` 并位于服务库的根. 这一点是可以改变的,但令人十分沮丧.

| 外地 | 类型 | 需求 | 说明 |
| --- | :-- | :-- | :-- |
| 名称 | 字符串 | 强制性 | 定义模块的名称 |
| 说明 | 字符串 | 可选 | 模块说明 |
| 依赖关系 | \[依赖 | 可选 | 要获取的依赖性 |

### 依赖性格式

| 外地 | 类型 | 需求 | 说明 | 示例 |
| --- | :-- | :-- | :-- | :-- |
| url 密码 | 字符串 | 强制性 | 用于检查 protobuf 文件的仓库地址 | `"github.com/coralogix/cx-api-users/"` |
| 订正 | 字符串 | 可选 | 修改后退出, 可以是标记版本或承诺散列 | `v0.2` |
| 分支 | 布尔 | 可选 | 要退职的分行, 获取最后的承诺 | `feature/v2` |
| 协议 | 字符串 | 可选 | 要使用的协议 : \[sh, https\] | `ssh` |
| 允许政策 | \[打 | 可选 | 允许政策规则(`*` 开头或结尾匹配任意目录深度) | `"/prefix/*"`, (中文(简体) ), `"*/subpath/*"`, (中文(简体) ), `"/path/to/file.proto"` |
| 否定政策( d) | \[打 | 可选 | 拒绝政策规则`*` 开头或结尾匹配任意目录深度) | `"/prefix/*"`, (中文(简体) ), `"*/subpath/*"`, (中文(简体) ), `"/path/to/file.proto"` |
| 棱镜 | 嘘 | 可选 | 是否仅通过模块依赖来跟踪原型导入而不是复制 | `true` 编号 : `false` |
| 过渡 | 嘘 | 可选 | 标出此依赖性为过渡性 | `true` 编号 : `false` |
| 内容( b) | \[打 | 可选 | 要导入的子目录 | `["/myservice", "/com/org/client"]` |

若为 `revision` 是一个标签和 `branch` 被设定,标记的承诺必须属于该分支.

若为 `revision` 承诺必须属于 `branch`,或者如果 `branch` 未设置.

### 允许和拒绝政策

模式 `allow_policies` 财务报告和审定财务报表 `deny_policies` 与最近的路径相匹配 `content_roots`。 。 。 .

`allow_policies` 仅适用于它们被定义的依赖性,并描述您想要从依赖性中获取的原始文件. 何时 `prune = false`,只包含匹配的原生文件. 何时 `prune = true`,匹配的原生文件被用作倒转根: 原生文件跟随原生文件 `import` 跨模块依赖关系的语句,可能包括从同一模块导入的额外文件,也可能包括从依赖子树导入的文件.

`deny_policies` 适用于整个依赖子树. 何时 `prune = false`,不包括匹配的原生文件. 何时 `prune = true`,不包括匹配原生文件及其导入树.

### 依赖性循环

Pruning 特性使 protofetch 跟随 proto 文件 `import` 语句而不是只从模块级依赖关系复制文件。 有了螺旋, protoft 从包含的文件开始 `allow_policies`,并按模块依赖性逐一跟踪其进口情况, 并获取每个导入的原始文件。 此 traversal 可能包含来自同一模块的额外文件, 即使 他们没有直接匹配 `allow_policies`,并可能包括从依赖子树导入的原生文件.

### 额外的过渡性依赖

启动 pruning 时, protofetch 在模块依赖树中查找导入的 proto 文件 . 这取决于每个依赖在a/ `protofetch.toml` 文档。 如果有受扶养人 不提供一条, 您仍可使用 pruning 特性, 通过声明额外的依赖性 `transitive = true`。 。 。 . 不直接取出来自过渡依赖的文件 。 它们是作为候选人提供的,只有在 `import` 由被压迫的依赖而来.

### Protofetch 依赖toml 实例

```toml
name = "repository name"
description = "this is a repository"

[dep1]
url = "github.com/org/dep1"
revision = "1.3.0"
prune = true
allow_policies = ["/prefix/*", "*/subpath/*", "/path/to/file.proto"]

[dep2]
url = "github.com/org/dep2"
branch = "feature/v2"

[another-name]
url = "github.com/org/dep3"
revision = "a16f097eab6e64f2b711fd4b977e610791376223"
transitive = true

[scoped-down-dep4]
url = "github.com/org/dep4"
revision = "v1.1"
content_roots = ["/scope/path"]
allow_policies = ["prefix/subpath/scoped_path/*"]
```

## Git 协议

Protofetch 支持使用 Git 仓库访问 `ssh` 或者说 `https`默认情况下, Protofetch 用途 `ssh`。您可以用 `PROTOFETCH_GIT_PROTOCOL` 环境变量.

也可以将协议设置在 `protofetch.toml`,但这只有在 Git 服务器不支持两个协议时才有必要。 否则,最好不要设置这个字段,让用户选择他们喜欢的任何协议.

### SSH 支持

您需要运行一个 SSH 代理, 并加载您的 SSH 密钥 :

```sh
ssh-add ~/.ssh/your-private-key
```

### HTTPS 支持

如果您想要使用 https, 您需要配置 git 来使用 [证书助手](https://git-scm.com/docs/gitcredentials)。 。 。 .

支持 https 当 `2FA` 启用时,您必须生成个人访问符并设定为密码. 以下权限在创建符时已足够 .

![GitHub personal access token](https://npmcn.com/package/%40coralogix/protofetch/readme-images/github-personal-access-token.png)

## 范围降低多API repo

对于支持多个API的回波,但只需要特定的目录,即组合 `content_roots` 财务报告和审定财务报表 `allow_policies` 可以使用.

例如: `dep4` repo包含以下内容:

```sh
dep4
 ├── scope
 │   ├── path1
 │   └── path2
 └── scope2
     └── unrelated
```

我们只需要原始文件 `dep4/scope/path1`时 `path1` 是软件包名称.

```toml
[scoped-down-dep4]
url = "github.com/org/dep4"
revision = "v1.1"
content_roots = ["/scope"]
allow_policies = ["path1/*"]
```

## 常见问题

### @coralogix/protofetch 是什么？

Protobuf的源依赖管理工具\.

### 如何安装 @coralogix/protofetch？

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

### @coralogix/protofetch 支持 TypeScript 吗？

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

### @coralogix/protofetch 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @coralogix/protofetch 需要什么版本的 Node\.js？

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

### @coralogix/protofetch 可以商用吗？

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

### @coralogix/protofetch 的下载量有多少？

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

### @coralogix/protofetch 还在维护吗？

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