vercel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Call the Vercel REST API with

curl + jq

. The user's token is in

$VERCEL_ACCESS_TOKEN

; every call needs

Authorization: Bearer $VERCEL_ACCESS_TOKEN

. Base URL:

https://api.vercel.com

. If the resource is team-scoped, append

?teamId=$VERCEL_TEAM_ID

(set only when the user connected a team token).

Errors come back as

{"error":{"code","message"}}

— show

message

verbatim.

403 forbidden

usually means the token can't see that team/project → re-connect with the right scope.

Helper for the optional team param:

bash

TEAM=""; [ -n "$VERCEL_TEAM_ID" ] && TEAM="?teamId=$VERCEL_TEAM_ID"
AUTH="Authorization: Bearer $VERCEL_ACCESS_TOKEN"

使用

curl + jq

调用Vercel REST API。用户的令牌存储在

$VERCEL_ACCESS_TOKEN

中；每次调用都需要携带

Authorization: Bearer $VERCEL_ACCESS_TOKEN

请求头。基础URL：

https://api.vercel.com

。如果资源属于团队范围，则追加

?teamId=$VERCEL_TEAM_ID

（仅当用户关联了团队令牌时设置）。

错误返回格式为

{"error":{"code","message"}}

——直接展示

message

字段内容。

403 forbidden

通常表示令牌无权限访问该团队/项目→请使用正确权限范围重新关联令牌。

团队参数辅助脚本：

bash

TEAM=""; [ -n "$VERCEL_TEAM_ID" ] && TEAM="?teamId=$VERCEL_TEAM_ID"
AUTH="Authorization: Bearer $VERCEL_ACCESS_TOKEN"

Projects & deployments

项目与部署

bash

undefined

bash

undefined

Projects

查看项目

curl -sS -H "$AUTH" "https://api.vercel.com/v9/projects$TEAM"
| jq '.projects[] | {name, framework, latestProduction: .latestDeployments[0].url}'

Recent deployments (optionally filter by ?projectId=… or &state=ERROR)

最近的部署（可通过?projectId=…或&state=ERROR进行筛选）

curl -sS -H "$AUTH" "https://api.vercel.com/v6/deployments${TEAM:-?}&limit=20"
| jq '.deployments[] | {uid, name, url, state, readyState, created}'

undefined

curl -sS -H "$AUTH" "https://api.vercel.com/v6/deployments${TEAM:-?}&limit=20"
| jq '.deployments[] | {uid, name, url, state, readyState, created}'

undefined

Diagnose a failed build

诊断失败的构建

bash

undefined

bash

undefined

Deployment detail

部署详情

curl -sS -H "$AUTH" "https://api.vercel.com/v13/deployments/DEPLOYMENT_ID${TEAM:+&teamId=$VERCEL_TEAM_ID}"
| jq '{name, url, state: .readyState, error: .errorMessage}'

Build / runtime events (the actual logs)

构建/运行时事件（实际日志）

curl -sS -H "$AUTH" "https://api.vercel.com/v3/deployments/DEPLOYMENT_ID/events${TEAM:+?teamId=$VERCEL_TEAM_ID}"
| jq -r '.[] | select(.type=="stdout" or .type=="stderr") | .payload.text'

undefined

curl -sS -H "$AUTH" "https://api.vercel.com/v3/deployments/DEPLOYMENT_ID/events${TEAM:+?teamId=$VERCEL_TEAM_ID}"
| jq -r '.[] | select(.type=="stdout" or .type=="stderr") | .payload.text'

undefined

Domains & redeploy

域名与重新部署

bash

undefined

bash

undefined

Project domains

项目域名

curl -sS -H "$AUTH" "https://api.vercel.com/v9/projects/PROJECT_ID/domains${TEAM:+?teamId=$VERCEL_TEAM_ID}"
| jq '.domains[] | {name, verified}'


To **redeploy**, POST to `https://api.vercel.com/v13/deployments` with a
`deploymentId` (or git source) body — **confirm with the user first**, it ships
to production.

curl -sS -H "$AUTH" "https://api.vercel.com/v9/projects/PROJECT_ID/domains${TEAM:+?teamId=$VERCEL_TEAM_ID}"
| jq '.domains[] | {name, verified}'


要**重新部署**，请向`https://api.vercel.com/v13/deployments`发送POST请求，请求体携带`deploymentId`（或Git源）——**请先与用户确认**，因为这会部署到生产环境。

Gotchas

注意事项

Never print env-var values. Listing project env vars returns metadata; the
```
/v1/.../env/{id}
```
decrypt route returns secrets — don't call it unless the user explicitly asks, and even then summarize, don't echo.

Deployment

state

readyState

QUEUED → BUILDING → READY | ERROR | CANCELED

```
created
```
/
```
ready
```
are epoch ms — divide by 1000 for human time.

切勿打印环境变量值。列出项目环境变量仅返回元数据；
```
/v1/.../env/{id}
```
解密接口会返回敏感信息——除非用户明确要求，否则不要调用该接口，即使调用也仅需汇总信息，不要直接输出内容。

部署的

state

readyState

状态流程：

QUEUED → BUILDING → READY | ERROR | CANCELED

。

```
created
```
/
```
ready
```
字段为毫秒级时间戳——除以1000即可转换为人类可读时间。