Vercel Secure Deploy

Vercel 安全部署助手

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

执行流程

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

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

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

使用 AskUserQuestion 工具询问：

问题 1：你有 Vercel 账号吗？

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

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

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

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

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

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

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

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

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

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

使用 AskUserQuestion 工具询问：

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

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

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

域名前缀规则：

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

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

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

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

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

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

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

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

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

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

第三步：自动改造代码

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

1. 创建后端接口 (api/ 目录)

   • 告诉用户："正在创建安全的后端接口..."
   • 重要：必须使用原项目中的模型名称和 API 调用方式
   • 参考 templates/ 目录下的模板，但要根据原项目调整

2. 修改前端代码

   • 告诉用户："正在修改前端代码，移除暴露的密钥..."
   • 更新 services 文件，改为调用后端接口
   • 保持原有的函数签名和返回值格式

3. 创建配置文件

   • 告诉用户："正在创建部署配置..."
   • 创建 vercel.json
   • 更新 vite.config.ts（移除密钥注入）
   • 更新 package.json（添加依赖和 engines 字段）

4. 创建环境变量文件

   • 创建 .env.local 写入用户提供的 API 密钥
   • 确保 .gitignore 包含 .env* 或 *.local

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

改动说明：

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

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

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

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

1. 检查并配置 Node.js 版本

   读取 package.json，确保包含 engines 字段：

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

   注意：使用 ">=18" 而不是 ">=18.x"，避免版本警告。

2. 安装依赖

   npm install
   

3. 本地构建测试

   运行本地构建命令验证项目可以正常构建：

   npm run build
   

   如果构建失败，分析错误并修复后重试。常见问题：

   • TypeScript 类型错误：检查并修复类型定义
   • 依赖缺失：运行 npm install 安装
   • 环境变量问题：检查 vite.config.ts 配置

4. 检查必要文件存在

   确认以下文件存在且配置正确：

   • 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 登录状态，继续部署..."

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

1. 告诉用户："检测到未登录 Vercel，正在为你启动登录流程..."

2. 使用 Bash 工具运行登录命令（自动发送回车以跳过交互提示）：

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

3. 此命令会在后台运行，读取输出文件获取验证链接（通常包含 vercel.com/oauth/device?user_code= 格式的 URL）

4. 将链接展示给用户： "请打开以下链接完成 Vercel 登录：

[提取到的验证链接]

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

5. 等待后台任务完成，检查输出是否包含 "Congratulations" 确认登录成功

6. 运行 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 环境变量..."

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

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

1. 拉取项目设置

vercel pull --yes 2>&1

2. 本地构建生产版本

vercel build --prod 2>&1

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

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 路由的正确方式

1. 首先读取原项目的服务文件，提取：

   • 模型名称（如 gemini-3-pro-image-preview）
   • API 调用参数结构
   • 响应处理逻辑

2. 根据原项目创建 API 路由，而不是直接使用模板

3. 模板仅作参考，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