部署
数据模型
deployments.deploy、deployments.wait 与 deployments.get 返回部署对象，deployments.list 与 deployments.listAll 返回部署对象的集合。deployments.getLog 只返回构建日志地址。字段 | 类型 | 必有 | 说明 |
deploymentId/deployment_id | string/str | 是 | 部署 ID |
projectId/project_id | string/str | 是 | 项目 ID |
env | string/str | 是 | 部署环境的环境标识字符串。内置值为 Production、Preview，也可以是项目中已创建的自定义 Slug，例如 Staging |
status | string/str | 否 | 部署状态。终态取值为 Success、Failed、Timeout、Cancelled 和 Invalid。未到达终态时先为 Pending，随后为 Process |
previewUrl/preview_url | string/str | 否 | 预览链接。可在浏览器中打开的地址仅由 deployments.wait 在 Success 时返回 |
code | number/int、float | 否 | 构建退出码， 0 表示成功 |
createdOn/created_on | string/str | 否 | 创建时间，格式为 ISO 8601 |
modifiedOn/modified_on | string/str | 否 | 修改时间，格式为 ISO 8601 |
deployments.deploy
发起一次部署，待部署内容由
artifact 指定。当 env 精确为 "Preview" 时，SDK 会先查询已有部署来检查是否存在生产环境部署；不存在时在打包制品、上传制品或创建部署之前抛出 ValidationError。默认不等待部署完成。SDK 在完成制品上传并成功创建部署后返回部署 ID、项目 ID 和环境标识，不返回访问地址。传入
wait: true（Python 为 wait=True）时，SDK 会继续等待部署到达终态；也可以在取得部署 ID 后单独调用 deployments.wait。TypeScript 返回 Promise，通过 await 等待结果；Python 调用在等待完成或发生异常后返回或抛出异常。deployments.deploy 仅支持代码来源为直接上传（Provider 为 Upload）的项目。通过 projects.create 创建的项目属于该类型；Git 仓库接入项目不支持通过此方法上传制品部署。参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
artifact | Artifact/dict | 是 | 待部署内容 |
env | string/str | 否 | 部署环境的环境标识字符串，默认 "Production" |
wait | boolean/bool | 否 | 是否等待部署到达终态，默认 false |
timeout | number/float | 否 | 最长等待时间，单位为秒，默认 900 |
pollInterval/poll_interval | number/float | 否 | 轮询间隔，单位为秒，默认 5 |
onUploadProgress/upload_progress | 回调 | 否 | 待部署内容上传完成后触发一次 |
onStatusChange/status_change | 回调 | 否 | 部署状态变更时触发，仅在 wait 为 true 时生效 |
返回值
Promise<Deployment>/dict —— 未等待时只包含 deploymentId、projectId 和 env 三个字段，其余字段不存在。SDK 不会为补齐这些字段而额外发起查询。
示例
const deployment = await makers.deployments.deploy({projectId: "your-project-id",artifact: { files: { "index.html": "<h1>Hello</h1>" } },});console.log(deployment.deploymentId, deployment.env);
deployment = makers.deployments.deploy(project_id="your-project-id",artifact={"files": {"index.html": "<h1>Hello</h1>"}},)print(deployment["deployment_id"], deployment["env"])
待部署内容的形式
artifact 的三种形式互斥，每次调用只能传入其中一种。形式 | 类型 | 说明 |
files | Record<string, string | Uint8Array>/dict[str, str | bytes] | 以键值对形式直接给出文件内容，由 SDK 在内存或临时目录中打包为 Zip。键为相对 POSIX 路径，值支持文本与二进制内容 |
directory | string/str | 本地目录路径，由 SDK 打包为 Zip |
archive | string/str | 本地 Zip 文件路径，通过安全校验后原样上传 |
directory 的常见取值有三类：1. 应用源码所在的项目根目录，例如
"."。2. 静态构建产物目录，例如
"./dist"。该目录的根目录需包含 index.html 作为站点入口，否则访问站点首页时返回 404。SDK 不校验这一点，更多信息请参见 直接上传。3. 本地执行
edgeone makers build 后的产物目录 "./.edgeone"。示例
// 以下四种写法分别对应一种待部署内容，实际调用时只取其中一种await makers.deployments.deploy({projectId: "your-project-id",artifact: { directory: "." },});// artifact: { directory: "./dist", excludePatterns: ["**/*.map"] }// artifact: { directory: "./.edgeone" }// artifact: { archive: "./site.zip" }
# 以下四种写法分别对应一种待部署内容，实际调用时只取其中一种makers.deployments.deploy(project_id="your-project-id",artifact={"directory": "."},)# artifact={"directory": "./dist", "exclude_patterns": ["**/*.map"]}# artifact={"directory": "./.edgeone"}# artifact={"archive": "./site.zip"}
打包规则
传入
directory 时，SDK 按以下规则打包：默认忽略以点开头的文件与目录，
.well-known 和 .edgeone 除外。因此 .git 、.github、.vscode 等目录及 .env 文件同样不会进入压缩包。默认还忽略任意层级的
node_modules、打包根目录下的 .edgeone，以及以 .log、.tmp、.temp、.swp、.swo 结尾的文件和 .DS_Store、Thumbs.db、desktop.ini。打包
"./.edgeone" 时，SDK 保留 node_modules 和以点开头的目录，但仍排除 .git、.env、日志和临时文件等默认忽略项。压缩包按 EdgeOne CLI 的产物布局组织；其他目录则将内容置于压缩包根目录。SDK 不读取
.gitignore，默认忽略项无法关闭，只能通过 excludePatterns 追加。该参数使用相对压缩包根目录的 POSIX glob 语义，不支持以 ! 开头的取反规则。拒绝符号链接。
传入
archive 时，SDK 在上传前校验 Zip 内容，拒绝绝对路径、包含 .. 路径段或反斜杠的路径、规范化后重复的路径，以及符号链接条目。校验通过后原样上传，不重新打包。进度回调
onUploadProgress 在待部署内容上传完成后触发一次。onStatusChange 在首次查询部署状态时以及之后每次状态变更时触发，首次触发时 previousStatus 为空。状态变更回调依赖等待过程，只有传入
wait 为 true 时才会触发。wait 为 false 时 SDK 不查询部署状态，该回调不会被调用，也不会有任何提示。此时如需接收状态变更事件，请把回调传给 deployments.wait。事件 | 字段 |
上传进度事件 | uploadedBytes/uploaded_bytes、totalBytes/total_bytes、completedFiles/completed_files、totalFiles/total_files |
状态变更事件 | deployment（当前部署对象）、previousStatus/previous_status（上一个状态，首次触发时为空） |
注意：
回调抛出异常时不会中断部署。若初始化
Makers 时传入了 logger，异常由 logger 报告；未传入 logger 时该异常被忽略。示例
const result = await makers.deployments.deploy({projectId: "your-project-id",artifact: { files: { "index.html": "<h1>Hello</h1>" } },wait: true,onUploadProgress: (event) => {console.log(event.uploadedBytes, event.totalBytes);},onStatusChange: (event) => {console.log(event.previousStatus, event.deployment.status);},});if (result.status === "Success") {console.log(result.previewUrl);}
result = makers.deployments.deploy(project_id="your-project-id",artifact={"files": {"index.html": "<h1>Hello</h1>"}},wait=True,upload_progress=lambda event: print(event["uploaded_bytes"], event["total_bytes"]),status_change=lambda event: print(event["previous_status"], event["deployment"]["status"]),)if result.get("status") == "Success":print(result.get("preview_url"))
deployments.wait
轮询指定部署直至到达终态。终态取值为
Success、Failed、Timeout、Cancelled 和 Invalid。默认最长等待 15 分钟，每 5 秒轮询一次。部署失败通过返回的
status 表示，不抛出异常。只有本地等待超时或请求本身出错时才抛出异常。参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
deploymentId/deployment_id | string/str | 是 | 部署 ID |
timeout | number/float | 否 | 最长等待时间，单位为秒，默认 900 |
pollInterval/poll_interval | number/float | 否 | 轮询间隔，单位为秒，默认 5 |
onStatusChange/status_change | 回调 | 否 | 部署状态变更时触发 |
返回值
Promise<Deployment>/dict —— status 为终态取值之一。status 为 Success 时，previewUrl 为可访问的站点地址。注意：
等待超时抛出
DeploymentTimeoutError。该异常只表示本地停止等待，Makers 上的部署仍在继续，SDK 不会取消它。示例
const result = await makers.deployments.wait({projectId: "your-project-id",deploymentId: "your-deployment-id",timeout: 900,pollInterval: 5,});if (result.status === "Success") {console.log(result.previewUrl);} else {console.error(result.status, result.code);}
result = makers.deployments.wait(project_id="your-project-id",deployment_id="your-deployment-id",timeout=900,poll_interval=5,)if result.get("status") == "Success":print(result.get("preview_url"))else:print(result.get("status"), result.get("code"))
deployments.get
查询指定部署的当前信息，不等待部署完成。未找到对应部署时，抛出
NotFoundError。参数
参数 | 类型 | 必填 | 说明 |
projectId / project_id | string / str | 是 | 项目 ID |
deploymentId / deployment_id | string / str | 是 | 部署 ID |
返回值
Promise<Deployment> / dict，包含指定部署的信息。示例
const deployment = await makers.deployments.get({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(deployment.deploymentId, deployment.status);
deployment = makers.deployments.get(project_id="your-project-id",deployment_id="your-deployment-id",)print(deployment["deployment_id"], deployment.get("status"))
deployments.list
分页列出指定项目的部署。
参数
参数 | 类型 | 必填 | 说明 |
projectId/project_id | string/str | 是 | 项目 ID |
status | string[]/list[str] | 否 | 按部署状态过滤 |
timeRange/time_range | { start, end }/dict | 否 | 按创建时间过滤，起止时间格式为 ISO 8601 |
repoBranch/repo_branch | string[]/list[str] | 否 | 按代码分支过滤 |
page | number/int | 否 | 页码，从 0 开始，默认 0 |
pageSize/page_size | number/int | 否 | 每页条数，取值范围为 1 至 100，默认 20 |
order.field | string/str | 否 | 排序字段。两种语言的取值不同，TypeScript 为 "createdOn" 或 "modifiedOn"，Python 为 "created_on" 或 "modified_on" |
order.direction | "asc" | "desc" | 否 | 排序方向 |
返回值
Promise<Page<Deployment>>/dict —— 包含 items、page、pageSize / page_size、 total 和 hasNext / has_next 五个字段。页码从 0 开始。示例
const page = await makers.deployments.list({projectId: "your-project-id",page: 0,pageSize: 20,order: { field: "createdOn", direction: "desc" },});console.log(page.total, page.hasNext);for (const deployment of page.items) {console.log(deployment.deploymentId, deployment.status);}
page = makers.deployments.list(project_id="your-project-id",page=0,page_size=20,order={"field": "created_on", "direction": "desc"},)print(page["total"], page["has_next"])for deployment in page["items"]:print(deployment["deployment_id"], deployment["status"])
deployments.listAll / deployments.list_all
遍历指定项目的部署。SDK 从第 0 页开始自动分页查询，并逐项返回部署对象。
参数
参数与
deployments.list 相同，但不接受 page。projectId / project_id 必填；筛选、排序及 pageSize / page_size 参数的含义和默认值与 deployments.list 一致。pageSize / page_size 控制每次查询的条数，不限制遍历的总条数。返回值
TypeScript 返回
AsyncIterable<Deployment>，使用 for await...of 遍历；Python 返回 Iterator[dict[str, Any]]，使用 for 遍历。每次迭代得到一个部署对象。示例
for await (const deployment of makers.deployments.listAll({projectId: "your-project-id",pageSize: 20,order: { field: "createdOn", direction: "desc" },})) {console.log(deployment.deploymentId, deployment.status);}
for deployment in makers.deployments.list_all(project_id="your-project-id",page_size=20,order={"field": "created_on", "direction": "desc"},):print(deployment["deployment_id"], deployment.get("status"))
deployments.getLog / deployments.get_log
获取指定部署的构建日志地址。该方法返回包含日志地址的对象，不下载或返回日志正文。
参数
参数 | 类型 | 必填 | 说明 |
projectId / project_id | string / str | 是 | 项目 ID |
deploymentId / deployment_id | string / str | 是 | 部署 ID |
返回值
Promise<{ logUrl: string }> / dict。日志地址字段在 TypeScript 中为 logUrl，在 Python 中为 log_url；服务端未返回日志地址时，该字段为空字符串。示例
const result = await makers.deployments.getLog({projectId: "your-project-id",deploymentId: "your-deployment-id",});console.log(result.logUrl);
result = makers.deployments.get_log(project_id="your-project-id",deployment_id="your-deployment-id",)print(result["log_url"])