当前位置：首页 > news >正文

[环境管理/Python] dotenv : Python 轻量级环境管理库

news 2026/7/15 18:54:08

1 概述: dotenv

dotenv 是一个轻量级且必备的工具，用于【管理环境变量】，特别适合初级开发者学习配置管理。

1.1 为什么要用 `dotenv`？

场景	问题	dotenv 解决方案
代码中硬编码密钥	泄露风险、难以维护	分离到 `.env` 文件
不同环境配置不同	改代码麻烦	一套代码，多套配置
团队协作	每个人配置不同	`.env` 本地管理，`.env.example` 共享模板

加载一次，随处读取，文件保密，集中管理，生产脱钩。

1.2 安装与基础用法

安装

pip install python-dotenv

最简示例

.env 文件

放在项目根目录，不要提交到 Git：

# 数据库配置
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
DEBUG=True
API_KEY=sk-1234567890abcdef

Python 代码：

from dotenv import load_dotenv
import os# 加载 .env 文件到环境变量
load_dotenv()# 像读取普通环境变量一样使用
db_url = os.getenv("DATABASE_URL")
debug_mode = os.getenv("DEBUG", "False") == "True"  # 带默认值
api_key = os.getenv("API_KEY")print(f"数据库: {db_url}")
print(f"调试模式: {debug_mode}")

1.3 核心 API 详解

`load_dotenv()` —— 最常用的加载方式

from dotenv import load_dotenv# 默认行为：从当前工作目录向上查找 .env 文件
load_dotenv()# 指定具体路径
load_dotenv(dotenv_path="/path/to/.env")# 自定义 .env 文件名
load_dotenv(dotenv_path=".env.local")# 不覆盖已存在的环境变量（安全模式）
load_dotenv(override=False)  # 默认 True，会覆盖系统环境变量

`find_dotenv()` —— 自动查找文件

from dotenv import load_dotenv, find_dotenv# 自动向上级目录查找 .env
env_path = find_dotenv(raise_error_if_not_found=True)
load_dotenv(env_path)

`set_key()` / `get_key()` —— 读写 .env 文件

from dotenv import set_key, get_key# 读取特定键
value = get_key(".env", "DATABASE_URL")# 修改或新增键值（会修改文件！）
set_key(".env", "NEW_VAR", "new_value")

4. 最佳实践（初级工程师必看）

✅ 正确的项目结构

my_project/
├── .env                 # ← 本地配置文件（gitignore）
├── .env.example         # ← 模板文件（提交到git）
├── .gitignore
├── src/
│   └── config.py        # ← 集中管理配置读取
└── main.py

✅ `.gitignore` 配置

# 忽略所有 .env 文件，但保留模板
.env
.env.local
.env.*.local
!.env.example

✅ `.env.example` 模板（给团队看）

# 复制此文件为 .env 并填写真实值
DATABASE_URL=postgresql://user:pass@localhost/dbname
DEBUG=False
API_KEY=your_api_key_here
SECRET_KEY=generate_a_random_string

✅ 集中配置管理（推荐模式）

config.py：

from dotenv import load_dotenv
from dataclasses import dataclass
import osload_dotenv()@dataclass(frozen=True)
class Config:"""应用配置，只读"""DATABASE_URL: str = os.getenv("DATABASE_URL", "")DEBUG: bool = os.getenv("DEBUG", "False").lower() == "true"API_KEY: str = os.getenv("API_KEY", "")PORT: int = int(os.getenv("PORT", "8000"))# 全局配置实例
config = Config()# 使用方式
# from config import config
# print(config.DATABASE_URL)

5. 常见坑与解决方案

坑	原因	解决
修改 `.env` 后代码没变化	只在导入时加载一次	重启程序或手动重新 `load_dotenv()`
布尔值判断错误	`os.getenv` 返回字符串	`"True" == "true"` 或 `str.lower()`
多行值解析失败	值包含换行符	用引号包裹：`MY_VAR="line1\nline2"`
值包含 `#` 被截断	`#` 被当注释	用引号包裹：`URL="http://a.com#fragment"`
生产环境变量不生效	优先级问题	生产环境直接用系统环境变量，不依赖 `.env`

6. 快速参考卡片

from dotenv import load_dotenv, find_dotenv
import os# 标准启动代码
load_dotenv(find_dotenv())# 读取（带默认值）
value = os.getenv("KEY", "default")# 类型转换
port = int(os.getenv("PORT", "8080"))
debug = os.getenv("DEBUG", "").lower() in ("true", "1", "yes")# 检查必填项
required = ["DATABASE_URL", "API_KEY"]
missing = [k for k in required if not os.getenv(k)]
if missing:raise ValueError(f"缺少环境变量: {missing}")

总结

要点	说明
核心功能	把配置从代码分离到 `.env` 文件
安全原则	`.env` 永不提交 Git，用 `.env.example` 模板
架构模式	用 `config.py` 集中管理，避免到处 `os.getenv`
生产部署	云平台直接设置环境变量，不依赖 `.env` 文件