LLM系列：环境搭建：5.Python-dotenv 环境变量管理-开发者社区

Python-dotenv 环境变量管理

在Python项目开发中，python-dotenv是一个用于从.env文件读取键值对并将其加载到系统环境变量中的核心工具库。根据日常工程规范，其主要功能与应用场景总共可分为四大类：

1. 基础加载(Basic Loading)：自动寻找并加载.env文件到 Python 的os.environ字典中；
2. 字典解析(Dictionary Parsing)：将配置文件的内容解析为 Python 字典，而不直接污染系统的全局环境变量；
3. 动态读写(Dynamic Operations)：通过代码直接对.env文件中的特定键值进行读取、修改或删除操作；
4. 变量展开(Variable Expansion)：支持在.env文件内部像 Shell 脚本一样互相引用已定义的环境变量。

(注：在进行团队协作或将项目开源时，必须将包含敏感信息(如数据库密码、API Key、Secret)的.env文件加入到.gitignore中，以防核心机密泄露。)

一. 安装与基础语法规则

在使用之前，需要通过 pip 安装该第三方库。虽然导入时使用的是import dotenv，但安装时的包名是python-dotenv。

pipinstallpython-dotenv

1. .env 文件的基本编写规则

.env文件的编写极其严格，它遵循类似于 Bash 的语法规则，主要必须满足以下条件：

键值对格式：使用KEY=VALUE的形式，等号两侧尽量不要有空格。
引号的使用：值可以使用单引号或双引号包裹。如果值内部包含空格或特殊字符，必须使用引号。
注释规则：使用#开头表示注释，注释可以单独一行，也可以放在配置项的尾部(需用空格隔开)。

示例.env文件：

# 数据库配置 DB_HOST=127.0.0.1 DB_PORT=3306 # API 密钥 (包含空格，使用双引号包裹) SECRET_KEY="my super secret key" # 变量的扩展(Expansion)特性：复用已有的变量 DATABASE_URL="mysql://${DB_HOST}:${DB_PORT}/my_db"

二. 核心加载与解析运算

核心运算指的是将.env文件中的配置数据读取到 Python 运行环境中的相关方法。

1. load_dotenv - 全局环境变量加载

作用：自动搜索当前路径下的.env文件，没有就去父目录下找，找到就停止；并将其内部的键值对全部注册到 Python 的全局环境变量字典os.environ中。这是最常用、最高频的方法。

fromdotenvimportload_dotenv load_dotenv(dotenv_path=None,override=False)

参数：

配置文件路径 (dotenv_path)：指定.env文件的绝对或相对路径。如果不指定，默认使用find_dotenv()自动向上层目录寻找 (String 或 PathLike -pathlib模块中的Path对象)。
覆盖标志 (override)：当系统环境变量中已经存在同名键时，决定是否使用.env文件中的值进行覆盖。False为不覆盖(默认)，True为强制覆盖 (bool)。

返回值：

成功：返回一个布尔值 (bool)。如果找到了.env文件并成功加载则返回True，未找到则返回False。

示例：

importosfromdotenvimportload_dotenv# 加载环境变量is_loaded=load_dotenv()# 返回 True# 通过 Python 原生的 os 模块读取host=os.getenv("DB_HOST")# '127.0.0.1'port=os.getenv("DB_PORT","默认值8080")# '3306' (支持设置默认值)

2. dotenv_values - 字典解析运算

作用：将.env文件的内容读取并解析为一个标准的 Python 字典 (dict)，但绝对不会将这些值注入到os.environ中。

注：这种方法常用于同一项目中需要加载多个不同环境配置文件(如.env.dev,.env.prod)，且不想污染系统全局环境变量的场景。

fromdotenvimportdotenv_values dotenv_values(dotenv_path=None)

参数：

配置文件路径 (dotenv_path)：需要解析的目标配置文件路径 (String 或 PathLike)。

返回值：

成功：返回一个包含所有配置键值对的字典 (OrderedDict / dict)。

示例：

