第5课：线上环境变量和 API Key

先看一张直觉图

先不要急着把 API Key 复制来复制去。

请先看这张图：

这张图想告诉你一件事：

本地 .env 是你电脑上的钥匙盒，线上环境变量是部署平台那边的钥匙盒。

项目在本地运行时，能读你电脑上的 .env。

项目上线后，运行位置变了。

所以它不能自动读到你电脑里的 .env。

开始之前

第二册里，你可能已经见过 .env。

里面可能有：

OPENAI_API_KEY=sk-...
DATABASE_URL=...
VITE_API_URL=...

这些内容通常不是普通文字。

有些是钥匙。

有些是地址。

有些是项目运行时需要的配置。

本课先记住一句话：

变量名可以写出来，真实值要保护好。

例如：

OPENAI_API_KEY

这是变量名，可以讨论。

但后面真正的 key 值，不应该放进公开代码、公开文档、截图或聊天记录。

先看一个小故事

小林的小工具本地能调用 AI。

他本地有一个 .env 文件：

OPENAI_API_KEY=自己的真实 key

本地运行时，一切正常。

后来他把项目部署到线上。

页面能打开，但一点击“生成标题”，就失败了。

小林第一反应是：

是不是平台坏了？
是不是 AI 接口坏了？
是不是 Codex 写错了？

有人提醒他先检查：

你在线上平台配置 OPENAI_API_KEY 了吗？

小林说：

我本地有 .env 啊。

课程提示：

本地 .env 在你的电脑上。
线上项目在平台上运行。
平台那里也需要自己的环境变量配置。

小林这才明白：

我不是只要部署代码。
我还要检查线上运行时需要的配置。

一、.env 是什么

.env 可以先理解成：

本地配置文件。

它常常用来保存：

• API Key。
• 接口地址。
• 模型名称。
• 数据库连接地址。
• 是否开启某个功能。

你可以这样理解：

.env = 我电脑上的小钥匙盒

它的好处是：

不把敏感配置直接写进代码里。

但它也有一个限制：

.env 通常只在本地项目里生效，不会自动跑到线上平台。

二、环境变量是什么

环境变量可以先理解成：

项目运行时能读取的一组配置。

本地有本地的环境变量。

线上有线上的环境变量。

部署平台可能会有一个位置叫：

Environment Variables
Project Settings
Variables
Secrets

不同平台叫法不完全一样。

但意思接近：

把线上运行需要的配置，放到平台提供的安全位置。

第三册不要求你背每个平台按钮。

你只要知道：

上线后，必要配置要在部署平台那边也有。

三、API Key 是什么

API Key 可以先理解成：

调用某个服务的钥匙。

比如你的小工具要调用 AI 接口，可能需要一个 key。

这个 key 证明：

你有权限使用这个服务。

所以它很敏感。

如果别人拿到了你的真实 API Key，可能会：

• 使用你的额度。
• 调用你的服务。
• 造成费用或安全问题。

所以本课定一条规则：

变量名可以写，真实 key 不公开。

四、变量名和值不要混在一起

很多新手会把变量名和值混在一起。

其实它们不是一回事。

例如：

OPENAI_API_KEY=sk-abc123...

这里可以分成两部分：

部分	例子	能不能公开讨论
变量名	OPENAI_API_KEY	通常可以
真实值	sk-abc123...	不要公开

这一课填写练习表时，只写：

OPENAI_API_KEY

不要写真实值。

如果你要把真实值填到部署平台，也要在平台的安全配置页面填写，不要写进公开笔记。

五、哪些变量需要上线配置

不是所有变量都一定要上线。

你要让 AI 判断。

常见需要检查的有：

• AI 服务的 API Key。
• 后端接口地址。
• 数据库连接地址。
• 登录或第三方服务的密钥。
• 项目运行模式。

你可以让 AI 回答三个问题：

项目用了哪些环境变量？
每个变量大概做什么？
上线时哪些必须在平台配置？

如果 AI 要你贴真实值，你要提醒它：

我只提供变量名，不提供真实值。

六、线上缺少环境变量会怎样

