部署到 Vercel

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

目标是让用户进入最佳的长期设置状态：将其项目链接到 Vercel 并通过 git push 进行部署。下面的每种方法都旨在让用户更接近这种状态。

步骤 1: 收集项目状态

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

# 1. 检查 git remote
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 remote → Git Push

这是理想状态。项目已链接且具有 git 集成。

1. 在推送前询问用户。 未经明确批准切勿推送：

   This project is connected to Vercel via git. I can commit and push to
   trigger a deployment. Want me to proceed?
   (该项目已通过 git 连接到 Vercel。我可以提交并推送以触发部署。要继续吗？)
   

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 remote → 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.
   (正在将此项目链接到 Vercel 上的 <团队名称>。这将创建一个 Vercel 项目用于部署，并启用未来 git 推送时的自动部署。)
   

3. 如果存在 git remote，使用选定的团队范围进行基于仓库的链接：

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

   这会读取 git remote URL 并将其匹配到从该仓库部署的现有 Vercel 项目。它会创建 .vercel/repo.json。这比 vercel link（不带 --repo）可靠得多，后者尝试按目录名称匹配，当本地文件夹和 Vercel 项目名称不同时经常会失败。

   如果没有 git remote，回退到标准链接：

   vercel link --scope <team-slug>
   

   这会提示用户选择或创建一个项目。它会创建 .vercel/project.json。

4. 然后使用最佳可用方法进行部署：
   • 如果存在 git remote → 提交并推送（参见上面的 git push 方法）
   • 如果没有 git remote → 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 remote 则使用 --repo，否则使用普通的 vercel link）：

   vercel link --repo --scope <team-slug>   # 如果存在 git remote
   vercel link --scope <team-slug>          # 如果没有 git remote
   

5. 部署，使用最佳可用方法（如果存在 remote 则 git push，否则 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 push: 使用 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.
  (部署成功！预览 URL: ... 认领 URL: ... 请在预览 URL 查看您的网站。若要转移此部署到您的 Vercel 账户，请访问认领 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
(由于网络限制部署失败。解决方法：1. 前往... 2. 添加 *.vercel.com 到允许域名 3. 重试部署)

提权的网络访问 (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?
(部署需要提权的网络访问才能部署到 Vercel。我可以使用提权权限重新运行命令——要我继续吗？)

CLI 认证失败

如果 vercel login 或 vercel deploy 因认证错误失败，请回退到无认证部署脚本（根据环境选择 claude.ai 或 Codex 变体）。