Awesome-omni-skill vercel-secure-deploy

将 Google AI Studio 项目部署到 Vercel。当用户提到"部署"、"上线"、"发布网站"、"Vercel"、"保护 API 密钥"时触发。

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/backend/vercel-secure-deploy" ~/.claude/skills/diegosouzapw-awesome-omni-skill-vercel-secure-deploy && rm -rf "$T"

manifest: skills/backend/vercel-secure-deploy/SKILL.md

safety · automated scan (medium risk)

This is a pattern-based risk scan, not a security review. Our crawler flagged:

global npm install
references .env files
references API keys

Always read a skill's source content before installing. Patterns alone don't mean the skill is malicious — but they warrant attention.

source content

Vercel 安全部署助手

帮助用户将 Google AI Studio 项目安全地部署到互联网上，全程交互式引导，无需技术背景。

执行流程

第一步：欢迎并收集基本信息

首先向用户打招呼并解释将要做什么：

"你好！我来帮你把这个 AI 项目发布到网上，让任何人都能访问。我会一步步引导你完成。在开始之前，我需要了解一些信息。"

使用 AskUserQuestion 工具询问：

问题 1：你有 Vercel 账号吗？

有，已经注册过了
没有，需要注册一个

如果没有，引导用户： "请先注册一个 Vercel 账号：

打开 https://vercel.com
点击右上角 'Sign Up'
推荐使用 GitHub 账号登录（如果有的话）
注册完成后告诉我"

问题 2：你有 Gemini API 密钥吗？

有，我已经有了
没有，需要获取一个

如果没有，引导用户： "请获取一个免费的 Gemini API 密钥：

打开 https://aistudio.google.com/apikey
用 Google 账号登录
点击 'Create API Key'
复制生成的密钥（一长串字母数字）
把密钥发给我"

问题 3：请把你的 API 密钥发给我 （等待用户提供密钥，格式类似：AIzaSy...）

收到密钥后确认： "收到！我会把这个密钥安全地配置到服务器端，不会暴露在网页代码中。"

问题 4：你想要什么域名前缀？

使用 AskUserQuestion 工具询问：

使用默认（项目名称）
自定义域名前缀

如果选择自定义，让用户在"其他"选项中输入想要的前缀。

说明： "你的网站地址将会是：[前缀].vercel.app

域名前缀规则：

只能包含小写字母、数字和连字符（-）
不能以连字符开头或结尾
例如：my-cool-app、memegen2024"

记录用户选择的域名前缀，后续部署时使用。

第二步：分析项目（重要）

自动执行，无需用户操作：

读取
```
package.json
```
确定项目类型
读取原项目的 AI 服务代码，提取模型名称（非常重要！）
查找 API 调用代码的具体实现方式
检查现有配置

关键：必须从原项目代码中提取以下信息：

使用的模型名称（如
```
gemini-3-pro-image-preview
```
）
API 调用的参数结构（如
```
imageConfig
```
、
```
inputImage
```
等）
响应数据的处理方式

向用户报告： "正在分析你的项目...

✅ 项目类型：[React/Vue/其他] ✅ AI 服务：[Gemini/OpenAI/其他] ✅ 使用的模型：[从代码中提取的模型名称] ✅ 需要保护的 API 密钥：已找到

接下来我会自动完成代码改造，请稍等..."

第三步：自动改造代码

执行以下操作（自动完成，向用户展示进度）：

创建后端接口 (
```
api/
```
目录)
- 告诉用户："正在创建安全的后端接口..."
- 重要：必须使用原项目中的模型名称和 API 调用方式
- 参考
```
templates/
```
  目录下的模板，但要根据原项目调整
修改前端代码
- 告诉用户："正在修改前端代码，移除暴露的密钥..."
- 更新 services 文件，改为调用后端接口
- 保持原有的函数签名和返回值格式
创建配置文件
- 告诉用户："正在创建部署配置..."
- 创建
```
vercel.json
```
- 更新
```
vite.config.ts
```
  （移除密钥注入）
- 更新
```
package.json
```
  （添加依赖和 engines 字段）
创建环境变量文件
- 创建
```
.env.local
```
  写入用户提供的 API 密钥
- 确保
```
.gitignore
```
  包含
```
.env*
```
  或
```
*.local
```

