# 前端部署配置（Vercel） 本文只覆盖 `frontend` 目录对应的 Next.js 前端部署。 ## 一、部署目标 推荐方案： 1. GitHub Actions 负责 `CI` 2. Vercel 负责前端 `CD` 3. FastAPI 后端单独部署在 VPS / Docker 主机 前端本身不直接访问天气源，而是通过 Next Route Handlers 转发到后端： 1. 浏览器 -> Vercel 上的 Next.js 前端 2. Next `/api/*` -> `POLYWEATHER_API_BASE_URL` 3. FastAPI 后端 -> 分析 / 支付 / 鉴权服务 ## 二、Vercel 项目设置 在 Vercel 导入 GitHub 仓库后，使用下面的设置： - Framework Preset: `Next.js` - Root Directory: `frontend` - Build Command: `npm run build` - Install Command: `npm install` 如果仓库已经连接过 Vercel，通常只需要确认 `Root Directory` 仍然是 `frontend`。 ## 三、最小必填环境变量 只部署天气看板和基础登录时，先填下面 4 项： ```env POLYWEATHER_API_BASE_URL=https:// NEXT_PUBLIC_SUPABASE_URL=https://.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY= POLYWEATHER_AUTH_ENABLED=true ``` 建议显式补： ```env POLYWEATHER_AUTH_REQUIRED=true ``` 说明： - `POLYWEATHER_API_BASE_URL`：前端所有 `/api/*` Route Handler 转发时依赖它，没填会直接返回 500。 - `NEXT_PUBLIC_SUPABASE_URL` / `NEXT_PUBLIC_SUPABASE_ANON_KEY`：Supabase 客户端依赖它们。 - `POLYWEATHER_AUTH_ENABLED`：关闭时，前端不会启用登录能力。 - `POLYWEATHER_AUTH_REQUIRED`：控制 middleware 是否强制登录。 ## 四、按功能启用的可选环境变量 ### 1. 分享式看板 ```env POLYWEATHER_DASHBOARD_ACCESS_TOKEN= ``` 设置后，可通过 `/?access_token=` 打开带令牌的看板入口。 ### 2. 前后端 entitlement 校验 ```env POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN= ``` 仅当后端开启 entitlement / 订阅校验时需要。 ### 3. 钱包支付 ```env NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID= NEXT_PUBLIC_WALLETCONNECT_POLYGON_RPC_URL=https://polygon-bor-rpc.publicnode.com ``` 如果不启用钱包支付，可以留空。 ### 4. Telegram 入口 ```env NEXT_PUBLIC_TELEGRAM_GROUP_URL=https://t.me/ NEXT_PUBLIC_TELEGRAM_BOT_URL=https://t.me/WeatherQuant_bot ``` 只影响按钮跳转，不影响核心页面加载。 ## 五、推荐的三套配置口径 ### 1. 公开游客模式 ```env POLYWEATHER_API_BASE_URL=https://api.example.com POLYWEATHER_AUTH_ENABLED=false POLYWEATHER_AUTH_REQUIRED=false ``` 适合公开演示站。 ### 2. 正常登录模式 ```env POLYWEATHER_API_BASE_URL=https://api.example.com NEXT_PUBLIC_SUPABASE_URL=https://.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY= POLYWEATHER_AUTH_ENABLED=true POLYWEATHER_AUTH_REQUIRED=true ``` 适合正式前端站点。 ### 3. 登录 + entitlement 联动 ```env POLYWEATHER_API_BASE_URL=https://api.example.com NEXT_PUBLIC_SUPABASE_URL=https://.supabase.co NEXT_PUBLIC_SUPABASE_ANON_KEY= POLYWEATHER_AUTH_ENABLED=true POLYWEATHER_AUTH_REQUIRED=true POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN= ``` 适合前后端都启用了会员/订阅保护的生产环境。 ## 六、不要放进 Vercel 的变量 这些属于后端私密配置，不应该放到前端项目： - `SUPABASE_SERVICE_ROLE_KEY` - `TELEGRAM_BOT_TOKEN` - `POLYWEATHER_BACKEND_ENTITLEMENT_TOKEN` 以外的后端 secret - 支付签名私钥 / 交易私钥 / 任何 bot 凭据 特别注意： - `NEXT_PUBLIC_*` 会暴露给浏览器 - 只有明确允许前端公开使用的值，才应加 `NEXT_PUBLIC_` ## 七、上线前检查 Vercel 部署前至少确认： 1. `POLYWEATHER_API_BASE_URL` 指向可访问的后端生产地址 2. `frontend/.env.example` 和 Vercel Project Settings 中的实际值一致 3. GitHub Actions 中 `frontend-quality` 已通过 4. 如果启用鉴权，Supabase redirect URL 已包含前端域名 ## 八、常见问题 ### 1. 页面打开后 API 全部 500 先检查： ```env POLYWEATHER_API_BASE_URL ``` 这是最常见原因。 ### 2. Vercel 构建通过，但登录失败 先检查： - `NEXT_PUBLIC_SUPABASE_URL` - `NEXT_PUBLIC_SUPABASE_ANON_KEY` - Supabase 项目里的站点 URL / redirect URL ### 3. 钱包入口显示未配置 先检查： ```env NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID ``` 这是钱包连接的必需项。