介绍
python-dotenv 可以帮你从本地的 .env 文件中读取配置，并自动加载到系统的环境变量中，这样就不用把配置信息（如：数据库用户、密码）等敏感信息直接写在代码里，既安全又便于不同环境（开发/生产）切换。
安装
pip安装
在终端执行安装命令：
pip install python-dotenv
uv安装
uv add python-dotenv
poetry虚拟环境
poetry add python-dotenv
创建 .env 文件
在你的 Python 项目根目录下，新建一个名为 .env 的文件（注意文件名以点开头），内容格式为 键=值，示例：
# .env 文件内容（注释用#开头）
DASHSCOPE_API_KEY=你的阿里云百炼API密钥
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=123456
git
一定要把 .env 文件加入 .gitignore（如果用Git管理代码），避免敏感信息提交到代码仓库！
读取配置-方式一
加载.env文件
加载 .env 文件，并放入到环境变量中：
load_dotenv()
读取环境变量
方式1：os.getenv(键, 默认值)
方式2：os.environ["键"] —— 键不存在时会报错，慎用
例子
import os
from dotenv import load_dotenv
# 加载.env文件（默认读取项目根目录的.env）
# 如果.env文件在其他路径，可指定：load_dotenv("/path/to/your/.env")
load_dotenv()
# 读取环境变量
# 方式1：os.getenv(键, 默认值) —— 推荐，键不存在时返回默认值，避免报错
dashscope_key = os.getenv("DASHSCOPE_API_KEY", "默认值（可选）")
db_host = os.getenv("DB_HOST")
db_port = os.getenv("DB_PORT")
# 方式2：os.environ["键"] —— 键不存在时会报错，慎用
# dashscope_key = os.environ["DASHSCOPE_API_KEY"]
# 打印验证
print("DashScope API Key：", dashscope_key)
print("数据库地址：", db_host, ":", db_port)
load_dotenv() 的参数
dotenv_path：指定.env文件路径，如load_dotenv("./config/.env")；override=True：强制用.env中的值覆盖系统已有的同名环境变量（默认 False）；verbose=True：打印加载过程的日志，便于排查问题。
读取配置-方式二
加载.env文件
不加载到环境变量，直接读取 .env 为字典（适合不想污染环境变量的场景）
config = dotenv_values(".env")
例子
from dotenv import dotenv_values
# 不加载到环境变量，直接读取.env为字典（适合不想污染环境变量的场景）
config = dotenv_values(".env")
print(config["DASHSCOPE_API_KEY"]) # 直接从字典取值
常见问题
- 加载不到.env文件：检查文件路径是否正确（默认读项目根目录）、文件名是否是
.env（不是 env 或 .env.txt）； - 中文乱码：确保
.env文件编码为 UTF-8； - 值包含特殊字符（如空格、等号）：用引号包裹，如
API_KEY="ab cd=123"。
总结
python-dotenv核心作用是安全管理敏感配置，避免硬编码，通过.env文件分离配置和代码；- 核心流程：安装 → 创建
.env写配置 → 代码中load_dotenv()加载 →os.getenv()读取； - 关键注意事项：
.env文件要保密，读取时优先用os.getenv()（带默认值）避免报错。