deploy-to-vercel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deploy to Vercel

部署到Vercel

Deploy any project to Vercel. Always deploy as preview (not production) unless the user explicitly asks for production.

The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.

将任意项目部署到Vercel。**始终部署为预览版本（而非生产版本），除非用户明确要求生产部署。

我们的目标是为用户搭建最佳的长期配置：让他们的项目与Vercel关联，支持git推送自动部署。以下所有方法都旨在引导用户逐步接近这一状态。

Step 1: Gather Project State

步骤1：收集项目状态

Run all four checks before deciding which method to use:

bash

undefined

在决定使用哪种部署方法之前，先运行以下四项检查：

bash

undefined

1. Check for a git remote

1. 检查git远程仓库地址

git remote get-url origin 2>/dev/null

2. Check if locally linked to a Vercel project (either file means linked)

2. 检查本地是否已关联Vercel项目（两个文件任意存在即代表已关联

cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

3. Check if the Vercel CLI is installed and authenticated

3. 检查Vercel CLI是否已安装并完成认证

vercel whoami 2>/dev/null

4. List available teams (if authenticated)

4. 列出可用团队（如果已完成认证）

vercel teams list --format json 2>/dev/null

undefined

vercel teams list --format json 2>/dev/null

undefined

Team selection

团队选择

If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.

Pass the team slug via

--scope

on all subsequent CLI commands (

vercel deploy

vercel link

vercel inspect

, etc.):

bash

vercel deploy [path] -y --no-wait --scope <team-slug>

If the project is already linked (

.vercel/project.json

.vercel/repo.json

exists), the

orgId

in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.

About the
.vercel/
directory: A linked project has either:

```
.vercel/project.json
```
— created by
```
vercel link
```
(single project linking). Contains
```
projectId
```
and
```
orgId
```
.
```
.vercel/repo.json
```
— created by
```
vercel link --repo
```
(repo-based linking). Contains
```
orgId
```
,
```
remoteName
```
, and a
```
projects
```
array mapping directories to Vercel project IDs.

Either file means the project is linked. Check for both.

Do NOT use

vercel project inspect

vercel ls

, or

vercel link

to detect state in an unlinked directory — without a

.vercel/

config, they will interactively prompt (or with

--yes

, silently link as a side-effect). Only

vercel whoami

is safe to run anywhere.

如果用户属于多个团队，将所有可用的团队slug以项目符号列表形式呈现，询问用户要部署到哪个团队。用户选定团队后，立即进入下一步，无需额外确认。

在后续所有CLI命令（

vercel deploy

、

vercel link

、

vercel inspect

等）都通过

--scope

参数传入团队slug：

bash

vercel deploy [path] -y --no-wait --scope <team-slug>

如果项目已经完成关联（存在

.vercel/project.json

或

.vercel/repo.json

存在），这些文件中的

orgId

会决定对应的团队，无需再次询问。如果只有一个团队（或仅有个人账户），跳过询问直接使用即可。

**关于

.vercel/

目录：已关联的项目会包含以下任意一个文件：

```
.vercel/project.json
```
— 由
```
vercel link
```
创建（单个项目关联），包含
```
projectId
```
和
```
orgId
```
。
```
.vercel/repo.json
```
— 由
```
vercel link --repo
```
创建（基于代码仓库级关联），包含
```
orgId
```
、
```
remoteName
```
以及映射目录到Vercel项目ID的
```
projects
```
数组。

任意一个文件存在都代表项目已完成关联，两个都需要检查。

请勿在未关联的目录下不要使用

vercel project inspect

、

vercel ls

或

vercel link

来检测状态——如果没有

.vercel/

配置，这些命令会弹出交互式提示（如果加了

--yes

参数，会静默完成关联产生副作用）。只有

vercel whoami

是唯一可以在任意目录安全运行的命令。

Step 2: Choose a Deploy Method

步骤2：选择部署方法

Linked (

.vercel/

exists) + has git remote → Git Push

已关联（存在

.vercel/

+ 有git远程仓库 → Git推送

This is the ideal state. The project is linked and has git integration.

