出海
Supabase 接入 Google 一键登录完整配置指南
Supabase 邮箱注册与邮箱确认链接完整配置指南
Vercel + Supabase 环境变量与部署配置指南
本文档使用 MrDoc 发布
-
+
首页
Vercel + Supabase 环境变量与部署配置指南
# Vercel + Supabase 环境变量与部署配置指南 如果你正在用： - `Nuxt` - `Next.js` - `Vercel` - `Supabase` 来做一个面向海外用户的 Web 应用，那么环境变量和部署配置是最容易卡人的一环。 这篇文章整理一套实战可用的方案，重点解决这些问题： - 本地开发怎么配 `.env.local` - Vercel 线上环境变量怎么配 - `Supabase Auth` 和 `Supabase Postgres` 分别需要哪些参数 - 为什么本地能跑，Vercel 却报错 - `DATABASE_URL` 应该填哪条 --- ## 一、整体思路 最推荐的做法是把配置分成两类： ### 1. 前端公开配置 这类配置会暴露到浏览器，可以放 `NUXT_PUBLIC_*` 或类似前缀。 例如： - `NUXT_PUBLIC_SUPABASE_URL` - `NUXT_PUBLIC_SUPABASE_ANON_KEY` ### 2. 服务端私密配置 这类配置只能在服务端使用，不能暴露到前端。 例如： - `DATABASE_URL` - `FAL_KEY` - `R2_SECRET_ACCESS_KEY` - `SUPABASE_SERVICE_ROLE_KEY` 一句话理解： - 能给前端看的，用 `PUBLIC` - 不能给前端看的，只放服务端环境变量 --- ## 二、本地开发和线上部署应该分开 建议你至少分两套环境： ### 本地开发 - `.env.local` ### 线上部署 - Vercel 后台 `Environment Variables` 不要把真正的私密环境变量直接提交到 Git 仓库。 推荐做法： - 仓库里保留 `.env.example` - 本地自己维护 `.env.local` - 线上在 Vercel 面板配置环境变量 --- ## 三、Supabase 常见需要的环境变量 如果你同时使用了： - Supabase Auth - Supabase Postgres 那么最常见的一组变量是下面这些。 ### 前端公开变量 ```env NUXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co NUXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxx ``` 说明： - `SUPABASE_URL`：Supabase 项目地址 - `ANON_KEY`：前端可公开使用的 publishable key 这两个值通常在： `Supabase -> Settings -> API` 里获取。 ### 服务端数据库变量 ```env DATABASE_URL=postgresql://... ``` 这个用于： - Nuxt server routes - Prisma / Drizzle / pg 客户端 - 服务端查询数据库 --- ## 四、最关键的一点：Vercel 上的 `DATABASE_URL` 不能用本地内网地址 例如下面这种： ```env DATABASE_URL=postgresql://user:password@10.168.1.194:5432/imvz ``` 它只适合： - 你自己的本地网络 - 局域网开发环境 **不适合 Vercel。** 因为： - `10.x.x.x` 是内网地址 - Vercel 的 Serverless Functions 跑在云端 - 云端没法直接访问你家里或公司内网里的 PostgreSQL 所以在 Vercel 上，你必须换成： - `Supabase Postgres` - `Neon Postgres` - 或其他公网可访问数据库 --- ## 五、Supabase 的 `DATABASE_URL` 应该用哪条 Supabase 一般会提供多种连接方式： - Direct connection - Session pooler - Transaction pooler 对于 `Vercel / Serverless` 场景，更推荐： **Transaction pooler** 因为： - Serverless 请求短、无状态 - 不适合大量长连接 - pooler 更适合连接管理 一个典型例子会像这样： ```env DATABASE_URL=postgresql://postgres.your-project-ref:YOUR_PASSWORD@aws-1-us-east-1.pooler.supabase.com:6543/postgres?sslmode=no-verify ``` 注意： - 用的是 `pooler.supabase.com` - 端口通常是 `6543` - serverless 下常见会配 `sslmode=no-verify` --- ## 六、为什么 `sslmode=require` 有时会报错 有些环境下，你会遇到类似： ```txt self-signed certificate in certificate chain ``` 这说明： - 已经连到了数据库 - 但是 TLS 证书链校验没有通过 在这种情况下，经常会把： ```env ?sslmode=require ``` 改成： ```env ?sslmode=no-verify ``` 也就是： ```env DATABASE_URL=postgresql://...@...pooler.supabase.com:6543/postgres?sslmode=no-verify ``` 这样仍然走 SSL，但不严格校验证书链。 --- ## 七、本地 `.env.local` 示例 如果你本地开发也直接连 Supabase，可以像这样： ```env DATABASE_URL=postgresql://postgres.your-project-ref:YOUR_PASSWORD@aws-1-us-east-1.pooler.supabase.com:6543/postgres?sslmode=no-verify NUXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co NUXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxx FAL_KEY=your_fal_key R2_ACCOUNT_ID=xxx R2_ACCESS_KEY_ID=xxx R2_SECRET_ACCESS_KEY=xxx R2_BUCKET_NAME=imvz R2_PUBLIC_BASE_URL=https://pub-xxx.r2.dev ``` 如果你本地想继续连局域网库，也可以保留： ```env DATABASE_URL=postgresql://imvz:password@10.168.1.194:5432/imvz ``` 但要知道： - 本地数据和线上就不是一套 - 调试时会更容易出现“登录在 Supabase，业务数据在另一套 PG”的割裂问题 --- ## 八、Vercel 后台要配哪些变量 进入： `Vercel -> Project -> Settings -> Environment Variables` 一般需要把这些加进去： ```env DATABASE_URL=postgresql://postgres.your-project-ref:YOUR_PASSWORD@aws-1-us-east-1.pooler.supabase.com:6543/postgres?sslmode=no-verify NUXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co NUXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxx FAL_KEY=your_fal_key R2_ACCOUNT_ID=xxx R2_ACCESS_KEY_ID=xxx R2_SECRET_ACCESS_KEY=xxx R2_BUCKET_NAME=imvz R2_PUBLIC_BASE_URL=https://pub-xxx.r2.dev ADMIN_EMAILS=admin@example.com ``` 然后重新部署。 注意： - 改了环境变量后，老部署不会自动读取新值 - 通常需要 `Redeploy` 或重新 push 一次 --- ## 九、为什么仓库里的 `.env.local` 不该上传 `.env.local` 一般应该放在 `.gitignore` 里。 原因： - 里面可能有数据库密码 - 有第三方 API Key - 有对象存储密钥 - 有管理员邮箱白名单 所以推荐结构是： ### `.env.example` 只放模板： ```env DATABASE_URL= NUXT_PUBLIC_SUPABASE_URL= NUXT_PUBLIC_SUPABASE_ANON_KEY= FAL_KEY= ``` ### `.env.local` 只留在本地，不提交。 --- ## 十、Vercel 构建时报 `.env.local not found` 怎么办 有些项目会在 `package.json` 里把 `.env.local` 写死，例如： ```json "build": "node --env-file=.env.local ./node_modules/nuxt/bin/nuxt.mjs build" ``` 这在本地没问题，但到了 Vercel 上，仓库里通常没有 `.env.local`，就会直接报： ```txt node: .env.local: not found ``` 更稳的做法是： - 本地有 `.env.local` 时自动加载 - 线上没有 `.env.local` 时，直接使用 Vercel 注入的环境变量 也就是说，不要把 `.env.local` 当成线上构建的必需文件。 --- ## 十一、常见报错排查 ### 1. Missing Supabase public runtime config 原因： - `NUXT_PUBLIC_SUPABASE_URL` 或 `NUXT_PUBLIC_SUPABASE_ANON_KEY` 没配 检查： - 本地 `.env.local` - Vercel Environment Variables ### 2. 线上 `/api/health/db` 返回 500 常见原因： - `DATABASE_URL` 没配 - 配成了本地内网地址 - SSL 参数不对 - Supabase 连接串选错了 direct connection ### 3. self-signed certificate in certificate chain 解决： - 把 `sslmode=require` 改成 `sslmode=no-verify` ### 4. Connection terminated unexpectedly 常见原因： - 本机到 Supabase pooler 的网络不稳定 - TLS 连接断开 这种情况本地可以考虑： - 暂时切回 LAN Postgres - 或单独本地 PostgreSQL 线上一般还是建议继续用 Supabase。 ### 5. 前端登录成功了，但服务端接口报错 这说明可能出现了： - `Auth` 和 `Database` 用的不是一套环境 - 本地登录走 Supabase，但数据库走另一套库 - 服务端环境变量没和前端保持一致 --- ## 十二、推荐的生产环境策略 如果你准备正式上线，推荐这样分层： ### 前端 - `NUXT_PUBLIC_SUPABASE_URL` - `NUXT_PUBLIC_SUPABASE_ANON_KEY` ### 服务端 - `DATABASE_URL` - `FAL_KEY` - `R2_*` - `ADMIN_EMAILS` ### 数据库 - 用户、订阅、任务、模型配置都统一放到一套数据库 ### 模型配置 - 模型 `ID` 建议放数据库管理 - 真正的 `FAL_KEY` 保留在环境变量 这样以后： - 模型切换不用每次改 Vercel 配置 - 只需要管理员后台改数据库配置即可 --- ## 十三、推荐的最小可用配置清单 ### 本地开发 ```env DATABASE_URL=postgresql://postgres.your-project-ref:YOUR_PASSWORD@aws-1-us-east-1.pooler.supabase.com:6543/postgres?sslmode=no-verify NUXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co NUXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxx ``` ### Vercel 生产 ```env DATABASE_URL=postgresql://postgres.your-project-ref:YOUR_PASSWORD@aws-1-us-east-1.pooler.supabase.com:6543/postgres?sslmode=no-verify NUXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co NUXT_PUBLIC_SUPABASE_ANON_KEY=sb_publishable_xxx FAL_KEY=your_fal_key R2_ACCOUNT_ID=xxx R2_ACCESS_KEY_ID=xxx R2_SECRET_ACCESS_KEY=xxx R2_BUCKET_NAME=imvz R2_PUBLIC_BASE_URL=https://pub-xxx.r2.dev ADMIN_EMAILS=admin@example.com ``` --- ## 十四、总结 `Vercel + Supabase` 这套组合很好用，但最容易出问题的就是： 1. 把本地库地址配到线上 2. 选错数据库连接串 3. 环境变量只配了一半 4. 改完环境变量却没重新部署 5. 把私密密钥暴露到前端 实战里最稳的原则就是： - `Auth` 和 `Database` 尽量统一环境 - `public` 配置给前端 - `secret` 配置只给服务端 - `.env.local` 只留本地 - Vercel 用后台环境变量管理正式配置 把这些关系理顺之后，部署和调试都会顺很多。
superadmin
2026年4月11日 22:04
转发文档
收藏文档
上一篇
下一篇
手机扫码
复制链接
手机扫一扫转发分享
复制链接
Markdown文件
分享
链接
类型
密码
更新密码