@vercel/client 编程式部署客户端：事件流 API 设计、源码实现与版本演进全解析

CLI后端云原生【免费下载链接】vercelDevelop. Preview. Ship.项目地址https://gitcode.com/gh_mirrors/ve/vercel点击查看免费下载vercel/client是 Vercel 官方开源的 Node.js 部署客户端它把「收集文件 → 计算哈希 → 创建部署 → 上传文件 → 轮询状态 → 别名分配」这一整套部署流程封装成一个异步事件流让任何 Node.js 程序都能以纯代码方式完成vercel deploy所做的事。本文以 packages/client/CHANGELOG.md 为骨架结合 packages/client/src 源码与测试用例为你梳理该包的事件驱动 API 用法、关键配置项、底层实现原理以及从 12.x 到 18.x 版本演进中的破坏性变更、新功能与安全加固读完即可在自己的 CI/CD 或工具链中直接使用。一、vercel/client 是什么vercel/client位于本仓库packages/client目录是一个专为「以编程方式向 Vercel 部署」设计的 npm 包。它不依赖交互式 CLI而是通过一个**异步生成器async generator**对外输出事件调用方用for await...of消费事件即可驱动整个部署流程。从 packages/client/package.json 可以看到其运行时依赖集中在构建与路由相关的工作区包上vercel/build-utils、vercel/error-utils、vercel/routing-utils、vercel/microfrontends并引入async-retry重试、async-sema信号量并发控制、tar-fstgz 归档等基础设施。当前版本为 18.2.3engines要求Node.js 20。包对外暴露的入口非常精简见 src/index.tsexport { continueDeployment } from ./continue; export { checkDeploymentStatus } from ./check-deployment-status; export { inspectDeploymentFiles } from ./inspect-deployment-files; export { getVercelIgnore, buildFileTree } from ./utils/index; export const createDeployment buildCreateDeployment(); export * from ./errors; export * from ./types;其中createDeployment是最核心的入口continueDeployment用于手动部署manual deployment的续跑checkDeploymentStatus负责部署状态轮询inspectDeploymentFiles与getVercelIgnore/buildFileTree则暴露了文件收集与忽略规则解析的能力。二、快速上手五分钟跑通一次编程式部署安装与引入npm install vercel/clientconst { createDeployment } require(vercel/client);最小可用示例createDeployment接收两个参数path一个目录路径、单个文件路径或同一层级的多个文件路径组成的数组options包含token必填、可选的teamId以及任意vercel.json合法的部署字段。async function deploy() { let deployment; for await (const event of createDeployment({ token: process.env.TOKEN, path: /Users/me/Code/myproject, })) { if (event.type ready) { deployment event.payload; break; } } return deployment; }完整事件列表README 中给出的事件列表是[ // File events文件事件 hashes-calculated, // 文件哈希计算完成 file-count, // 需要上传的文件数量与进度对象 file-uploaded, // 单个文件上传完成 all-files-uploaded, // 全部文件上传完成 // Deployment events部署事件 created, // 部署已在服务端创建 building, // 进入构建阶段 ready, // 部署就绪 alias-assigned, // 别名已分配 warning, // 警告 error, // 错误 ];而源码 src/utils/index.ts 中维护的EVENTS_ARRAY实际上更完整README 只是子集还包括notice、tip、canceled以及 v1 / v2 Checks 相关事件const EVENTS_ARRAY [ // File events hashes-calculated, file-count, file-uploaded, all-files-uploaded, // Deployment events created, building, ready, alias-assigned, warning, error, notice, tip, canceled, // v1 Checks events checks-registered, checks-completed, checks-running, checks-conclusion-succeeded, checks-conclusion-failed, checks-conclusion-skipped, checks-conclusion-canceled, // v2 Checks events checks-v2-failed, ] as const; export type DeploymentEventType (typeof EVENTS_ARRAY)[number]; export const EVENTS new Set(EVENTS_ARRAY);你也可以在代码中直接导入事件集合做校验import { EVENTS } from vercel/client;三、配置项详解VercelClientOptions 与 DeploymentOptionscreateDeployment的第一个参数类型为VercelClientOptions定义在 src/types.ts。下表汇总了全部字段及其作用字段类型说明tokenstring必填Vercel API Token。缺失时抛token_not_provided错误见 src/create-deployment.tspathstring \| string[]目录 / 文件 / 同级文件数组必须为绝对路径否则抛invalid_pathdebugboolean开启后向 stderr 输出[client-debug]前缀的调试日志见 src/utils/index.tsteamIdstring指定 Team 作用域会拼入 API 查询参数?teamIdapiUrlstring自定义 API 地址默认https://api.vercel.comforceboolean强制部署prebuiltboolean预构建部署模式上传.vercel/output产物而非源码vercelOutputDirstringprebuilt 模式下产物目录缺省时报错见 src/utils/index.tsrootDirectorystring \| null项目根目录相对路径withCacheboolean保留缓存的强制部署userAgentstring自定义 UA默认client-v${pkgVersion}defaultNamestring默认部署名isDirectorybooleanpath 是否为目录由collectDeploymentFiles自动探测见 src/collect-deployment-files.tsskipAutoDetectionConfirmationboolean跳过框架自动检测确认archivetgz归档上传格式目前仅支持tgzVALID_ARCHIVE_FORMATS见 src/types.tsdispatcherFetchDispatcherundici Dispatcher如undici.ProxyAgent用于代理等连接定制projectNamestring项目名用于微前端配置推断bulkRedirectsPathstring \| null批量重定向文件相对项目根目录prebuilt 部署会将其纳入上传manualboolean实验性手动部署模式要求prebuilt: true见 src/create-deployment.tsaliasAssignedSignalAbortSignal当已有部署事件流观察到别名分配时用它中止当前轮询FetchDispatcher是一个极简的 undici Dispatcher 接口抽象src/types.tsexport interface FetchDispatcher { dispatch(options: unknown, handler: unknown): boolean; }第二个参数DeploymentOptionssrc/types.ts会被序列化进创建部署的请求体包括version、regions、routes、cleanUrls、rewrites、redirects、headers、trailingSlash、builds、functions、env、build.env、source、target、name、meta、projectSettings、gitMetadata、actor、autoAssignCustomDomains、customEnvironmentSlugOrId等。其中target的处理逻辑值得注意src/deploy.tstarget preview时直接置为undefined预览部署本就是默认target为其他非production值时会转换为customEnvironmentSlugOrId自定义环境部署。VercelConfig接口src/types.ts还完整覆盖了vercel.json支持的所有顶层字段包括builds、routes、functions、crons、images、proxy、bunVersion、bulkRedirectsPath以及实验性的experimentalServices/experimentalServiceGroups/experimentalServicesV2和正式的services多服务配置。四、源码级解析一次部署请求的完整生命周期createDeployment的实际执行流程在 src/create-deployment.ts 中一目了然const { fileList, filesMap: files } await collectDeploymentFiles(path, clientOptions, debug); if (fileList.length 0) { yield { type: warning, payload: There are no files inside your deployment. }; } yield { type: hashes-calculated, payload: mapToObject(files) }; deploymentOptions.version 2; for await (const event of upload(files, clientOptions, deploymentOptions)) { yield event; }整个链路可以拆成五个阶段1. 文件收集collectDeploymentFilessrc/collect-deployment-files.ts 负责校验 path 为绝对路径目录、单文件或文件数组调用buildFileTreesrc/utils/index.ts递归扫描目录依据.vercelignore/.nowignore规则过滤文件prebuilt 模式下通过.vc-config.json的filePathMap补充引用文件、纳入.vercel/routes.json与微前端配置、bulkRedirectsPath最后按是否archive tgz选择走createTgzFiles归档或hashes逐文件哈希。2. 哈希计算hashessrc/utils/hashes.ts 实现了基于SHA-1的内容寻址普通文件createHash(sha1)计算十六进制摘要符号链接对链接目标字符串本身做哈希超大文件超过MAX_BUFFER_FILE_SIZE 2^31 - 1约 2 GiB时fs.readFile会抛ERR_FS_FILE_TOO_LARGE因此改用hashFile以createReadStream流式计算哈希且不保留内存中的data为后续流式上传做准备哈希去重相同内容的文件合并到同一个DeploymentFile.names数组中同名只传一次。const MAX_BUFFER_FILE_SIZE 2 ** 31 - 1;3. 创建部署deploy → postDeploymentsrc/deploy.ts 中deploy()先生成默认部署名单文件叫file目录取最后一段路径名然后调用postDeployment向/v13/deployments发送 POST 请求。请求体会附带files清单——即prepareFiles()生成的PreparedFile[]文件名、sha、size、mode。这里有一个值得关注的静态内联快速路径src/utils/index.ts当文件集满足「全部是普通文件、全部为.html/.htm/.md后缀、文件数 ≤ 10、总字节 ≤ 5 MB」时shouldInlineStaticFiles返回 true文件内容会以 base64 直接内联进创建请求src/utils/index.ts服务端可走免构建的即时静态部署路径不满足条件时自动回退到常规构建流程。4. 上传缺失文件uploadFiles创建请求若返回missing_filescode 为missing_files客户端拿到缺失的 SHA 清单后进入上传阶段src/upload.ts。上传实现有这些特点并发控制new Sema(50, { capacity: 50 })最多 50 个并发请求重试策略async-retry配置retries: 5, factor: 6, minTimeout: 10对ETIMEDOUT、ECONNREFUSED、ENOTFOUND、ECONNRESET、EAI_FAIL、socket hang up等客户端网络错误重试isClientNetworkError还递归检查 native fetch 的cause失败即取消一旦某个文件遇到非网络错误会 abort 所有进行中的上传abortControllers集合避免无效请求继续消耗带宽大文件流式上传无内存data的大文件用createReadStream(names[0])直接从磁盘流式发送并通过 Transform 计数 chunk 更新UploadProgress.bytesUploadedUploadProgress继承自EventEmittersrc/upload.ts上传成功返回file-uploaded事件全部完成后 yieldall-files-uploaded随后再次调用deploy()正式完成部署创建。5. 状态轮询与收尾第二次deploy()创建成功后进入checkDeploymentStatus见下一节直到ready/alias-assigned/error/checks-v2-failed等终止事件返回。若部署在首次创建响应里就已READY且别名已分配则直接短路返回无需轮询。五、部署状态轮询与容错机制src/check-deployment-status.ts 实现了状态轮询逻辑包含了 CHANGELOG 中多次提到的容错特性1. Retry-After 解析与限流退避parseRetryAfterMssrc/check-deployment-status.ts对三种情况分别处理响应状态行为HTTP 429 / 503读取Retry-After头秒数或 HTTP 日期解析失败时回退默认 5000msHTTP 5xx视为可安全重试等待默认 5000ms其他不重试直接继续等待时长被钳制在[RETRY_DELAY_MIN_MS5000, RETRY_DELAY_MAX_MS60000]区间防止极端Retry-After值导致客户端长时间挂起。2. 随机抖动Jitter防惊群对应 CHANGELOG 17.2.31 的变更每次限流退避都会叠加0 ~ RETRY_DELAY_SKEW_MS(30s)的随机偏移避免多个客户端在同一时刻抢一个限流配额thundering herdconst randomSkewMs Math.floor(RETRY_DELAY_SKEW_MS * Math.random());3. 重试上限CHANGELOG 17.2.14 提到checkDeploymentStatus对 HTTP 429 / 5xx 最多重试 3 次当前源码中为RETRY_COUNT 5后续版本上调配合getPollingDelay见 src/utils/get-polling-delay.ts根据已耗时动态调整轮询间隔。4. 事件流驱动的别名分配优化CHANGELOG 17.6.4 引入了「从 alias-assigned 构建流事件完成部署」的能力当调用方通过aliasAssignedSignal传入一个已收到别名分配事件的 AbortSignal 时sleepUntilAliasAssigned会在信号中止时提前唤醒checkDeploymentStatus随即从事件中恢复出READYalias-assigned状态并直接返回轮询降级为兜底方案src/check-deployment-status.ts。5. Checks 事件透传轮询过程中服务端返回的checksState/checksConclusion会逐一映射为checks-registered、checks-running、checks-completed、checks-conclusion-*事件当 v2 的deployment-alias检查失败时立即产出checks-v2-failed并终止——这正是 CHANGELOG 17.3.0「Deployment Checks 支持」的落地实现让deploy --prod在别名提升前就能发现检查失败。六、版本演进亮点从 12.x 到 18.x 的关键变更CHANGELOG 记录了本包自 12.5.1 至 18.2.3 的全部变更。剔除大量「Updated dependencies」条目后实质性的功能、修复与破坏性变更可按主题归纳如下。破坏性变更Major Changes版本变更13.0.0移除 Node.js 14最低要求提升到 Node.js 1615.0.0移除 Node.js 16 支持16.0.0移除 Node.js 18最低要求提升到 Node.js 20当前engines即 2017.0.0请求 api-deployments 时在客户端 options 中设置prebuilt17.5.16移除已废弃的public字段不再向部署接口发送该字段含--public标志测试 fixtures 与辅助函数同步清理18.0.0从node-fetch迁移到原生fetch删除 CLI bundle 中最后一处url.parse()用法消除了 Node 24 上vercel deploy触发的DEP0169DeprecationWarningagent?: http.Agent选项被替换为dispatcher?: FetchDispatcherundici dispatcher如undici.ProxyAgent。CLI 会自动透传代理感知的 dispatcher因此HTTP_PROXY/HTTPS_PROXY行为对 CLI 用户保持不变14.0.0默认忽略.yarn/cachesplit-tgz成为归档部署的默认方式新功能与能力扩展Node.js Routing Middleware18.2.0通过proxy.entrypoint支持 Node.js 路由中间件入口可用proxy.matcher做可选路径匹配matcher 只能配置在入口源码或vercel.json其中之一对应ProxyConfig类型见 src/types.ts。Rust 项目默认跳过target/18.1.0检测到根目录Cargo.toml时vercel deploy/vercel dev默认忽略target/本地构建产物可达数百 MB服务端会重建并缓存用户可用!/target加回同时加固了vercel dev的本地文件扫描器目录在扫描中途被删除cargo build频繁刷新target/的常见竞态时跳过而非崩溃。实现见 src/utils/index.ts。多服务配置services17.4.3 → 17.6.0services成为多服务项目的正式配置字段experimentalServicesV2保留为废弃的向后兼容别名17.5.0 支持在services中通过显式env配置注入引用其他服务的环境变量17.5.6 则移除了service-ref形态下的顶层env。实验性手动部署17.2.42manual仅支持 prebuilt 部署创建后部署保持INITIALIZING需后续调用continueDeployment继续src/continue.tsCLI 侧配套vercel deploy --prebuilt与deploy continue命令17.2.64 为deploy continue增加了--archive支持。vercel deploy --dry17.6.1不上传、不创建部署仅检查检测到的框架预设与本地部署文件集对非 TTY 消费方输出完整 JSON。bulkRedirectsPath支持目录17.2.58prebuilt 部署中该路径既可以是单文件也可以是目录目录内递归纳入修复了此前目录场景报 No files found at path 的问题路径逃逸解析到项目根之外会被拒绝见 src/utils/index.ts。微前端配置15.2.0 / 15.3.0 / 15.3.1将microfrontends.json/microfrontends.jsonc纳入部署15.2.0未指定rootDirectory时自动推断其位置15.3.0findConfig更名为findMicrofrontendsConfig15.3.1实现基于vercel/microfrontends。框架与运行时支持17.2.0 新增 TanStack Start 框架预设17.1.0 通过vercel.json属性支持 BunbunVersion15.1.0 将 v9 pnpm lockfile 识别为 pnpm 10。API 与事件增强13.2.0 起固定使用 v13 创建部署接口13.3.0 发送customEnvironmentSlugOrId13.4.0 在vc ls [project]展示部署保留策略17.2.37 将检测到的 agent 名作为actor传入部署请求体17.2.5 在部署中包含.vercel/routes.json。默认忽略规则扩充15.1.5 / 14.0.0加入 Yarn PlugnPlay 文件.pnp*、.yarn/cache等默认忽略项完整默认列表见 src/utils/index.ts。安全加固与健壮性修复prebuilt 场景的忽略规则复检18.2.3vercel deploy --prebuilt不再无条件信任.vc-config.json的filePathMap引用。源码路径会重新对照项目的.vercelignore/.nowignore规则解析出部署根目录之外的引用会被拒绝从而防止被篡改或低信任度的构建产物把.env等被忽略文件重新塞回上传集。对应实现见 src/utils/index.ts并有专门 fixtureprebuilt-filepathmap-ignore配套测试。超大文件不再崩溃17.6.2大于 Nodefs.readFile上限约 2 GiB的文件改为流式哈希与流式上传ERR_FS_FILE_TOO_LARGE不再出现CLI 上传进度不再假设所有文件都在内存中当文件仍超过服务端单请求上传上限HTTP 413时CLI 会提示改用--archivetgz分片上传。哈希侧实现见 src/utils/hashes.ts。上传失败级联取消13.4.18任一文件上传失败时取消其他进行中的上传。归档分片13.5.0 / 14.0.0支持将归档部署拆分为多个部分上传并使其成为默认方式split-tgz。错误提示优化13.1.1 为vc deploy --prebuilt缺失文件提供更友好报错含 node_modules 依赖未安装提示见 src/collect-deployment-files.ts13.4.19 在特定部署失败时建议--archive标志。类型与内部重构17.4.0升级到 TypeScript 5.9。17.2.48内部fetch重命名为fetchApi。13.4.10以node-fetch替换zeit/fetch18.0.0 再进一步迁移到原生fetch。13.4.20引入 vitest 作为测试框架并重构避免全局设置最大监听数max listeners。七、测试与验证如何确认客户端行为packages/client/tests下提供了完整的单元与集成测试是对上述行为的直接验证单元测试unit.check-deployment-status.test.ts轮询与 Retry-After 逻辑、unit.get-polling-delay.test.ts轮询间隔、unit.hashes.test.tsSHA-1 哈希与去重、unit.utils.test.ts、unit.vercelignore.test.ts忽略规则、unit.inspect-deployment-files.test.ts、unit.manual-deployment.test.ts手动部署模式。集成测试integration-create-deployment.test.ts、integration-paths.test.ts。测试 fixtures覆盖了nowignore新旧忽略文件冲突、rust-target/rust-target-with-ignoreRust target 跳过、prebuilt-filepathmap-ignorefilePathMap 安全复检、bulk-redirects-path/bulk-redirects-dir批量重定向文件与目录、microfrontend、symlinks、vercelignore-allow-nodemodules等典型场景。在包目录内可直接运行# 单元测试 pnpm vitest-unit # 集成测试 pnpm vitest-e2e # 类型检查 pnpm type-check八、进一步探索想要深入理解vercel/client建议按以下顺序阅读源码src/create-deployment.ts事件流编排入口src/upload.ts并发上传、重试与取消逻辑src/check-deployment-status.ts状态轮询与限流退避src/utils/index.ts文件树构建、忽略规则、fetchApi 封装、静态内联判定src/types.ts全部类型定义VercelClientOptions、Deployment、VercelConfig等src/continue.ts手动部署续跑packages/client/CHANGELOG.md版本演进完整记录packages/client/README.md官方使用文档。如果你是 CLI 使用者该包的行为会以vercel deploy、vercel dev、vercel build等命令的形式透出如果你是工具链开发者直接消费vercel/client的事件流即可把 Vercel 部署能力嵌入自己的发布流水线——从文件收集、哈希去重、限流退避到别名分配所有工程细节都已在此包中处理好。赞分享CLI后端云原生【免费下载链接】vercelDevelop. Preview. Ship.项目地址https://gitcode.com/gh_mirrors/ve/vercel点击查看免费下载相关推荐Huly 服务端客户端库 hcengineering/server-client 深入解析从版本演进到源码实现Huly 服务端客户端库 hcengineering/server client 深入解析从版本演进到源码实现 hcengineering/server后端前端企业应用项目管理即时通讯CRMGradio Python 客户端 gradio_client 演进全解从 0.1.2 到 2.6.1 的 API 客户端设计与版本变迁Gradio Python 客户端 gradio_client 演进全解从 0.1.2 到 2.6.1 的 API 客户端设计与版本变迁 本文以 Gradio前端后端AI 应用Huly 平台账号服务客户端 hcengineering/account-client 源码解析RPC API 能力全景与版本演进Huly 平台账号服务客户端 hcengineering/account client 源码解析RPC API 能力全景与版本演进 hcengineeri后端前端企业应用项目管理即时通讯CRM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考