Ask the user before pushing. Never push without explicit approval:

This project is connected to Vercel via git. I can commit and push to
trigger a deployment. Want me to proceed?

Commit and push:
bash
```
git add .
git commit -m "deploy: <description of changes>"
git push
```
Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually
```
main
```
) gets a production deployment.
Retrieve the preview URL. If the CLI is authenticated:
bash
```
sleep 5
vercel ls --format json
```
The JSON output has a
```
deployments
```
array. Find the latest entry — its
```
url
```
field is the preview URL.
If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.

这是理想状态。项目已关联且有git集成。

推送前询问用户，未获得明确批准前不要推送：

该项目已通过git关联到Vercel。我可以提交并推送代码触发部署，是否继续？

**提交并推送：

bash

git add .
git commit -m "deploy: <更改描述>"
git push

Vercel会根据推送的代码自动构建。非生产分支会生成预览部署；生产分支（通常是

main

）会生成生产部署。

获取预览URL。如果CLI已完成认证：

bash

sleep 5
vercel ls --format json

JSON输出中包含

deployments

数组，找到最新的条目，其

url

字段就是预览URL。

如果CLI未认证，告知用户可以查看Vercel控制台或git提供商的提交状态检查获取预览URL。

Linked (

.vercel/

exists) + no git remote →

vercel deploy

已关联（存在

.vercel/

+ 无git远程仓库 →

vercel deploy

The project is linked but there's no git repo. Deploy directly with the CLI.

bash

vercel deploy [path] -y --no-wait

Use

--no-wait

so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:

bash

vercel inspect <deployment-url>

For production deploys (only if user explicitly asks):

bash

vercel deploy [path] --prod -y --no-wait

项目已关联但没有git仓库，用CLI直接部署：

bash

vercel deploy [path] -y --no-wait

使用

--no-wait

参数让CLI立即返回部署URL，而不是阻塞等待构建完成（构建可能需要较长时间）。之后可以用以下命令检查部署状态：

bash

vercel inspect <deployment-url>

生产部署（仅当用户明确要求时使用）：

bash

vercel deploy [path] --prod -y --no-wait

Not linked + CLI is authenticated → Link first, then deploy

未关联 + CLI已认证 → 先关联再部署

The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.

Ask the user which team to deploy to. Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.

Once a team is selected, proceed directly to linking. Tell the user what will happen but do not ask for separate confirmation:

Linking this project to <team name> on Vercel. This will create a Vercel
project to deploy to and enable automatic deployments on future git pushes.

If a git remote exists, use repo-based linking with the selected team scope:
bash
```
vercel link --repo --scope <team-slug>
```
This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates
```
.vercel/repo.json
```
. This is much more reliable than
```
vercel link
```
(without
```
--repo
```
), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
If there is no git remote, fall back to standard linking:
bash
```
vercel link --scope <team-slug>
```
This prompts the user to select or create a project. It creates
```
.vercel/project.json
```
.
Then deploy using the best available method:
- If a git remote exists → commit and push (see git push method above)
- If no git remote →
```
vercel deploy [path] -y --no-wait --scope <team-slug>
```
  , then
```
vercel inspect <url>
```
  to check status

CLI可用但项目还未关联，这是引导用户进入最佳配置的好机会。

**询问用户要部署到哪个团队，将步骤1中获取的团队slug以项目符号列表形式呈现。如果只有一个团队（或仅有个人账户），跳过这一步。
**选定团队后，直接进入关联流程。告知用户即将执行的操作但无需单独确认：

正在将该项目关联到Vercel的<团队名称>。这会创建一个Vercel项目用于部署，同时启用后续git推送自动部署。

**如果存在git远程仓库，使用选定的团队scope进行仓库级关联：

bash

vercel link --repo --scope <team-slug>

该命令会读取git远程仓库URL，匹配已有的从该仓库部署的Vercel项目，创建

.vercel/repo.json

。这比不带

--repo

的

vercel link

更可靠，后者尝试按目录名匹配，当本地文件夹和Vercel项目名称不同时经常失败。

如果没有git远程仓库，回退到标准关联：

