部署到 Vercel
将任何项目部署到 Vercel。始终以预览(preview)方式部署,除非用户明确要求生产环境(production)。
目标是让用户进入最佳长期工作流程:项目通过 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 集成。
-
在推送前先询问用户。 未经明确批准绝不推送:
此项目已通过 Git 连接到 Vercel。我可以提交并推送以触发部署。是否继续? -
提交并推送:
git add . git commit -m "deploy: <更改描述>" git pushVercel 会从推送自动构建。非生产分支获得预览部署;生产分支(通常是
main)获得生产部署。 -
获取预览 URL。 如果 CLI 已认证:
sleep 5 vercel ls --format jsonJSON 输出包含一个
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 中的团队 slug。如果只有一个团队(或仅个人账户),跳过此步骤。
-
一旦选择了团队,直接进行关联。 告知用户接下来会发生什么,但不要要求单独确认:
正在将此项目关联到 <team name> 上的 Vercel。这将创建一个 Vercel 项目用于部署,并启用未来 Git 推送的自动部署。 -
如果存在 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。 -
然后使用最佳可用方法部署:
- 如果存在 Git 远程仓库 → 提交并推送(参见上面的 Git 推送方法)
- 如果没有 Git 远程仓库 →
vercel deploy [path] -y --no-wait --scope <team-slug>,然后使用vercel inspect <url>检查状态
未关联 + CLI 未认证 → 安装、认证、关联、部署
Vercel CLI 尚未安装。
-
安装 CLI(如果尚未安装):
npm install -g vercel -
认证:
vercel login用户在浏览器中完成认证。如果在非交互式环境中无法登录,请跳转到下面的免认证回退。
-
询问要部署到哪个团队:以项目符号列表呈现
vercel teams list --format json中的团队 slug。如果只有一个团队/个人账户,跳过。一旦选择,立即继续。 -
使用所选团队范围关联项目(如果存在 Git 远程仓库则使用
--repo,否则使用普通vercel link):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>检查状态)。
免认证回退,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,如果认证失败则回退到部署脚本。
-
检查 Vercel CLI 是否已安装(此检查无需提升权限):
command -v vercel -
如果安装了
vercel,尝试使用 CLI 部署:vercel deploy [path] -y --no-wait -
如果未安装
vercel,或 CLI 失败并显示“No existing credentials found”,使用回退脚本:skill_dir="<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 版本)。