Skip to content

运行与日志 ​

run / logs / runs / stop 四个命令对项目与任务通用(任务触发用 task run,见 任务命令)。日志的服务端存储与实时推送机制见 日志与实时跟随。

run:触发项目运行 ​

bash
deploy run my-app                          # 触发并立刻返回 runId
deploy run my-app -f                       # 先补历史日志,再实时跟随到结束
deploy run my-app --wait                   # 不打印日志,只等结果
deploy run my-app -f -e TAG=v1.2.3 --branch main
deploy run my-app --command-id 10 --command-id 11   # 只跑指定命令
deploy run my-app -f --cancel-on-interrupt # Ctrl+C 时取消运行
deploy run my-app --with-dependencies --wait --json # 先构建依赖项目
flag说明
-f, --follow先回放历史日志,再经 WebSocket 实时跟随到运行结束
--wait不打印日志,轮询等待终态后返回
-e K=V触发时覆盖环境变量(可重复;项目需允许 env override)
--branch REF本次运行使用的分支/ref(写入 requestedRef)
--command-id ID只跑指定命令 ID(可重复;ID 来自 project get,update 后会变)
--cancel-on-interruptCtrl+C 时调取消接口并等终态(默认只断开跟随)
--with-dependencies先按依赖顺序构建前置项目,再跑目标项目

不带 -f 也不带 --wait 时立刻返回,--json 输出 {runId, projectKey, buildNumber, status, logUrl, statusUrl}。进入队列不代表部署成功,自动化流程应使用 -f 或 --wait 等待最终结果。

运行 ID 与构建号 ​

收尾摘要里有两个数字,不要混淆:

text
== my-app 构建开始 ==
npm ci
npm run build
构建成功
运行 ID #88(构建号 #13)  success  退出码 0  耗时 8.1s   → CLI 退出码 0
运行 ID #87(构建号 #7)   failed   退出码 1  耗时 2.3s   → CLI 退出码 1
  • 运行 ID(#88)是全局运行 ID:deploy logs / deploy stop / runs list 都用它。
  • 构建号(#13)是项目内第几次部署,即服务端日志头部 === Deploy Run #13 === 里的那个数字。

摘要会同时标出两者;拿不到构建号时退化为只显示 运行 ID #88。摘要里的「退出码」是脚本自身的退出码,箭头后的才是 CLI 进程的退出码。

logs:查看与跟随日志 ​

bash
deploy logs 88                 # 一次性拉全部历史日志(回放完即返回 0)
deploy logs 88 -f              # 实时跟随(断线自动重连 + 按 offset 续拉)
deploy logs 88 --offset 4096   # 从指定字节偏移开始
flag说明
-f, --follow回放历史后实时跟随到运行结束,给出终态摘要
--offset N起始字节偏移(默认 0,从头开始;不能为负)

不带 -f 只回放历史日志并返回 0(即使运行失败);带 -f 会给出终态摘要,运行失败时返回 1。

JSONL 跟随 ​

--json 跟随时 stdout 每行一个 JSON,可逐行解析:日志事件若干行 + 最后一行结果对象:

json
{"data":"构建开始\n","type":"log"}
{"data":"构建成功\n","type":"log"}
{"buildNumber":13,"durationMs":8123,"exitCode":0,"runId":88,"status":"success"}

Ctrl+C 语义 ​

run -f / logs -f 下按 Ctrl+C 默认只断开日志跟随,不取消运行(退出码 0),stderr 会提示可用 deploy logs <runId> -f 再次跟随。只有 deploy run --cancel-on-interrupt 才会先调 POST /runs/{id}/cancel,等终态后按状态返回。--wait 下 Ctrl+C 同样只停止等待(退出码 0),运行继续。中间件操作的跟随也固定为「只断开不取消」。

断线重连 ​

跟随日志时若 HTTP/WebSocket 断开,会退避重连(0.5s 起、5s 封顶,不设次数上限,直到运行结束或 Ctrl+C)。每次重连前先用 GET /runs/{id}/log?offset=<nextOffset> 补齐历史;服务端重发更早内容时按 offset 裁掉重复前缀——不丢日志、不重复刷屏。鉴权失败(401)不会盲目重试。

runs list:运行历史 ​

bash
deploy runs list
deploy runs list --project my-app --status failed --page 2
flag默认说明
--project KEY空按项目 key 过滤
--status S空queued/running/success/failed/canceled/timeout/error
--page N1页码
--page-size N20每页条数(最大 200)

表格列出 RUN(全局运行 ID)/ project / build(构建号)/ 状态 / 触发方式 / 触发人 / 开始时间 / 耗时 / 脚本退出码。项目与任务共用 Run 表,不带过滤时两类运行都会列出;CLI 目前没有按任务过滤的 flag(服务端 API 支持 taskKey,见 认证与通用约定 所在的 API 章)。

stop:取消运行 ​

bash
deploy stop 88        # 幂等取消;cancel 是别名

调 POST /runs/{id}/cancel。接口幂等:运行已结束或已取消时也返回成功。取消后的终态是 canceled,跟随中的 CLI 会以退出码 1 收尾。

退出码的完整定义与脚本判断示例见 输出约定与退出码;常见失败的排查见 故障排查。