bash

vercel link --scope <team-slug>

该命令会提示用户选择或创建一个项目，创建

.vercel/project.json

。

**之后使用最佳可用方法部署：

如果存在git远程仓库 → 提交并推送（参考上文git推送方法）

如果没有git远程仓库 →

vercel deploy [path] -y --no-wait --scope <team-slug>

，之后运行

vercel inspect <url>

检查状态

Not linked + CLI not authenticated → Install, auth, link, deploy

未关联 + CLI未认证 → 安装、认证、关联、部署

The Vercel CLI isn't set up at all.

Install the CLI (if not already installed):
bash
```
npm install -g vercel
```
Authenticate:
bash
```
vercel login
```
The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the no-auth fallback below.
Ask which team to deploy to — present team slugs from
```
vercel teams list --format json
```
as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.

Link the project with the selected team scope (use

--repo

if a git remote exists, plain

vercel link

otherwise):

bash

vercel link --repo --scope <team-slug>   # if git remote exists
vercel link --scope <team-slug>          # if no git remote

Deploy using the best available method (git push if remote exists, otherwise
```
vercel deploy -y --no-wait --scope <team-slug>
```
, then
```
vercel inspect <url>
```
to check status).

Vercel CLI完全未配置。

安装CLI（如果未安装）：

bash

npm install -g vercel

认证：

bash

vercel login

用户在浏览器中完成认证。如果运行在非交互式环境中无法登录，跳转到下文的无认证降级方案。

询问要部署到哪个团队——将
```
vercel teams list --format json
```
返回的团队slug以项目符号列表形式呈现。如果只有一个团队/个人账户，跳过。选定后直接进入下一步。
使用选定的团队scope关联项目（如果存在git远程仓库使用
```
--repo
```
，否则使用普通
```
vercel link
```
：

bash

vercel link --repo --scope <team-slug   # 如果存在git远程仓库
vercel link --scope <team-slug>          # 如果没有git远程仓库

使用最佳可用方法部署（如果有远程仓库用git推送，否则用
```
vercel deploy -y --no-wait --scope <team-slug>
```
，之后
```
vercel inspect <url>
```
检查状态）。

No-Auth Fallback — claude.ai sandbox

无认证降级方案 —— claude.ai沙箱

When to use: Last resort when the CLI can't be installed or authenticated in the claude.ai sandbox. This requires no authentication — it returns a Preview URL (live site) and a Claim URL (transfer to your Vercel account).

bash

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]

Arguments:

```
path
```
- Directory to deploy, or a
```
.tgz
```
file (defaults to current directory)

Examples:

bash

undefined

使用场景：当CLI无法在claude.ai沙箱中安装或认证时的最后备选方案。无需认证，会返回预览URL（可访问的站点）和认领URL（转移到你的Vercel账户）。

bash

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]

参数：

```
path
```
- 要部署的目录，或
```
.tgz
```
文件（默认为当前目录）

示例：

bash

undefined

Deploy current directory

部署当前目录

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh

Deploy specific project

部署指定项目

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project

Deploy existing tarball

部署已有压缩包

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz


The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.

**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."

---

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz


脚本会自动从`package.json`检测框架，打包项目（排除`node_modules`、`.git`、`.env`），上传并等待构建完成。

**告知用户："你的部署已就绪，访问[previewUrl]。在[claimUrl]认领部署以管理你的应用。"

---

No-Auth Fallback — Codex sandbox

无认证降级方案 —— Codex沙箱

When to use: In the Codex sandbox where the CLI may not be authenticated. Codex runs in a sandboxed environment by default — try the CLI first, and fall back to the deploy script if auth fails.

Check whether the Vercel CLI is installed (no escalation needed for this check):
bash
```
command -v vercel
```
If
vercel
is installed, try deploying with the CLI:
bash
```
vercel deploy [path] -y --no-wait
```

If
vercel
is not installed, or the CLI fails with "No existing credentials found", use the fallback script:

bash

skill_dir="<path-to-skill>"

# Deploy current directory
bash "$skill_dir/resources/deploy-codex.sh"

