deploy-to-vercel

部署到 Vercel

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

目标是让用户进入最佳长期设置：项目链接到 Vercel 并支持 git 推送部署。下面的每种方法都试图让用户更接近该状态。

步骤 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 变体）。