适合个人开发者、AI 工具作者、脚本自动化玩家。
如果你现在还在代码里硬写 api_key 和 base_url，这篇可以直接改掉你的习惯。

为什么要把配置单独放出来？

很多项目一开始都能跑，但后面越改越乱，最常见的问题就是：

• API Key 直接写在代码里
• Base URL 到处散落
• 模型名改一次要找很多文件
• 本地调试和线上环境不一致

这类问题看起来不大，但项目一旦开始扩展，维护成本会很快上来。

所以更稳的做法是：
把配置集中放进 .env，代码只负责读取。

---

一、.env 适合放什么？

你可以把它理解成项目的“环境变量配置文件”。

通常适合放这些内容：

• API_KEY
• BASE_URL
• MODEL
• TIMEOUT
• MAX_RETRIES

例如：

API_KEY=sk-xxxxxx
BASE_URL=https://your-api-domain.com/v1
MODEL=your-model-name
TIMEOUT=20
MAX_RETRIES=3

这样一来，代码里就不用写死敏感信息了。

---

二、为什么个人开发者特别适合这样做？

1. 安全一点

不会把 Key 直接暴露在源码里。

2. 方便切换环境

本地、测试、线上可以用不同配置。

3. 修改成本低

换模型、换地址、调超时，不用改业务代码。

4. 适合团队协作

别人拉你的代码后，只要补自己的 .env 就能跑。

---

三、Python 怎么读取 .env？

最常见的方式是用 python-dotenv。

1）安装依赖

pip install python-dotenv

2）创建 .env

API_KEY=sk-xxxxxx
BASE_URL=https://your-api-domain.com/v1
MODEL=your-model-name
TIMEOUT=20
MAX_RETRIES=3

3）读取配置

import os
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("API_KEY")
BASE_URL = os.getenv("BASE_URL")
MODEL = os.getenv("MODEL")
TIMEOUT = int(os.getenv("TIMEOUT", "20"))
MAX_RETRIES = int(os.getenv("MAX_RETRIES", "3"))

print(API_KEY, BASE_URL, MODEL, TIMEOUT, MAX_RETRIES)

---

四、把配置接到 OpenAI-compatible API 里

下面给你一个完整一点的例子。

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.getenv("API_KEY"),
    base_url=os.getenv("BASE_URL"),
    timeout=float(os.getenv("TIMEOUT", "20"))
)

model = os.getenv("MODEL", "your-model-name")

response = client.chat.completions.create(
    model=model,
    messages=[
        {"role": "system", "content": "你是一个专业的技术助手。"},
        {"role": "user", "content": "帮我写一个 Python 示例。"}
    ]
)

print(response.choices[0].message.content)

这段代码的核心思路就是：

• 配置从 .env 读取
• 业务代码不写死敏感信息
• 模型和接口地址随时可改

---

五、推荐的项目结构

如果你想写得更规整一点，可以这样分：

project/
├── .env
├── config.py
├── llm_client.py
├── main.py
└── requirements.txt

.env

放环境变量。

config.py

统一读取配置。

llm_client.py

封装模型调用。

main.py

负责你的业务逻辑。

这样后面扩展起来会很舒服。

---

六、几个容易踩坑的地方

1. .env 不要提交到 Git

记得加到 .gitignore。

2. 不要把 Key 打印到日志里

调试时也要注意。

3. 配置读取后要做校验

比如 Key 为空时直接报错，不要等请求失败才发现。

4. 开发环境和生产环境要分开

不要所有环境都共用一套配置。

---

七、一个更稳的写法：统一校验配置

你可以把配置校验单独写出来。

import os
from dotenv import load_dotenv

load_dotenv()

def get_config():
    api_key = os.getenv("API_KEY")
    base_url = os.getenv("BASE_URL")
    model = os.getenv("MODEL")

    if not api_key:
        raise ValueError("API_KEY is required")
    if not base_url:
        raise ValueError("BASE_URL is required")
    if not model:
        raise ValueError("MODEL is required")

    return {
        "api_key": api_key,
        "base_url": base_url,
        "model": model,
        "timeout": int(os.getenv("TIMEOUT", "20")),
        "max_retries": int(os.getenv("MAX_RETRIES", "3")),
    }

这样你在启动时就能提前发现问题。

---

八、这套方式适合哪些项目？

特别适合这些场景：

• AI 工具站
• 自动化脚本
• Agent 工作流
• 模型接入项目
• 个人效率工具
• 技术副业项目

如果你的项目后面还会继续扩展，这种配置方式基本是最省心的。

---

九、结语

很多项目后面不好维护，不是因为功能复杂，而是因为一开始把配置写得太乱。

如果你能从一开始就把：

• Key
• Base URL
• Model
• 超时
• 重试次数

统一放到 .env，后面会轻松很多。

如果你正在做 AI 工具、脚本自动化或者个人项目，可以直接留言或私信，我可以把我整理好的配置模板发给你。

免责声明

本文内容仅用于技术交流与经验分享，不构成任何商业承诺。具体使用效果请以实际测试为准。