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-dotenv1. .env 文件的基本编写规则.env文件的编写极其严格它遵循类似于 Bash 的语法规则主要必须满足以下条件键值对格式使用KEYVALUE的形式等号两侧尽量不要有空格。引号的使用值可以使用单引号或双引号包裹。如果值内部包含空格或特殊字符必须使用引号。注释规则使用#开头表示注释注释可以单独一行也可以放在配置项的尾部(需用空格隔开)。示例.env文件# 数据库配置 DB_HOST127.0.0.1 DB_PORT3306 # API 密钥 (包含空格使用双引号包裹) SECRET_KEYmy super secret key # 变量的扩展(Expansion)特性复用已有的变量 DATABASE_URLmysql://${DB_HOST}:${DB_PORT}/my_db二. 核心加载与解析运算核心运算指的是将.env文件中的配置数据读取到 Python 运行环境中的相关方法。1. load_dotenv - 全局环境变量加载作用自动搜索当前路径下的.env文件没有就去父目录下找找到就停止并将其内部的键值对全部注册到 Python 的全局环境变量字典os.environ中。这是最常用、最高频的方法。fromdotenvimportload_dotenv load_dotenv(dotenv_pathNone,overrideFalse)参数配置文件路径 (dotenv_path) 指定.env文件的绝对或相对路径。如果不指定默认使用find_dotenv()自动向上层目录寻找 (String 或 PathLike -pathlib模块中的Path对象)。覆盖标志 (override) 当系统环境变量中已经存在同名键时决定是否使用.env文件中的值进行覆盖。False为不覆盖(默认)True为强制覆盖 (bool)。返回值成功 返回一个布尔值 (bool)。如果找到了.env文件并成功加载则返回True未找到则返回False。示例importosfromdotenvimportload_dotenv# 加载环境变量is_loadedload_dotenv()# 返回 True# 通过 Python 原生的 os 模块读取hostos.getenv(DB_HOST)# 127.0.0.1portos.getenv(DB_PORT,默认值8080)# 3306 (支持设置默认值)2. dotenv_values - 字典解析运算作用将.env文件的内容读取并解析为一个标准的 Python 字典 (dict)但绝对不会将这些值注入到os.environ中。注这种方法常用于同一项目中需要加载多个不同环境配置文件(如.env.dev,.env.prod)且不想污染系统全局环境变量的场景。fromdotenvimportdotenv_values dotenv_values(dotenv_pathNone)参数配置文件路径 (dotenv_path) 需要解析的目标配置文件路径 (String 或 PathLike)。返回值成功 返回一个包含所有配置键值对的字典 (OrderedDict / dict)。示例fromdotenvimportdotenv_values# 解析特定的配置文件configdotenv_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_foundFalse,usecwdFalse)参数文件名 (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_modealways)参数配置文件路径 (dotenv_path) 目标.env文件的绝对路径 (String)。目标键名 (key_to_set) 需要修改或新增的变量名 (String)。目标键值 (value_to_set) 需要设置的新值 (String)。引号模式 (quote_mode) 控制写入文件时是否加引号。always(总是加引号),auto(包含空格时加),never(从不加) (String)。返回值成功 返回包含所设置键值对的元组 (Tuple)。示例importosfromdotenvimportset_key,find_dotenv env_filefind_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_filefind_dotenv()# 直接查阅文件内容不污染当前运行的全局环境api_versionget_key(env_file,API_VERSION)print(api_version)# 假设存在输出v2.0.13. unset_key - 删除指定键值对作用打开指定的.env文件查找并彻底物理删除指定的键值对包括其所在的行。如果目标键在文件中不存在则文件保持原样不会报错。fromdotenvimportunset_key unset_key(dotenv_path,key_to_unset,quote_modealways)参数配置文件路径 (dotenv_path) 目标.env文件的绝对路径 (String)。目标键名 (key_to_unset) 需要彻底删除的变量名 (String)。引号模式 (quote_mode) 重新写入文件时的引号规则通常保持默认即可 (String)。返回值成功 返回一个元组。如果删除成功返回(True, 你的键名)如果没找到该键返回(None, 你的键名)(Tuple)。示例fromdotenvimportunset_key,find_dotenv env_filefind_dotenv()# 从 .env 文件中物理抹除该配置项resultunset_key(env_file,API_VERSION)print(result)# 删除成功时输出类似于(True, API_VERSION)