部署到 Vercel

部署到 Vercel 是做什么的？

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

目标是让用户进入最佳长期工作流程：项目通过 git 推送部署关联到 Vercel。以下每种方法都致力于将用户推向该状态。

第 1 步：收集项目状态

在决定使用哪种方法之前，请运行全部四项检查：

# 1. 检查 git 远程仓库
出站 git remote get-url origin 2>/dev/null

# 2. 检查是否本地关联到 Vercel 项目（任一文件均表示已关联）
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# 3. 检查 Vercel CLI 是否已安装并已认证
vercel whoami 2>/dev/null

# 4. 列出可用团队（如已认证）
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. 在推送前征询用户同意。 没有明确批准，绝不推送：

   此项目已通过 git 连接到 Vercel。我可以提交并推送
   以触发部署。是否继续？
   

2. 提交并推送：

   git add .
   git commit -m "deploy: <变更描述>"
   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. 一旦选择了团队，直接进行关联。 告知用户将要发生的事情，但无需单独确认：

   正在将此项目关联到 Vercel 上的 <团队名称>。这将创建一个用于部署的 Vercel
   项目，并支持未来 git 推送的自动部署。
   

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 推送方法）
   • 如果不存在 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>   # 如果存在 git 远程仓库
   vercel link --scope <team-slug>          # 如果不存在 git 远程仓库
   

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

---

无认证回退 — claude.ai 沙箱

何时使用： 当 CLI 在 claude.ai 沙箱中无法安装或认证时作为最后手段。这不需要认证——它返回一个预览 URL（在线站点）和一个认领 URL（转移到你的 Vercel 账户）。

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

参数：

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

示例：

# 部署当前目录
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh

# 部署特定项目
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project

# 部署已有的 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>"
   
   # 部署当前目录
   bash "$skill_dir/resources/deploy-codex.sh"
   
   # 部署特定项目
   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
   
   # 部署已有的 tarball
   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
   

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

告知用户： “你的部署已准备就绪：[previewUrl]。前往 [claimUrl] 认领它以管理你的部署。”

提级的网络访问： 仅在沙箱阻止网络调用时才提级实际的部署命令（sandbox_permissions=require_escalated）。不要提级 command -v vercel 检查。

---

代理特定说明

Claude Code / 基于终端的代理

你拥有完整的 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：

  部署成功！
  
  预览 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 变体）。