线上缺少环境变量时，页面可能不一定完全打不开。

有时它会表现为：

• 页面能打开，但生成失败。
• AI 调用失败。
• 保存失败。
• 后端接口报错。
• 部署日志里出现 undefined、missing key、unauthorized。

所以以后你看到：

本地正常，线上某个功能失败

不要马上怀疑全部代码坏了。

你要加一个检查：

线上环境变量有没有配置？

七、动手练习：变量名和值分开

请先看这三行示例：

OPENAI_API_KEY=sk-xxxx
DATABASE_URL=postgres://xxxx
VITE_API_URL=https://api.example.com

然后把每行分成两列：

变量名	真实值
OPENAI_API_KEY	sk-xxxx
DATABASE_URL	postgres://xxxx
VITE_API_URL	https://api.example.com

再判断：

哪一列可以写进练习表？
哪一列不要公开？

参考答案：

变量名可以写进练习表。
真实值不要公开。

八、自己动手：填写线上环境变量检查表

现在轮到你的项目。

请不要把真实 API Key 发给朋友、同事或公开 AI 聊天。

只列变量名。

我的线上环境变量检查表

变量名	用途	本地是否有	线上是否已配置	是否包含真实密钥	是否可以公开

检查问题

问题	我的答案
我的项目是否使用 .env
哪些变量上线必须配置
哪些变量只是本地开发用
我有没有把真实密钥贴进公开聊天或公开文档
如果线上调用 AI 失败，可能和哪些变量有关

给 Codex 的提示词

请把下面这段发给 Codex。

请你先不要改代码。
请不要让我公开任何真实 API Key、Token、密码或数据库地址。

请检查这个项目是否使用了环境变量或 .env。
请告诉我：
1. 项目需要哪些环境变量名；
2. 每个变量大概负责什么；
3. 哪些变量上线时需要配置到部署平台；
4. 哪些变量不能公开；
5. 缺少这些变量时，线上可能出现什么现象。

如果项目里有 .env.example，请优先根据它判断。
请只列变量名，不要要求我粘贴真实值。
请最后帮我填写一张“线上环境变量检查表”。

如果你准备把配置填到部署平台，继续发：

请你先不要改代码。

我准备在部署平台配置环境变量。

部署平台：
【填写】

项目使用的变量名：
【只填写变量名，不填真实值】

本地是否有 .env：
【填写】

请帮我检查：
1. 哪些变量必须在线上配置；
2. 哪些变量看起来像密钥，不能公开；
3. 哪些变量可能只是本地开发用；
4. 配置完成后应该测试哪个功能；
5. 如果线上仍然失败，下一步应该看哪里。

请不要让我把真实值贴出来。

本课记住

词	你要记住的意思
.env	我电脑上的本地钥匙盒
线上环境变量	部署平台那边的钥匙盒
API Key	调用服务的钥匙

重要规则：

• 变量名可以写出来。
• 真实 API Key、Token、密码不要公开。
• 本课产出是线上环境变量检查表。

本课小结

这一课你不需要变成安全专家。

你只需要记住：

本地有 .env，不代表线上也有配置。
线上项目需要什么配置，要在部署平台的环境变量里检查。
变量名可以讨论，真实值要保护。

如果上线后某个 AI 功能失败，除了看代码和日志，还要检查：

线上环境变量是否缺失。

课后任务

请完成 3 件事：

1. 让 Codex 检查项目是否使用 .env 或环境变量。
2. 填写“线上环境变量检查表”。
3. 确认没有把真实 API Key 写进公开聊天、公开文档或截图。

如果你曾经公开过真实 key，请不要继续使用它。

请让 AI 帮你理解下一步：

我不小心公开了 API Key。请告诉我小白应该立刻做哪些安全处理，但不要展开企业安全课。

本课最低标准

完成本课，不是看你会不会配置所有平台。

最低合格标准是：

你能说出本地 .env 和线上环境变量不是一回事。
你能列出项目需要的变量名和用途。
你知道真实 API Key 不应该公开。
你能完成线上环境变量检查表。

如果你能完成这四件事，本课就达标。