fromdotenvimportdotenv_values# 解析特定的配置文件config=dotenv_values(".env.dev")# {'DB_HOST': '127.0.0.1', 'DB_PORT': '3306', 'SECRET_KEY': 'my super secret key', ...}print(config["DB_HOST"])# 直接像字典一样取值

3. find_dotenv - 配置文件自动定位

作用：从当前脚本所在目录开始，逐级向父目录寻找.env文件，直到根目录为止。

fromdotenvimportfind_dotenv find_dotenv(filename='.env',raise_error_if_not_found=False,usecwd=False)

参数：

文件名 (filename)：需要寻找的目标文件名，默认为'.env'(String)。
异常标志 (raise_error_if_not_found)：如果为True，找不到文件时会直接抛出 IOError 异常 (bool)。

返回值：

成功：返回找到的配置文件的绝对路径字符串 (String)。若未找到则返回空字符串""。

三. 动态读写运算

动态读写运算常用于在代码运行时，直接对硬盘上的.env文件内容进行增删改查。它直接修改文件本身，而不仅仅是修改内存中的变量。

函数	描述
set_key(…)	修改`.env`文件中指定键的值（如果不存在则追加）。
get_key(…)	读取`.env`文件中指定键的值（不加载到环境变量）。
unset_key(…)	删除`.env`文件中指定的键值对。

1. set_key - 动态更新或追加键值

作用：打开指定的.env文件，修改某个特定变量的值。如果该变量不存在，则在文件末尾自动追加该键值对。

fromdotenvimportset_key set_key(dotenv_path,key_to_set,value_to_set,quote_mode='always')

参数：

配置文件路径 (dotenv_path)：目标.env文件的绝对路径 (String)。
目标键名 (key_to_set)：需要修改或新增的变量名 (String)。
目标键值 (value_to_set)：需要设置的新值 (String)。
引号模式 (quote_mode)：控制写入文件时是否加引号。'always'(总是加引号),'auto'(包含空格时加),'never'(从不加) (String)。

返回值：

成功：返回包含所设置键值对的元组 (Tuple)。

示例：

importosfromdotenvimportset_key,find_dotenv env_file=find_dotenv()# 修改现有值或新增配置，直接物理写入到 .env 文件中set_key(env_file,"API_VERSION","v2.0.1")

2. get_key - 物理读取指定键值

作用：直接从硬盘上的.env文件中读取某个特定变量的值。此操作绝对不会将该变量加载到系统的os.environ环境变量中，实现了真正的读取隔离。

fromdotenvimportget_key get_key(dotenv_path,key_to_get)

参数：

配置文件路径 (dotenv_path)：目标.env文件的绝对路径 (String)。
目标键名 (key_to_get)：需要读取的目标变量名 (String)。

返回值：

成功：如果文件中存在该键，返回对应的字符串值 (String)；如果不存在，则返回None。

示例：

fromdotenvimportget_key,find_dotenv env_file=find_dotenv()# 直接查阅文件内容，不污染当前运行的全局环境api_version=get_key(env_file,"API_VERSION")print(api_version)# 假设存在，输出：'v2.0.1'

3. unset_key - 删除指定键值对

作用：打开指定的.env文件，查找并彻底物理删除指定的键值对（包括其所在的行）。如果目标键在文件中不存在，则文件保持原样，不会报错。

fromdotenvimportunset_key unset_key(dotenv_path,key_to_unset,quote_mode='always')

参数：

配置文件路径 (dotenv_path)：目标.env文件的绝对路径 (String)。
目标键名 (key_to_unset)：需要彻底删除的变量名 (String)。
引号模式 (quote_mode)：重新写入文件时的引号规则，通常保持默认即可 (String)。

返回值：

成功：返回一个元组。如果删除成功返回(True, '你的键名')；如果没找到该键，返回(None, '你的键名')(Tuple)。

示例：

fromdotenvimportunset_key,find_dotenv env_file=find_dotenv()# 从 .env 文件中物理抹除该配置项result=unset_key(env_file,"API_VERSION")print(result)# 删除成功时输出类似于：(True, 'API_VERSION')