完成后告诉用户： "✅ 代码改造完成！

改动说明：

创建了安全的后端接口，API 密钥只存在服务器端
网页代码中不再包含任何密钥
已配置好部署设置

接下来进入部署环节..."

第四步：预部署检查（重要）

此步骤确保 Vercel 构建一次成功，必须执行！

检查并配置 Node.js 版本

读取

package.json

，确保包含

engines

字段：

{
  "engines": {
    "node": ">=18"
  }
}

注意：使用

">=18"

而不是

">=18.x"

，避免版本警告。

安装依赖
```
npm install
```
本地构建测试

运行本地构建命令验证项目可以正常构建：
```
npm run build
```
如果构建失败，分析错误并修复后重试。常见问题：
- TypeScript 类型错误：检查并修复类型定义
- 依赖缺失：运行
```
npm install
```
  安装
- 环境变量问题：检查 vite.config.ts 配置
检查必要文件存在

确认以下文件存在且配置正确：
- ```
vercel.json
```
  - Vercel 部署配置
- ```
api/
```
  目录下的 API 路由文件
- ```
package.json
```
  中的 build 脚本

告诉用户："正在进行预部署检查，确保一次部署成功..."

检查通过后告诉用户："✅ 预部署检查通过，项目可以正常构建。"

第五步：检查并安装 Vercel CLI

自动执行，使用 Bash 工具检查 Vercel CLI 是否已安装：

which vercel || npm install -g vercel

告诉用户："正在检查 Vercel CLI..."

如果未安装，自动安装。向用户报告安装结果。

第六步：检查 Vercel 登录状态

自动执行，使用 Bash 工具检查登录状态：

vercel whoami 2>&1

如果已登录，告诉用户："已检测到 Vercel 登录状态，继续部署..."

如果未登录，自动执行登录流程：

告诉用户："检测到未登录 Vercel，正在为你启动登录流程..."
使用 Bash 工具运行登录命令（自动发送回车以跳过交互提示）：

printf '\n' | vercel login 2>&1

此命令会在后台运行，读取输出文件获取验证链接（通常包含
```
vercel.com/oauth/device?user_code=
```
格式的 URL）
将链接展示给用户： "请打开以下链接完成 Vercel 登录：

[提取到的验证链接]

在浏览器中完成授权后，登录会自动完成。"

等待后台任务完成，检查输出是否包含 "Congratulations" 确认登录成功
运行
```
vercel whoami
```
验证登录成功

备选方案：如果自动登录失败，引导用户使用 token 方式登录：

让用户访问 https://vercel.com/account/tokens 创建 token
使用
```
vercel login --token <token>
```
完成登录

第七步：首次部署并链接项目

自动执行，使用 Bash 工具运行非交互式部署来创建项目：

vercel --yes 2>&1

注意：

--name

参数已废弃，不要使用！ 项目名称会自动使用目录名。

告诉用户："正在创建 Vercel 项目..."

这一步会：

创建 Vercel 项目
生成
```
.vercel
```
目录
链接本地项目到 Vercel

第八步：配置环境变量

自动执行，使用 Bash 工具配置环境变量（使用用户之前提供的 API 密钥）：

echo "API_KEY_VALUE" | vercel env add GEMINI_API_KEY production 2>&1
echo "API_KEY_VALUE" | vercel env add GEMINI_API_KEY preview 2>&1
echo "API_KEY_VALUE" | vercel env add GEMINI_API_KEY development 2>&1

注意：将

API_KEY_VALUE

替换为用户在第一步提供的实际密钥。

告诉用户："正在配置 API 密钥到 Vercel 环境变量..."

第九步：本地预构建并部署到生产环境（推荐方式）

重要：使用本地预构建方式部署，比远程构建更稳定！

拉取项目设置

vercel pull --yes 2>&1

本地构建生产版本

vercel build --prod 2>&1

部署预构建产物到生产环境

vercel deploy --prebuilt --prod --yes 2>&1

告诉用户："正在进行正式部署..."

为什么使用本地预构建？

Vercel 远程构建有时会因为 npm install 超时等问题失败
本地预构建可以提前发现和修复问题
部署预构建产物更快更稳定

部署完成后，从输出中提取生产网址（通常是

xxx.vercel.app

）。

完成确认

向用户展示最终结果：

"部署完成！

