# @depot/sdk-node 中文文档 规范地址：https://npmcn.com/package/%40depot/sdk-node/ 版本：2\.3\.1 npm 元数据更新时间：2026-11-04T17:44:49.864Z 中文译文更新时间：2026-11-11T23:15:02.988Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40depot/sdk-node 原文对照：https://npmcn.com/package/%40depot/sdk-node/?lang=original 项目主页：https://github.com/depot/sdk-node 源码仓库：https://github.com/depot/sdk-node ## 关键信息（来自 npm 元数据） - 包体积（解压后）：887 kB，7 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：2 个 - peer 依赖：@bufbuild/protobuf ^2\.16\.0 - 首次发布：2023-02-04T13:21:46.756Z - 最新版本发布：2026-11-04T17:44:49.515Z - 近 30 天下载量：141153（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：16（近 12 个月 3 个） ## 中文简介 Depot API 的节点 SDK ## 安装 ```sh npm install @depot/sdk-node ``` 也可以使用：`pnpm add @depot/sdk-node`、`yarn add @depot/sdk-node`、`bun add @depot/sdk-node` ## README # 为 Node.js 调用 API SDK [![CI](https://github.com/depot/sdk-node/actions/workflows/ci.yml/badge.svg)](https://github.com/depot/sdk-node/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@depot/sdk-node.svg)](https://www.npmjs.com/package/@depot/sdk-node) ![Powered by TypeScript](https://img.shields.io/badge/powered%20by-typescript-blue.svg) 一个节点Js SDK [投币](https://depot.dev/) API (英语). 👉 [**API 文档**](https://buf.build/depot/api) ## 安装 使用 [小时](https://pnpm.io/) 或您最喜欢的软件包管理器 : ```bash pnpm add @depot/sdk-node ``` ## 使用量 Depot API服务在主机上曝光 `depot` 输出。 服务路径与相应的gRPC服务名称相匹配. 设定 `DEPOT_TOKEN` 用于认证请求的环境变量 : ```bash export DEPOT_TOKEN=your-access-token ``` - [`depot.build.v1.BuildService`](https://buf.build/depot/api/docs/main:depot.build.v1#depot.build.v1.BuildService) - [`depot.build.v1.RegistryService`](https://buf.build/depot/api/docs/main:depot.build.v1#depot.build.v1.RegistryService) - [`depot.buildkit.v1.BuildKitService`](https://buf.build/depot/api/docs/main:depot.buildkit.v1#depot.buildkit.v1.BuildKitService) - [`depot.code.v1beta1.CodeService`](https://buf.build/depot/api/docs/main:depot.code.v1beta1#depot.code.v1beta1.CodeService) - [`depot.core.v1.BuildService`](https://buf.build/depot/api/docs/main:depot.core.v1#depot.core.v1.BuildService) - [`depot.core.v1.GithubActionsService`](https://buf.build/depot/api/docs/main:depot.core.v1#depot.core.v1.GithubActionsService) - [`depot.core.v1.ProjectService`](https://buf.build/depot/api/docs/main:depot.core.v1#depot.core.v1.ProjectService) - [`depot.core.v1.UsageService`](https://buf.build/depot/api/docs/main:depot.core.v1#depot.core.v1.UsageService) - [`depot.core.v1.OrganizationService`](https://buf.build/depot/api/docs/main:depot.core.v1#depot.core.v1.OrganizationService) - [`depot.registry.v1beta1.RegistryService`](https://buf.build/depot/api/docs/main:depot.registry.v1beta1#depot.registry.v1beta1.RegistryService) ### 示例 **列出项目 :** ```typescript import {depot} from '@depot/sdk-node' async function example() { const result = await depot.core.v1.ProjectService.listProjects({}) console.log(result.projects) } ``` ### 创建客户端 使用 `createClient()` 明确配置客户端: ```typescript import {createClient} from '@depot/sdk-node' const client = createClient({token: 'your-access-token'}) const result = await client.core.v1.ProjectService.listProjects({}) console.log(result.projects) ``` `createClient()` 接受可选选项 `token` 财务报告和审定财务报表 `baseURL`默认 `https://api.depot.dev` 而不读取环境变量。 如果你遗漏 `token`,在每次需要认证的呼叫中提供授权头. 要给个人打电话使用不同的代号,请通过授权标题: ```typescript const result = await depot.core.v1.ProjectService.listProjects({}, {headers: {Authorization: `Bearer ${token}`}}) ``` ## OIDC信托政策 使用 `core.v1.ProjectService` 带有 **aPI 代号** 管理哪个CI 身份可以认证为 Depot 项目 。 项目符号和只读 组织标志不能授权这些操作. 对于GitLab,使用数字命名空间和项目ID. GitLab 项目 ID 是 与 Depot 项目ID 分离: ```typescript import {createClient} from '@depot/sdk-node' const projects = createClient({token: process.env.DEPOT_TOKEN}).core.v1.ProjectService const projectId = 'your-depot-project-id' const {trustPolicy} = await projects.addTrustPolicy({ projectId, provider: { case: 'gitlab', value: {namespaceId: '12345', projectId: '67890', protectedRefsOnly: true}, }, }) if (!trustPolicy) throw new Error('No trust policy returned') console.log(trustPolicy) // Check the saved settings, especially when adding an existing policy. const page = await projects.listTrustPolicies({projectId, pageSize: 100}) console.log(page.trustPolicies) // When page.nextPageToken is present, pass it as pageToken with the same project/filter. await projects.updateTrustPolicy({ projectId, trustPolicyId: trustPolicy.trustPolicyId, protectedRefsOnly: false, }) ``` `protectedRefsOnly: true` 将 GitLab 认证限制为受保护的 refs . 将新政策设定为默认 `false`增加一项现行政策 保留其保存的限制; 使用 `updateTrustPolicy` 来改变它们. 更新保留省略的字段,同时明确 `false` 禁用选中内容 限制。 GitHub 政策类似的支持 `allowPublicPullRequests`; 该 字段只对 GitHub 有效,并且 `protectedRefsOnly` 仅对 GitLab 有效. API也支持CircleCI和Buildkite政策. 为了取消一项政策,打电话 `removeTrustPolicy({projectId, trustPolicyId})`编辑 [可运行的 GitLab 示例](https://npmcn.com/package/%40depot/sdk-node/examples/gitlab-trust-policy.mjs) 执行一个 每一引用都明确操作。 从此仓库运行 `pnpm run build`, (中文(简体) ), 设定 `DEPOT_TOKEN`,并选择一个操作: ```bash node examples/gitlab-trust-policy.mjs list node examples/gitlab-trust-policy.mjs add true node examples/gitlab-trust-policy.mjs update false node examples/gitlab-trust-policy.mjs remove ``` 该实例列出了所有提供者的一页政策。 传回 `nextPageToken` 作为最后论据 `list` 以获取下一页。 它印着 添加和更新后保存的限制. ## 书记官处保留政策 使用 `depot.registry.v1beta1.RegistryService` 带有 **aPI 代号**。 。 。 . 标志决定了组织;您不需要组织ID或 `x-depot-org` 头曰. 项目令牌和登记册拉出/推出令牌不授权 这些管理层的电话. 设定 `repository` 转到仓库路径, 如 `team/app`,没有注册主机 或组织前缀。 使用 `**` 组织违约政策。 供应 完全是一个正整数策略 : `keepCount` 或者说 `keepDays`编辑 `enabled` 字段不是一个禁用开关:删除一个明确的策略,调用 `deleteRetentionPolicy`。 。 。 . ```typescript import {createClient} from '@depot/sdk-node' const registry = createClient({token: process.env.DEPOT_TOKEN}).registry.v1beta1.RegistryService // Keep the most recent 10 images for this repository. await registry.upsertRetentionPolicy({repository: 'team/app', enabled: true, keepCount: 10}) const {policy} = await registry.getRetentionPolicy({repository: 'team/app'}) // policy is undefined when this scope has no explicit policy. // Alternatively, set a time-based organization default. await registry.upsertRetentionPolicy({repository: '**', enabled: true, keepDays: 30}) // Remove only the explicit repository policy; an inherited policy may still apply. await registry.deleteRetentionPolicy({repository: 'team/app'}) ``` `getRetentionPolicy` 阅读关于所请求范围的明确政策,而不是 有效的继承政策。 删除 `**` 取消明确的组织 默认。 删除策略不会删除寄存器或其图像和 不恢复已被保留删除的图像. 这个 [可运行示例](https://npmcn.com/package/%40depot/sdk-node/examples/registry-retention.mjs) 执行一次操作 在一个时候。 从此寄存器中创建 SDK `pnpm run build`设置 `DEPOT_TOKEN`,并选择一个操作: ```bash node examples/registry-retention.mjs get team/app node examples/registry-retention.mjs keep-count team/app 10 node examples/registry-retention.mjs keep-days '**' 30 node examples/registry-retention.mjs delete team/app ``` ## 测试 使用 `pnpm run fmt:check` (氧化物), `pnpm run lint` (牛津岛),和 `pnpm run type-check` 用于源码检查。 运行 `pnpm run package:check` 用于构建和验证所打包的 带有 Publint 和类型错误的软件包 . 见 [释放](https://npmcn.com/package/%40depot/sdk-node/docs/releases.md) npm设置, 预发, 和批准. 运行 `pnpm test` 建立无害环境管理和通用JS软件包并运行Vitest套件. 自动测试 `test/` 并使用本地 HTTP/2 无 Depot 证书的端点. 该套房涵盖配置、授权、服务系列化、出错和 通过两个软件包入口取消。 默认客户端配置为 在孤立的节点进程中测试;甚至默认的API URL也会被本地重定向. 这个 `src/manual-smoke.ts` 脚本是针对活API的单独手工烟雾测试 并且被排除在自动发现之外. ## 许可证 麻省理工学院执照,见 `LICENSE`。 。 。 . ## 使用分析 `depot.core.v1.UsageAnalyticsService` 显示协调世界时的每日使用序列并标注 产品/项目/存储/工作流程细目。 这些方法需要部署API 服务支助;旧部署返回 `Unimplemented`。 。 。 . 见 [使用分析指南](https://depot.dev/docs/api/usage-analysis) 涵盖范围,单位, 滤波器 发光和新鲜度 合同由 [仓库/原型](https://github.com/depot/proto)。 。 。 . `pnpm run generate` 重新生成 SDK 最近出版的 `buf.build/depot/api` 合同。 MCP 消耗此 SDK 通过 aPI 存储器 `@depot/sdk-node` 软件包依赖. 有组织标志 `DEPOT_TOKEN`,使用下列方法比较等长周期: ```sh node examples/usage-compare.mjs 2026-10-01T00:00:00Z 2026-10-08T00:00:00Z 2026-10-15T00:00:00Z owner/repo ``` 示例跟随每页,比较稳定的工作流程密钥,保存未属性 用法,并返回 vCPU 分钟的三角洲 。 它不估计发票金额或发出通知. ## 常见问题 ### @depot/sdk-node 是什么？ Depot API 的节点 SDK ### 如何安装 @depot/sdk-node？ 在项目目录运行 npm install @depot/sdk-node，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@bufbuild/protobuf（^2\.16\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @depot/sdk-node 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @depot/sdk-node 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @depot/sdk-node 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @depot/sdk-node 可以商用吗？ @depot/sdk-node 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @depot/sdk-node 的下载量有多少？ 根据 npm 官方下载统计，@depot/sdk-node 在 2026/10/12 – 2026/11/10 这 30 天内被下载 141,153 次，日均约 4,705 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @depot/sdk-node 还在维护吗？ 最新版本 2\.3\.1 发布于 2026/11/05（7 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 3 个；首次发布于 2023/02/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。