# Deploy specific project
bash "$skill_dir/resources/deploy-codex.sh" /path/to/project

# Deploy existing tarball
bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz

The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with

previewUrl

and

claimUrl

Tell the user: "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."

Escalated network access: Only escalate the actual deploy command if sandboxing blocks the network call (

sandbox_permissions=require_escalated

). Do not escalate the

command -v vercel

check.

**使用场景：**在CLI可能未认证的Codex沙箱环境。Codex默认运行在沙箱环境中，优先尝试CLI，认证失败则回退到部署脚本。

**检查Vercel CLI是否已安装（该检查无需权限升级：

bash

command -v vercel

**如果已安装
```
vercel
```
，尝试用CLI部署：

bash

vercel deploy [path] -y --no-wait

如果未安装
vercel
，或CLI返回"未找到现有凭证，使用降级脚本：

bash

skill_dir="<path-to-skill>"

Agent-Specific Notes

部署当前目录

Claude Code / terminal-based agents

—

You have full shell access. Do NOT use the

/mnt/skills/

path. Follow the decision flow above using the CLI directly.

For the no-auth fallback, run the deploy script from the skill's installed location:

bash

bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]

The path may vary depending on where the user installed the skill.

bash "$skill_dir/resources/deploy-codex.sh"

Sandboxed environments (claude.ai)

部署指定项目

You likely cannot run

vercel login

git push

. Go directly to the no-auth fallback — claude.ai sandbox.

bash "$skill_dir/resources/deploy-codex.sh" /path/to/project

Codex

部署已有压缩包

Codex runs in a sandbox. Check if the CLI is available first, then fall back to the deploy script. Go to the no-auth fallback — Codex sandbox.

bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz


脚本处理框架检测、打包和部署。等待构建完成，返回包含`previewUrl`和`claimUrl`的JSON。

**告知用户："你的部署已就绪，访问[previewUrl]。在[claimUrl]认领部署以管理你的应用。"

**权限升级网络访问：**仅当沙箱限制网络调用（`sandbox_permissions=require_escalated`）时，才对实际部署命令进行权限升级。**不要**对`command -v vercel`检查进行权限升级。

---

Output

Agent专属说明

—

Claude Code / 基于终端的Agent

Always show the user the deployment URL.

Git push: Use
```
vercel ls --format json
```
to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
CLI deploy: Show the URL returned by
```
vercel deploy --no-wait
```
. Use
```
vercel inspect <url>
```
to check build status and report it to the user.

No-auth fallback: Show both the preview URL and the claim URL:

Deployment successful!

Preview URL: https://my-app-abc123.vercel.app
Claim URL:   https://vercel.com/claim-deployment?code=...

View your site at the Preview URL.
To transfer this deployment to your Vercel account, visit the Claim URL.

Do not curl or fetch the deployed URL to verify it works. Just return the link.

你拥有完整的shell访问权限。不要使用

/mnt/skills/

路径。按照上述决策流程直接使用CLI即可。

无认证降级方案时，从skill安装位置运行部署脚本：

bash

bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]

路径可能根据用户安装skill的位置有所不同。

Troubleshooting

沙箱环境（claude.ai）

Network Egress Error (claude.ai)

—

If deployment fails due to network restrictions on claude.ai, tell the user:

Deployment failed due to network restrictions. To fix this:

1. Go to https://claude.ai/settings/capabilities
2. Add *.vercel.com to the allowed domains
3. Try deploying again

你很可能无法运行

vercel login

或

git push

。直接使用无认证降级方案 —— claude.ai沙箱。

Escalated Network Access (Codex / sandboxed environments)

Codex

If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (

sandbox_permissions=require_escalated

). Do not escalate the initial CLI availability check — only escalate the actual deploy command.

Example guidance to the user:

The deploy needs escalated network access to deploy to Vercel. I can rerun
the command with escalated permissions — want me to proceed?

Codex运行在沙箱中。先检查CLI是否可用，之后回退到部署脚本。使用无认证降级方案 —— Codex沙箱。

CLI Auth Failure

输出

vercel login

vercel deploy

