6.5 环境变量同步到云端

---

1. 为什么要学这个?

你在本地开发时,一切正常。数据库连得上,AI接口调得通。

你满怀信心地git push,Vercel自动部署。一分钟后,你打开线上网址,所有功能全部报错:500 Internal Server Error。

日志显示:Error: DATABASE_URL is undefined。

掌握云端环境变量配置,才算真正学会部署。

---

2. 核心概念

2.1 环境变量的两个世界

就像你家的钥匙和公司的钥匙。

• 本地开发:代码从.env文件读取密钥
• 云端部署:代码从Vercel配置面板读取密钥
• 问题:你上传了代码,但没在Vercel配置密钥

技术定义:环境变量是应用运行时需要的配置信息(如数据库地址、API密钥)。本地开发时从.env文件读取,云端部署时需要在托管平台的配置面板中单独设置。

2.2 本地和云端的环境变量流程

graph TD
    subgraph Local["本地开发"]
        Code1["代码"] --> Read1["读取.env文件"]
        Env1[".env文件<br/>DATABASE_URL=xxx<br/>API_KEY=yyy"] --> Read1
        Read1 --> Run1["应用运行"]
    end
    
    subgraph Deploy["部署过程"]
        Push["git push"] --> GitHub["GitHub仓库"]
        GitHub -.->|.gitignore拦截| NoEnv["❌ .env文件不会上传"]
        GitHub --> Vercel["Vercel拉取代码"]
    end
    
    subgraph Cloud["云端运行"]
        Vercel --> Code2["代码"]
        Dashboard["Vercel配置面板<br/>手动填写环境变量"] --> Inject["注入到运行环境"]
        Code2 --> Read2["读取环境变量"]
        Inject --> Read2
        Read2 --> Run2["应用运行"]
    end
    
    style NoEnv fill:#ffcdd2
    style Env1 fill:#c8e6c9
    style Dashboard fill:#fff9c4

---

3. 解决方案

在Vercel手动配置环境变量

1. 登录Vercel,选择你的项目

2. 点击顶部的Settings

3. 左侧菜单找到Environment Variables

4. 点击Add New,填写:

   • Name: DATABASE_URL(变量名,要和本地.env里的一模一样)
   • Value: postgresql://...(你的数据库地址)
   • Environment: 勾选Production(生产环境)

5. 关键步骤:填完后,去Deployments页面,找到最新的部署记录,点击右边的三个点,选择Redeploy

为什么要Redeploy? 修改环境变量不会自动重启应用,必须手动Redeploy才能让新配置生效。

---

4. 常见场景

场景	怎么办
第一次部署项目	把本地.env里的所有变量在Vercel后台填一遍
API密钥泄露了	在Vercel更新密钥,然后Redeploy
想测试支付功能但不想真扣钱	为Preview环境单独配置测试用的支付密钥

---

5. 避坑指南

✅ 推荐做法	❌ 禁忌
改完配置立刻Redeploy	以为点了Save就自动生效
线上用正式库,线下用测试库	线上线下混用同一个数据库
用Vercel CLI批量导入变量	有50个变量还一个个手动复制

---

6. 真实案例

---

7. 本章小结

1. 🔑 两把钥匙:本地用.env文件,云端用Vercel配置面板
2. 🚫 不会自动上传:.env被.gitignore拦住,需要手动在云端配置
3. 🔄 记得重启:改完配置要Redeploy,否则不生效
4. 🎯 环境隔离:测试和生产用不同的数据库和密钥