6.1 .env 文件配置

---

1. 为什么要学这个?

你正在开发一个调用OpenAI接口的应用。为了图省事,你直接把Key写在了代码里:

const apiKey = "sk-abcdefg123456..."; // 永远不要这样做!

你开心地把代码提交到了GitHub公开仓库。

5分钟后,你收到了一封邮件:"您的OpenAI额度已耗尽"。

你一脸懵逼,查了日志才发现,几百个来自俄罗斯和印度的IP在疯狂刷你的接口。

这就是硬编码密钥(Hardcoding Secrets)的代价。

---

2. 核心概念

2.1 环境变量(.env)

技术定义:环境变量是操作系统或运行环境提供给应用程序的动态命名值。在Node.js/Next.js开发中,通常使用.env文件来存储敏感配置,这些变量在代码中通过process.env.VARIABLE_NAME访问。

就像饭店的秘密配方。

• 代码(Code):是菜谱中公开的部分,比如"宫保鸡丁需要鸡肉、花生、辣椒",所有人都能看
• 环境变量(.env):是厨师手里的秘密酱汁,比如"秘制酱料A",这个瓶子只有后厨(服务器)有,绝不给客人(Github)看

2.2 保险箱机制

graph TD
    subgraph Local["你的电脑(Local)"]
        Dev[".env文件(保险箱)"] -->|注入| App["运行中的App"]
        Code["代码文件"] --> App
    end
    
    subgraph git["GitHub(公开)"]
        Code -->|git push| Repo["远程仓库"]
        Dev -.->|被.gitignore拦截| Repo
    end
    
    style Dev fill:#ef9a9a
    style Repo fill:#90caf9

---

3. 实战步骤

第一步:创建保险箱

在项目根目录新建一个.env文件(注意前面有个点):

OPENAI_API_KEY=sk-123456789...
DATABASE_URL=postgres://user:password@localhost:5432/mydb

第二步:设置屏蔽罩

打开根目录下的.gitignore文件,确保里面有一行:

.env
.env.local
*.pem

**这一步至关重要!**它告诉Git:".env是我的私人物品,不要打包带走。"

第三步:代码中取钥匙

在Next.js中,直接使用:

// ❌ 错误:直接写死
// const key = "sk-123..."

// ✅ 正确:从保险箱里拿
const key = process.env.OPENAI_API_KEY;

第四步:给队友留模具(.env.example)

既然.env不能上传,队友拉代码后怎么知道要配什么?

创建一个.env.example文件,只留变量名,不填值:

# .env.example (这个要提交到GitHub)
OPENAI_API_KEY=
DATABASE_URL=

---

4. 适用场景

🎯 场景	推荐做法
API密钥	OpenAI Key, AWS Secret Key等
数据库密码	连接PostgreSQL或MongoDB的URL
支付凭证	Stripe或支付宝的私钥
环境区分	开发环境用测试库(DB_TEST),生产环境用正式库(DB_PROD)

---

5. 避坑指南

✅ 推荐做法	❌ 禁忌
必须加入.gitignore	觉得"我就测试一下"先提交再说(Git有历史记录,撤回也没用)
变量名全大写+下划线(API_KEY)	使用驼峰命名(apiKey)或包含空格
修改.env后重启终端	以为保存文件就会实时生效(环境变量是启动时加载的)

---

6. 真实案例

---

7. 本章小结

1. 🔐 最后防线:环境变量是将敏感数据与业务逻辑解耦的唯一正确方式
2. 🚫 Git禁区:.env文件必须死死锁在本地,绝对不能出现在.gitignore之外
3. 🔄 重启生效:修改了环境变量,必须重启开发服务器(Ctrl+C -> pnpm dev)
4. 📝 .env.example:给队友留模具,只留变量名不填值