Skip to main content

环境变量: 保管你 API Key 的保险箱

在之前的文章中，我们学会了使用 API 和 SDK 来与 AI 模型对话。在代码示例中，我们都用了一行看起来很神秘的代码来获取 API Key：

api_key = os.getenv("OPENAI_API_KEY")

为什么不直接把密钥写在代码里，比如 api_key = "sk-..."？这背后，隐藏着软件开发中一个最基础、也最重要的安全实践：使用环境变量 (Environment Variable)。

核心比喻：绝不能把信用卡粘在公开的菜谱上​

想象一下，你是一家餐厅的主厨，你的 API Key 是那张能支付所有账单的、极其珍贵的餐厅信用卡。而你的代码，是那本需要给所有帮厨、学徒甚至美食评论家看的公开菜谱。

你会把这张信用卡，直接用胶带粘在公开菜谱的第一页上吗？

绝对不会！因为任何一个拿到菜谱的人，都能得到你的信用卡并肆意挥霍。这种把密钥直接写在代码里的行为，我们称之为 “硬编码”(Hardcoding) ，是软件开发中的头号大忌。

正确的做法是：将代码和机密信息完全分离。而实现这一点的行业标准，就是使用环境变量。

环境变量，就是你电脑操作系统（或云端服务器）里，那个用来存放机密信息的、上了锁的“保险箱”。

  • 你的代码 (公开的菜谱)：只包含逻辑，不包含任何机密。
  • API Key (信用卡)：被安全地存放在“保险箱”里。
  • 代码中的指令：os.getenv("OPENAI_API_KEY") 这行代码，就是在告诉程序：“去，到操作系统的‘保险箱’里，把标签为 OPENAI_API_KEY 的那张卡取出来用。”

这样，即使你的“菜谱”（代码）被公开到全世界（例如上传到 GitHub），你的“信用卡”（API Key）也依然安全地待在你的“保险箱”里。

一个具体的安全实践示例​

让我们通过一个简单的例子，看看这个“保险箱”是如何运作的。

第1步：【错误的做法】硬编码密钥​

看看下面这段代码，它直接把 API Key 写了进去。请永远不要这样做！

# 危险！这是一个硬编码的例子，切勿模仿！
from openai import OpenAI

# 密钥直接暴露在代码中
client = OpenAI(api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx") 

# ...后续代码...

如果这份代码被上传到 GitHub，你的密钥将在几秒钟内被网络上的恶意机器人扫描到，你的账户会立刻被盗用。

第2步：【正确的做法】使用环境变量​

现在，我们用正确的方式重写它。

# 安全！这是一个使用环境变量的好例子
import os
from openai import OpenAI

# 1. 从“保险箱”（环境变量）中安全地获取密钥
api_key = os.getenv("OPENAI_API_KEY")

# 2. 检查密钥是否存在
if not api_key:
    raise ValueError("请设置 OPENAI_API_KEY 环境变量")

# 3. 将获取到的密钥传递给客户端
client = OpenAI(api_key=api_key)

# ...后续代码...
print("成功使用环境变量初始化客户端！")

这段代码是干净、安全的。它可以被自由地分享和版本控制，没有任何风险。

实践指南：如何设置你的“保险箱”​

那么，如何把你的 API Key 放入操作系统的“保险箱”里呢？这分为两种场景：

场景一：在你的电脑上设置 (本地开发)​

对于 macOS 或 Linux 用户 (推荐永久设置):

  1. 打开终端 (Terminal)。
  2. 编辑你的 Shell 配置文件，通常是 ~/.zshrc 或 ~/.bash_profile。例如：nano ~/.zshrc
  3. 在文件末尾添加一行： 
    export OPENAI_API_KEY="sk-..."
  4. 保存文件，然后重启终端或运行 source ~/.zshrc 使其生效。

对于 Windows 用户 (图形界面):

  1. 在搜索栏搜索并打开“编辑系统环境变量”。
  2. 点击“环境变量...”按钮。
  3. 在“用户变量”下，点击“新建...”。
  4. 变量名：OPENAI_API_KEY
  5. 变量值：sk-...
  6. 一路确定保存，并重启你的代码编辑器或命令行工具。

场景二：在线上平台设置 (部署上线)​

当你的应用需要部署到云端时，每个平台都提供了自己的“保险箱”。

  • 对于 Vercel, Netlify, Render 等现代托管平台: 通常，在你的项目设置页面，会有一个专门的 "Environment Variables" 菜单。你只需在网页上添加你的 OPENAI_API_KEY 和对应的值即可。平台会确保你的线上代码能读到它。

  • 对于传统服务器或 Docker (使用 .env 文件): 这是一种通用的行业标准。

    1. 在你的项目根目录，创建一个名为 .env 的文件。
    2. 在 .env 文件里写入：OPENAI_API_KEY="sk-..."
    3. 【至关重要】：将 .env 添加到你的 .gitignore 文件中！这可以防止你把这个“便携式保险箱”意外上传到 GitHub。 
      # 忽略所有 .env 文件，保护你的密钥！
      .env
    4. 你的代码需要使用一个库（如 Python 的 python-dotenv）来自动加载 .env 文件。

推荐资源​

  • GitHub Doc on secrets: Managing your secrets - 了解如何在 GitHub Actions 等自动化流程中安全地使用密钥。

相关词条​