fails with authentication errors, fall back to the no-auth deploy script (claude.ai or Codex variant, depending on the environment).

始终向用户展示部署URL。

**Git推送：使用
```
vercel ls --format json
```
查找预览URL。如果CLI未认证，告知用户查看Vercel控制台或提交状态检查获取。
**CLI部署：展示
```
vercel deploy --no-wait
```
返回的URL。使用
```
vercel inspect <url>
```
检查构建状态并告知用户。
**无认证降级方案：同时展示预览URL和认领URL：

部署成功！

预览URL: https://my-app-abc123.vercel.app
认领URL:   https://vercel.com/claim-deployment?code=...

在预览URL查看你的站点。
要将部署转移到你的Vercel账户，访问认领URL即可。

不要curl或fetch部署后的URL验证可用性，仅返回链接即可。

—

故障排查

—

网络出口错误（claude.ai）

—

如果部署因claude.ai的网络限制失败，告知用户：

部署因网络限制失败。解决方法：

1. 访问 https://claude.ai/settings/capabilities
2. 将*.vercel.com添加到允许域名列表
3. 重新尝试部署

—

权限升级网络访问（Codex / 沙箱环境

—

如果沙箱环境中部署因网络问题失败（超时、DNS错误、连接重置），使用升级权限重新运行（

sandbox_permissions=require_escalated

）。不要对初始CLI可用性检查升级权限——仅对实际部署命令升级。

示例用户引导：

部署需要升级网络访问权限才能部署到Vercel。我可以使用升级权限重新运行命令，是否继续？

—

CLI认证失败

—

如果

vercel login

或

vercel deploy

因认证错误失败，回退到无认证部署脚本（根据环境选择claude.ai或Codex版本）。",

deploy-to-vercel

Original

Translation

Deploy to Vercel

部署到Vercel

Step 1: Gather Project State

步骤1：收集项目状态

1. Check for a git remote

1. 检查git远程仓库地址

2. Check if locally linked to a Vercel project (either file means linked)

2. 检查本地是否已关联Vercel项目（两个文件任意存在即代表已关联

3. Check if the Vercel CLI is installed and authenticated

3. 检查Vercel CLI是否已安装并完成认证

4. List available teams (if authenticated)

4. 列出可用团队（如果已完成认证）

Team selection

团队选择

Step 2: Choose a Deploy Method

步骤2：选择部署方法

Linked (.vercel/ exists) + has git remote → Git Push

已关联（存在.vercel/ + 有git远程仓库 → Git推送

Linked (.vercel/ exists) + no git remote → vercel deploy

已关联（存在.vercel/ + 无git远程仓库 → vercel deploy

Not linked + CLI is authenticated → Link first, then deploy

未关联 + CLI已认证 → 先关联再部署

Not linked + CLI not authenticated → Install, auth, link, deploy

未关联 + CLI未认证 → 安装、认证、关联、部署

No-Auth Fallback — claude.ai sandbox

无认证降级方案 —— claude.ai沙箱

Deploy current directory

部署当前目录

Deploy specific project

部署指定项目

Deploy existing tarball

部署已有压缩包

No-Auth Fallback — Codex sandbox

无认证降级方案 —— Codex沙箱

Agent-Specific Notes

部署当前目录

Claude Code / terminal-based agents

Sandboxed environments (claude.ai)

部署指定项目

Codex

部署已有压缩包

Output

Agent专属说明

Claude Code / 基于终端的Agent

Troubleshooting

沙箱环境（claude.ai）

Network Egress Error (claude.ai)

Escalated Network Access (Codex / sandboxed environments)

Codex

CLI Auth Failure

输出

故障排查

网络出口错误（claude.ai）

权限升级网络访问（Codex / 沙箱环境

CLI认证失败

Linked (
`.vercel/`
exists) + has git remote → Git Push

已关联（存在
`.vercel/`
+ 有git远程仓库 → Git推送

Linked (
`.vercel/`
exists) + no git remote →
`vercel deploy`

已关联（存在
`.vercel/`
+ 无git远程仓库 →
`vercel deploy`