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。

bash 复制代码

pip install python-dotenv

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

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

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

示例 .env 文件：

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 中。这是最常用、最高频的方法。

python 复制代码

from dotenv import load_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。

示例：

python 复制代码

import os
from dotenv import load_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)，且不想污染系统全局环境变量的场景。

python 复制代码

from dotenv import dotenv_values

dotenv_values(dotenv_path=None)

参数：

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

返回值：

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

示例：

python 复制代码

from dotenv import dotenv_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 文件，直到根目录为止。

python 复制代码

from dotenv import find_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 文件，修改某个特定变量的值。如果该变量不存在，则在文件末尾自动追加该键值对。

python 复制代码

from dotenv import set_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)。

示例：

python 复制代码

import os
from dotenv import set_key, find_dotenv

env_file = find_dotenv()

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

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

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

python 复制代码

from dotenv import get_key

get_key(dotenv_path, key_to_get)

参数：

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

返回值：

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

示例：

python 复制代码

from dotenv import get_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 文件，查找并彻底物理删除指定的键值对（包括其所在的行）。如果目标键在文件中不存在，则文件保持原样，不会报错。

python 复制代码

from dotenv import unset_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)。

示例：

python 复制代码

from dotenv import unset_key, find_dotenv

env_file = find_dotenv()

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