TinyFish Cookbook部署Vercel完整指南：环境变量管理、API密钥安全与常见坑位排查

TinyFish Cookbook部署Vercel完整指南：环境变量管理、API密钥安全与常见坑位排查

【免费下载链接】tinyfish-cookbookA collection of sample apps and recipes built with the TinyFish web agent. Open-source examples for you to learn & build!项目地址: https://gitcode.com/gh_mirrors/ti/tinyfish-cookbook

TinyFish Cookbook 是基于 TinyFish Web Agent（网页智能体）构建的开源示例应用合集，收录了 30+ 个可直接运行的 Next.js 项目。本指南带你完整走一遍Vercel 部署流程：从克隆仓库、配置环境变量，到 API 密钥安全管理，以及长任务超时等常见坑位排查，帮助新手快速把任一样例应用到线上。

部署前准备：3 个先决条件

每个示例项目都是独立文件夹（一个独立 Next.js 工程），部署时只部署你需要的那一个目录，而不是整个仓库。项目总览与所有示例清单见 README.md。

一键部署步骤：从克隆到上线

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/ti/tinyfish-cookbook

第 2 步：本地先跑通（推荐）

以 viet-bike-scout（越南摩托车租赁比价工具）为例：

cd viet-bike-scout npm install npm run dev # 打开 http://localhost:3000

第 3 步：导入 Vercel

在 Vercel 控制台点击Add New Project，导入仓库后，Framework Preset 会自动识别为 Next.js，关键动作只有一个：在Root Directory中指定你选中的子目录（如viet-bike-scout），然后在 Environment Variables 页面粘贴密钥，即可部署。

环境变量管理：.env.example 是最佳地图

每个项目根目录都提供了环境变量模板文件，先读它再配置，是最快的上手方式：

• viet-bike-scout/.env.example — 只需TINYFISH_API_KEY
• tinyskills/.env.local.example — 需要TINYFISH_API_KEY+OPENAI_API_KEY或OPENROUTER_API_KEY
• research-sentry/.env.example — TinyFish + OpenAI（Whisper 语音转写）
• worldcup-briefing/README.md — 最复杂：数据库、加密密钥、多个第三方服务

本地与线上的对应关系

两个容易踩的细节：

1. Vercel 的环境变量要区分环境（Production / Preview / Development）。调试预览分支报"缺密钥"，往往是因为只在 Production 勾了配置。
2. .env.local已被 .gitignore 默认忽略，本地密钥不会误提交，但这也意味着线上密钥只能在 Vercel 控制台配置——忘了这一步是新手第一大坑。

API 密钥安全：3 条铁律

铁律一：密钥只放服务端环境变量。TINYFISH_API_KEY只在 API Route 中使用，绝不能出现在前端代码里。带NEXT_PUBLIC_前缀的变量会被打包进浏览器代码，对任何人都可见——所以这类前缀只用于真正要公开的变量（如 worldcup-briefing/README.md 中的NEXT_PUBLIC_BASE_URL）。

铁律二：启动时校验，快速失败。viet-bike-scout 用 Zod 在 viet-bike-scout/src/lib/env.ts 中做校验：密钥缺失时抛出清晰错误（列出具体缺哪个变量），而不是等到调用 API 时才收到 401。这是仓库内值得照抄的模式。

铁律三：需要"保管用户密钥"时，必须加密存储。worldcup-briefing 允许用户在界面里填自己的 TinyFish / VideoDB 密钥，源码用 AES-256-GCM 加密后才写入数据库，并用 32 字节十六进制ENCRYPTION_SECRET作为加密主密钥——详见其 README 的环境变量清单。

长任务坑位：maxDuration 与流式输出

Cookbook 里大量应用会并行派出多个浏览器 Agent，单次请求可能持续几十秒到几分钟。Vercel 默认函数超时时间很短，不配置必超时。仓库给了两套标准解法：

解法 A：路由文件内声明（Next.js 原生）

viet-bike-scout/src/app/api/search/route.ts 开头两行：

export const runtime = "nodejs"; export const maxDuration = 800;

解法 B：vercel.json 集中配置（多路由场景）

research-sentry/vercel.json 为语音/文本搜索路由设了 300 秒，摘要路由 120 秒，按需分级。

配合 SSE 流式返回：Agent 每完成一个站点就推送一条 Server-Sent Event，界面立刻刷新局部结果——用户体感远快于"等最慢的一个"，也不会撞上超时墙。这正是 viet-bike-scout 的 src/app/api/search/route.ts 的设计。

💡 注意：maxDuration超过免费版上限的路由，需要升级 Vercel 套餐。部署后如出现Function invoked time exceeded错误，优先检查这里。

常见坑位排查清单 🔍

部署完成后的验证清单 ✅

1. 打开线上页面，执行一次核心搜索（如选城市触发比价）；
2. 浏览器 DevTools → Network 中确认/api/*返回 200 且 SSE 事件持续流入；
3. Vercel 控制台 → Deployments → 查看函数日志，确认无Missing or invalid environment variables；
4. 预览环境（Preview URL）也测一遍，确保多环境密钥配置无误。

按以上流程，你可以把仓库里任意一个 Next.js 样例（比价工具、AI 问答、技能生成器等）在 15 分钟内部署上线，并建立起一套可复用的密钥管理与超时排查习惯。更多样例的部署说明，可直接阅读对应目录下的 README（如 silicon-signal/README.md、research-sentry/README.md）。

【免费下载链接】tinyfish-cookbookA collection of sample apps and recipes built with the TinyFish web agent. Open-source examples for you to learn & build!项目地址: https://gitcode.com/gh_mirrors/ti/tinyfish-cookbook