deploy-to-vercel

部署到 Vercel

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

目标是帮助用户采用最佳的长期方案：将项目关联到 Vercel，并通过 Git 推送部署。以下每种方法都会尽量让用户更接近这一状态。

步骤 1：收集项目状态

在决定使用哪种方法前，运行以下所有四项检查：

# 1. Check for a git remote
git remote get-url origin 2>/dev/null

# 2. Check if locally linked to a Vercel project (either file means linked)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# 3. Check if the Vercel CLI is installed and authenticated
vercel whoami 2>/dev/null

# 4. List available teams (if authenticated)
vercel teams list --format json 2>/dev/null

选择团队

如果用户属于多个团队，请以项目符号列表列出所有可用的团队 slug，并询问要部署到哪个团队。用户选定团队后，立即进入下一步——无需再次确认。

在后续所有 CLI 命令（vercel deploy、vercel link、vercel inspect 等）中，通过 --scope 传入团队 slug：

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 可以在任何位置安全运行。

步骤 2：选择部署方法

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

这是理想状态。项目已关联，并且已集成 Git。

1. **推送前先询问用户。**未经明确批准，绝不推送：

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

2. 提交并推送：

   git add .
   git commit -m "deploy: <description of changes>"
   git push
   

   Vercel 会自动根据推送内容进行构建。非生产分支会部署为预览环境；生产分支（通常是 main）会部署到生产环境。

3. **获取预览 URL。**如果 CLI 已通过身份验证：

   sleep 5
   vercel ls --format json
   

   JSON 输出中包含一个 deployments 数组。找到最新条目——其 url 字段就是预览 URL。

   如果 CLI 未通过身份验证，请告知用户前往 Vercel 控制面板或 Git 服务提供商中的提交状态检查，查看预览 URL。

---

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

项目已关联，但没有 Git 仓库。直接使用 CLI 部署。

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

使用 --no-wait，让 CLI 立即返回部署 URL，而不是阻塞直至构建完成（构建可能需要一段时间）。然后使用以下命令检查部署状态：

vercel inspect <deployment-url>

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

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

---

未关联 + CLI 已通过身份验证 → 先关联，再部署

CLI 可正常使用，但项目尚未关联。现在正好可以帮助用户进入最佳状态。

1. 询问用户要部署到哪个团队。 将步骤 1 中的团队 slug 以项目符号列表的形式列出。如果只有一个团队（或只有个人账户），则跳过此步骤。

2. 选定团队后，直接继续关联。 告知用户接下来会发生什么，但不要另行征求确认：

   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.
   

3. 如果存在 git 远程仓库，使用所选团队范围进行基于仓库的关联：

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

   这会读取 git 远程仓库 URL，并将其与从该仓库部署的现有 Vercel 项目进行匹配。此操作会创建 .vercel/repo.json。这比 vercel link（不带 --repo）可靠得多；后者会尝试按目录名进行匹配，而当本地文件夹与 Vercel 项目名称不同时，往往会失败。

   如果不存在 git 远程仓库，则改用标准关联方式：

   vercel link --scope <team-slug>
   

   这会提示用户选择或创建项目，并创建 .vercel/project.json。

4. 然后使用最佳可用方式部署：

   • 如果存在 git 远程仓库 → 提交并推送（参见上文的 git push 方式）
   • 如果不存在 git 远程仓库 → 执行 vercel deploy [path] -y --no-wait --scope <team-slug>，然后执行 vercel inspect <url> 检查状态

---

未关联 + CLI 未通过身份验证 → 安装、身份验证、关联、部署

尚未设置 Vercel CLI。

1. 安装 CLI（如果尚未安装）：

   npm install -g vercel
   

2. 进行身份验证：

   vercel login
   

   用户在浏览器中完成身份验证。如果处于无法登录的非交互式环境，则跳转到下方的无身份验证回退方案。

3. 询问要部署到哪个团队 — 将 vercel teams list --format json 返回的团队 slug 以项目符号列表的形式列出。如果只有一个团队或个人账户，则跳过。选定后立即继续。

4. 关联项目并指定所选团队范围（如果存在 git 远程仓库，则使用 --repo；否则使用普通的 vercel link）：

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

5. 部署，使用最佳可用方式（如果存在远程仓库，则使用 git push；否则执行 vercel deploy -y --no-wait --scope <team-slug>，然后执行 vercel inspect <url> 检查状态）。

---

无身份验证回退方案 — claude.ai 沙盒

适用情况： 当无法在 claude.ai 沙盒中安装或通过身份验证使用 CLI 时，作为最后的手段。此方式无需身份验证 — 它会返回一个预览 URL（实时网站）和一个认领 URL（转移到你的 Vercel 账户）。

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

参数：

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

示例：

# 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

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

告知用户：“你的部署已就绪，访问 [previewUrl] 查看。前往 [claimUrl] 认领，即可管理你的部署。”

---

无身份验证回退方案 — Codex 沙盒

适用情况： 在 Codex 沙盒中使用，此时 CLI 可能尚未通过身份验证。Codex 默认在沙盒环境中运行 — 先尝试使用 CLI，如果身份验证失败，则改用部署脚本。

1. 检查是否已安装 Vercel CLI（此检查无需提升权限）：

   command -v vercel
   

2. 如果已安装 vercel，尝试使用 CLI 部署：

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

3. 如果未安装 vercel，或 CLI 因 “No existing credentials found” 失败，则使用回退脚本：

   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
   

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

告知用户：“你的部署已就绪，访问 [previewUrl] 查看。前往 [claimUrl] 认领，即可管理你的部署。”

提升网络访问权限： 仅当沙盒阻止网络调用时，才为实际部署命令提升权限（sandbox_permissions=require_escalated）。不要为 command -v vercel 检查提升权限。

---

Agent 专属说明

Claude Code / 基于终端的 Agent

你拥有完整的 shell 访问权限。请勿使用 /mnt/skills/ 路径。直接使用 CLI，按照上述决策流程操作。

对于无认证回退方案，请从技能的安装位置运行部署脚本：

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

路径可能因用户安装技能的位置而异。

沙盒环境（claude.ai）

你可能无法运行 vercel login 或 git push。请直接转到 无认证回退方案 — claude.ai 沙盒。

Codex

Codex 在沙盒中运行。请先检查 CLI 是否可用，然后回退到部署脚本。转到 无认证回退方案 — Codex 沙盒。

---

输出

始终向用户显示部署 URL。

• Git 推送： 使用 vercel ls --format json 查找预览 URL。如果 CLI 未通过认证，请告知用户检查 Vercel 控制面板或提交状态检查。
• CLI 部署： 显示 vercel deploy --no-wait 返回的 URL。使用 vercel inspect <url> 检查构建状态，并将结果告知用户。
• 无认证回退方案： 同时显示预览 URL 和认领 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.
  

不要通过 curl 或 fetch 访问已部署的 URL 来验证是否可用。直接返回链接即可。

---

故障排除

网络出口错误（claude.ai）

如果由于 claude.ai 上的网络限制导致部署失败，请告知用户：

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

提升网络访问权限（Codex / 沙盒环境）

如果沙盒环境中由于网络问题（超时、DNS 错误、连接重置）导致部署失败，请使用提升后的权限（sandbox_permissions=require_escalated）重新运行。不要提升初始 CLI 可用性检查的权限——只提升实际部署命令的权限。

给用户的示例说明：

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

CLI 身份验证失败

如果 vercel login 或 vercel deploy 因身份验证错误而失败，请回退到无认证部署脚本（根据环境使用 claude.ai 或 Codex 版本）。