前言¶
本地改完代碼，下一步往往是上線驗證：配環境、裝 CLI、登錄賬號、選預覽還是生產……對習慣用 AI 編程助手寫代碼的開發者來說，這些步驟常常打斷心流。你更想要的是一句「幫我把這個項目部署出去，把鏈接給我」，Agent 就能按規範走完流程。
vercel-deploy 就是爲此準備的 Agent Skill。它收錄在 OpenAI 維護的 openai/skills 倉庫 .curated 精選目錄中，Skill 本身由 Vercel 授權（MIT License），專門指導 AI Agent 把應用或網站部署到 Vercel，並返回可訪問的預覽鏈接。下文基於官方 SKILL.md 與 scripts/deploy.sh 源碼整理，關鍵流程均可對照原文覈實。
這是什麼¶
vercel-deploy 是一個通用格式的 Agent Skill（SKILL.md + 配套腳本），核心定位是：
當用戶說「部署我的應用」「部署並給我鏈接」「推上線」或「創建預覽部署」時，Agent 應調用此 Skill，把項目部署到 Vercel 並返回 URL。
它解決的不是「教你怎麼寫 Vercel 配置」，而是把部署動作標準化：Agent 先檢查 Vercel CLI，能走 CLI 就走 CLI；CLI 不可用或未登錄時，自動降級到 Skill 自帶的 deploy.sh 腳本，無需用戶事先配置 Vercel 賬號也能拿到預覽鏈接。
來源歸屬：
- 倉庫：openai/skills →
skills/.curated/vercel-deploy/ - 版權：Vercel（MIT License，2026）
- 兼容工具：Cursor、Codex CLI、Claude Code 等支持
SKILL.md格式的 AI 編程工具
核心功能與亮點¶
1. 默認預覽部署，避免誤上生產¶
Skill 明確規定：除非用戶明確要求生產環境，否則一律以預覽（Preview）方式部署。這能避免 Agent 在用戶只想「看看效果」時，誤把未驗證的代碼推到 Production。
生產部署僅在用戶顯式要求時執行：
vercel deploy [path] --prod -y
2. 雙路徑部署：CLI 優先，腳本兜底¶
路徑 A — Vercel CLI（已安裝且已登錄）
- 先用普通權限檢查 CLI 是否存在（不提升沙箱權限）：
command -v vercel
- 若存在，執行部署（建議超時設爲 10 分鐘，構建可能較久）：
vercel deploy [path] -y
路徑 B — 無認證兜底腳本
當 CLI 未安裝，或報錯 No existing credentials found 時，Agent 應調用 Skill 目錄下的 scripts/deploy.sh：
skill_dir="<path-to-skill>"
# 部署當前目錄
bash "$skill_dir/scripts/deploy.sh"
# 部署指定項目目錄
bash "$skill_dir/scripts/deploy.sh" /path/to/project
# 部署已有 tarball
bash "$skill_dir/scripts/deploy.sh" /path/to/project.tgz
腳本會把項目打包上傳到 https://codex-deploy-skills.vercel.sh/api/deploy，等待構建完成後返回 JSON，其中包含：
previewUrl：可直接訪問的預覽站點claimUrl：用於將部署認領到你自己的 Vercel 賬號
Agent 應告知用戶：「Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment.」
3. 自動框架檢測與靜態站點處理¶
deploy.sh 會讀取 package.json 的依賴，自動識別框架類型，例如 Next.js、Nuxt、SvelteKit、Astro、Remix、Vite、Express、NestJS 等數十種。打包時會排除 node_modules、.git、.env 等目錄，避免上傳冗餘或敏感文件。
對於沒有 package.json 的純靜態 HTML 項目：若根目錄只有一個 HTML 文件且不叫 index.html，腳本會自動將其重命名爲 index.html，確保頁面在根路徑 / 可訪問。
4. 沙箱網絡與超時處理¶
在 Cursor、Codex 等沙箱環境中，部署可能因網絡受限失敗。Skill 要求：檢查 CLI 時不要提升權限；僅在執行實際部署命令時，若出現超時、DNS 錯誤或連接重置，才用 sandbox_permissions=require_escalated 重試部署命令。部署本身可能耗時數分鐘，Agent 需設置合理超時（CLI 路徑建議 600000ms，即 10 分鐘）。
5. 輸出規範¶
- 向用戶展示部署 URL；兜底腳本部署時同時展示 claim URL
- 不要用 curl 等方式去驗證部署 URL 是否可訪問，直接返回鏈接即可
安裝與啓用¶
Skill 以目錄形式存在，至少需要 SKILL.md 與 scripts/deploy.sh（兜底部署依賴後者）。官方目錄結構如下：
vercel-deploy/
├── SKILL.md
├── scripts/
│ └── deploy.sh
├── agents/
│ └── openai.yaml
├── assets/
├── LICENSE.txt
在 Cursor 中使用¶
- 從官方倉庫複製整個
vercel-deploy目錄到項目或用戶級 Skills 路徑：
# 項目級（隨倉庫共享給團隊）
mkdir -p .cursor/skills
git clone --depth 1 --filter=blob:none --sparse https://github.com/openai/skills.git /tmp/openai-skills
cd /tmp/openai-skills && git sparse-checkout set skills/.curated/vercel-deploy
cp -r skills/.curated/vercel-deploy /你的項目/.cursor/skills/
# 或用戶級（所有項目可用）
cp -r skills/.curated/vercel-deploy ~/.cursor/skills/
-
確認
SKILL.md頂部 frontmatter 包含name: vercel-deploy與description字段；文件夾名須與name一致（小寫、連字符）。 -
重啓或刷新 Cursor 後，Skill 會出現在 Agent 可用技能列表中。可在 Agent 對話裏輸入
/vercel-deploy手動調用，也可在描述匹配時由 Agent 自動選用。
Cursor 還會掃描 .agents/skills/ 與 ~/.agents/skills/，路徑規則與 .cursor/skills/ 相同。
在 Codex CLI 中使用¶
將同樣目錄放到 .codex/skills/vercel-deploy/ 或 ~/.codex/skills/vercel-deploy/。Codex 默認運行在沙箱中，Skill 文檔特別說明：先嚐試 CLI，認證失敗再回退到 deploy.sh。
在 Claude Code 中使用¶
放到 .claude/skills/vercel-deploy/ 或 ~/.claude/skills/vercel-deploy/，格式與 Cursor 一致。
典型用法示例¶
場景一：本地 Next.js 項目，CLI 已登錄¶
用戶對 Agent 說：
幫我把當前項目部署到 Vercel，把預覽鏈接給我。
Agent 按 Skill 執行：
command -v vercel
vercel deploy . -y
返回形如 https://xxx.vercel.app 的預覽 URL。
場景二：沙箱環境，無 Vercel 登錄¶
用戶對 Agent 說：
Deploy my app and give me the link.
CLI 報 No existing credentials found 後，Agent 調用：
bash "$skill_dir/scripts/deploy.sh" .
腳本 stderr 會輸出構建進度，最終 stdout 返回 JSON。用戶得到兩個鏈接，例如：
- Preview URL：
https://skill-deploy-xxxxx.vercel.app - Claim URL：
https://vercel.com/claim-deployment?code=...
通過 Claim URL 可將該部署綁定到自己的 Vercel 賬號，後續可在控制檯管理域名、環境變量等。
場景三：明確要求生產部署¶
用戶說：
把這個項目部署到 Vercel 生產環境。
此時 Agent 才應使用：
vercel deploy . --prod -y
若 CLI 不可用，需先與用戶確認是否接受預覽部署 + Claim 流程，因爲兜底腳本面向的是可認領的預覽部署，而非直接推 Production。
適用場景與注意事項¶
適合誰用
- 用 AI 助手快速搭原型、落地頁、全棧 Demo，需要「改完即看線上效果」
- 在 Cursor / Codex / Claude Code 沙箱裏開發，暫時無法或未配置 Vercel CLI 登錄
- 團隊希望把「部署到 Vercel」固化爲 Agent 標準動作，減少口頭重複指令
使用注意
- 預覽優先：Skill 設計哲學是默認 Preview；生產部署必須用戶明確開口。
- 保留 scripts 目錄：僅複製
SKILL.md不夠，無認證兜底依賴scripts/deploy.sh。 - 構建時間：首次部署可能較慢，Agent 與人都需耐心等待；腳本最多輪詢約 5 分鐘等待構建完成。
- 敏感文件：腳本會排除
.env等，但部署前仍建議檢查項目中是否含不應上傳的密鑰。 - 網絡權限：沙箱內部署失敗時，Agent 可能需要你授權提升網絡權限後重試。
- 與 Vercel 官方 Skill 的區別：Vercel Labs 也維護 deploy-to-vercel 等 Skill，流程更側重 CLI 登錄與 Git 關聯；OpenAI 精選的 vercel-deploy 更突出「零賬號預覽 + Claim」兜底，適合 Agent 沙箱場景。
小結¶
vercel-deploy 把「從代碼到可訪問鏈接」這件事寫進了 Agent 的可執行規範：CLI 能用時走標準 vercel deploy，不能用時用 bundled 腳本一鍵打包上傳，返回預覽 URL 與 Claim URL。對廣泛採用 Vercel 做前端與全棧託管的開發者來說，這是實用面很廣的一個 Skill。
官方地址：https://github.com/openai/skills/tree/main/skills/.curated/vercel-deploy