你的网站地址：[从部署输出中提取的生产网址]

现在任何人都可以通过这个网址访问你的应用了。

✅ 已完成的工作：

创建了安全的后端接口
API 密钥已安全配置到 Vercel 环境变量
项目已部署到生产环境

一些小贴士：

这个网址是永久有效的

如果以后要更新代码，运行以下命令重新部署：

vercel build --prod && vercel deploy --prebuilt --prod --yes

API 密钥安全地存储在 Vercel 服务器上，不会泄露

还有什么问题吗？"

错误处理指南

常见问题及自动修复

npm install 在 Vercel 构建时失败

原因：通常是 Node.js 版本不兼容或 npm 超时

修复：使用本地预构建方式（

vercel build --prod

vercel deploy --prebuilt --prod

）

engines 字段警告

使用
```
"node": ">=18"
```
而不是
```
">=18.x"
```
避免使用会自动升级的版本格式

本地 npm install 失败

检查是否安装了 Node.js
引导用户安装：https://nodejs.org

vercel login 失败

检查网络连接
如果无法获取验证链接，使用 token 方式登录：
1. 让用户访问 https://vercel.com/account/tokens
2. 点击 "Create Token" 创建新 token
3. 运行
```
vercel login --token <用户的token>
```
如果浏览器无法打开，手动复制输出中的验证链接到浏览器

Vercel 构建失败

先在本地运行
```
npm run build
```
复现问题
检查 TypeScript 错误并修复
确保所有依赖都在 package.json 中声明

部署后 API 调用报错 "model not found"

这是最常见的问题！
原因：API 路由中使用的模型名称与原项目不一致
修复：必须从原项目的服务文件中提取正确的模型名称
不要使用模板中的默认模型名称，每个项目可能使用不同的模型

部署后网站报错

检查环境变量是否正确配置：
```
vercel env ls
```
查看 Vercel 仪表板的 Function Logs

API 调用失败

确认 API 密钥正确
确认 Gemini API 已启用
检查
```
/api/gemini
```
路由是否正确部署
确认模型名称正确

预构建环境不匹配错误

如果看到 "prebuilt output was built with target environment preview"

需要使用

vercel build --prod

重新构建，再用

vercel deploy --prebuilt --prod

技术操作参考

创建 API 路由的正确方式

首先读取原项目的服务文件，提取：
- 模型名称（如
```
gemini-3-pro-image-preview
```
  ）
- API 调用参数结构
- 响应处理逻辑
根据原项目创建 API 路由，而不是直接使用模板
模板仅作参考，
```
templates/
```
目录下的文件：
- ```
gemini-api-route.ts
```
  - Gemini API 后端路由参考
- ```
openai-api-route.ts
```
  - OpenAI API 后端路由参考
- ```
frontend-service.ts
```
  - 前端服务调用方式参考

部署命令速查

# 首次部署（创建项目）
vercel --yes

# 配置环境变量
echo "your-api-key" | vercel env add GEMINI_API_KEY production

# 拉取项目设置
vercel pull --yes

# 本地预构建（推荐）
vercel build --prod

# 部署预构建产物到生产环境（推荐）
vercel deploy --prebuilt --prod --yes

# 更新部署的完整流程
vercel build --prod && vercel deploy --prebuilt --prod --yes

预部署检查清单

部署前确保以下项目全部通过：

package.json

包含

"engines": { "node": ">=18" }

```
npm run build
```
本地构建成功
```
vercel.json
```
配置正确
```
api/
```
目录存在且包含 API 路由
API 路由中的模型名称与原项目一致
```
.gitignore
```
包含
```
.env*
```
或
```
*.local
```
已确认用户的域名前缀选择（默认或自定义）

更换 API 密钥

如果用户需要更换 API 密钥：

# 删除旧密钥
vercel env rm GEMINI_API_KEY production --yes
vercel env rm GEMINI_API_KEY preview --yes
vercel env rm GEMINI_API_KEY development --yes

# 添加新密钥
echo "new-api-key" | vercel env add GEMINI_API_KEY production
echo "new-api-key" | vercel env add GEMINI_API_KEY preview
echo "new-api-key" | vercel env add GEMINI_API_KEY development

# 重新部署使新密钥生效
vercel build --prod && vercel deploy --prebuilt --prod --yes