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

【Python】使用`python-dotenv`模块管理环境变量

news 来源：原创 2025/8/23 15:14:46

最近田辛老师在进行与AI有关的开发。在开发和部署 Python 应用程序时（要么是在某个Python环境，要么是在MaxKB等知识库系统），我常常需要根据不同的环境（如开发环境、测试环境、生产环境）使用不同的配置信息，或者不想将敏感信息（如数据库连接字符串、API 密钥等）直接写在代码中。这时候，使用环境变量来管理这些配置信息就显得非常方便和安全。今天，田辛老师介绍通过python-dotenv模块，帮助我们轻松地从文件中读取环境变量并在程序中使用。

1. 安装 python-dotenv 模块

python-dotenv 模块不是 Python 标准库的一部分，所以我们需要先安装它。可以使用 pip来进行安装：

pip install python-dotenv

或者在Windows系统中

py -m pip install python-dotenv

2. `.env`文件的使用

我们通常会在项目根目录下创建一个名为.env的文件，在这个文件中以键=值的形式定义环境变量。例如：

NAME=田辛
COMPANY=田豆芽
EMAIL=tianxin.xp@gmail.com
API_KEY=sf-XXXXXXXXXX

这个文件中的每一行代表一个环境变量及其对应的值。

2.1. 使用 `load_dotenv()` 函数加载环境变量

要将 .env 文件中的环境变量加载到程序中，可以使用 load_dotenv() 函数。这个函数会自动在当前目录及其父目录中查找 .env 文件，并将其中定义的环境变量加载到操作系统的环境变量中。

from dotenv import load_dotenvload_dotenv()

如果 .env 文件成功加载，load_dotenv() 函数会返回 True，否则返回 False。我们可以利用这个返回值来判断是否成功加载了环境变量：

    # 加载环境变量文件if load_dotenv():print(f"{log_time} [INF] 读取配置文件成功")else:print(f"{log_time} [ERR] 读取配置文件失败，请检查配置文件是否存在或路径是否正确")raise FileNotFoundError("配置文件不存在或路径不正确")

2.2. 访问环境变量

加载环境变量后，我们就可以通过 os 模块来访问这些变量了。例如：

import os
from dotenv import load_dotenvload_dotenv()
print(os.getenv('NAME'))  # 输出：田辛
company = os.environ['COMPANY']
print(company )  # 输出：田豆芽
api_key = os.environ.get('SILICONFLOW_KEY', 'Nothing')  # 如果 SILICONFLOW_KEY 未定义，则返回默认值 'default'
print(api_key )  # 输出：Nothing

实际输出结果

PS E:\BG10-TRN-AIT-AI编程> & D:/01-Development/Conda/envs/py3.12/python.exe e:/BG10-TRN-AIT-AI编程/src/basic/package-dotenv.py
成功从 .env 文件加载环境变量
田辛
田豆芽
Nothing
PS E:\BG10-TRN-AIT-AI编程>

说明os.getenv() 和 os.environ.get() 都可以用来获取环境变量的值，它们都可以指定一个默认值，当环境变量未定义时返回该默认值。

3. 检查环境变量在操作系统中的设置

我们可以通过操作系统的命令行来检查环境变量是否已经设置。

在 macOS 或 Linux 中可以使用以下命令：
```
echo $EMAIL
```
在 Windows 中则可以使用：
```
echo %EMAIL%
```

这些命令会输出对应环境变量的值，如果变量未设置，则不会有任何输出。

4. `.env` 文件的搜索路径

当我们在一个子目录中调用 load_dotenv() 函数时，它会向上级目录逐层查找 .env 文件。例如，假设我们在项目根目录下的 foo/bar/baz 目录中运行程序，load_dotenv() 会依次在 foo/bar/baz、foo/bar、foo 和项目根目录中查找 .env 文件。

我们也可以通过指定 dotenv_path 参数来明确指定 .env 文件的路径：

from pathlib import Path
from dotenv import load_dotenvenv_path = Path('../../../.env')  # 指定 .env 文件的路径
load_dotenv(dotenv_path=env_path)

5. 覆盖已存在的环境变量

默认情况下，load_dotenv() 函数不会覆盖已经存在的环境变量。如果我们在不同的 .env 文件中定义了相同的环境变量，只有第一次加载的值会被保留。不过，我们可以通过设置 override=True 参数来强制覆盖已存在的环境变量：

load_dotenv(dotenv_path=myenv, override=True)

6. 以字典形式读取环境变量

除了将环境变量加载到操作系统中，我们还可以使用 dotenv_values() 函数将 .env 文件中的内容读取为一个 Python 字典。这在我们不想将环境变量实际加载到操作系统中，而只是想在程序内部使用这些值时非常有用：

from dotenv import dotenv_valuesenv_vars = dotenv_values()
for key, value in env_vars.items():print(f'{key}: {value}')

这会输出：

PS E:\BG10-TRN-AIT-AI编程> & D:/01-Development/Conda/envs/py3.12/python.exe e:/BG10-TRN-AIT-AI编程/src/basic/package-dotenv-dotenv_values.py
NAME: 田辛
COMPANY: 田豆芽
EMAIL: tianxin.xp@gmail.com
API_KEY: sf-XXXXXXXXXX
PS E:\BG10-TRN-AIT-AI编程>

总结

通过使用 python-dotenv 模块，我们可以很方便地在不同的环境中管理配置信息，同时避免将敏感信息直接暴露在代码中。这个模块提供了简单易用的接口来加载和使用环境变量，无论是通过操作系统的环境变量还是通过 Python 字典，都能满足我们的需求。在开发、测试和部署应用程序时，合理地利用环境变量和 python-dotenv 模块可以帮助我们更好地管理配置，提高代码的安全性和可维护性。

完整代码

.env

NAME=田辛
COMPANY=田豆芽
EMAIL=tianxin.xp@gmail.com
API_KEY=sf-XXXXXXXXXX

package-dotenv-load_dotenv.py

''' 
此脚本用于从 .env 文件中加载环境变量，并打印加载结果和特定环境变量的值。模块功能：
- 尝试从 .env 文件加载环境变量。
- 打印环境变量加载结果。
- 打印特定环境变量的值。
'''
import os
from dotenv import load_dotenv# 尝试从 .env 文件加载环境变量，若成功则返回 True，否则返回 False
if load_dotenv():# 打印环境变量加载成功的信息print('成功从 .env 文件加载环境变量')
else:# 打印环境变量加载失败的信息print('未从 .env 文件加载环境变量')# 使用 os.getenv 方法获取名为 'NAME' 的环境变量的值并打印
print(os.getenv('NAME'))  # 输出：田辛
# 使用 os.environ 字典获取名为 'COMPANY' 的环境变量的值，并赋值给变量 company
company = os.environ['COMPANY']
# 打印变量 company 的值
print(company)  # 输出：bar
# 使用 os.environ.get 方法获取名为 'SILICONFLOW_KEY' 的环境变量的值，若未定义则返回默认值 'Nothing'
api_key = os.environ.get('SILICONFLOW_KEY', 'Nothing')  # 原注释中 'BAZ' 可能为笔误，此处获取 'SILICONFLOW_KEY' 的值
# 打印变量 api_key 的值
print(api_key)  # 输出：default

package-dotenv-dotenv_values.py

''' 
此脚本用于从 .env 文件中加载环境变量并打印出来。模块功能：
- 从 .env 文件读取环境变量。
- 遍历并打印所有环境变量的键值对。
''' 
# 导入 dotenv 库中的 dotenv_values 函数，用于读取 .env 文件中的环境变量
from dotenv import dotenv_values# 调用 dotenv_values 函数，将 .env 文件中的环境变量存储到字典 env_vars 中
env_vars = dotenv_values()# 遍历 env_vars 字典，打印每个环境变量的键值对
for key, value in env_vars.items():# 使用 f-string 格式化输出键值对print(f'{key}: {value}')

1. 安装 python-dotenv 模块

2. .env文件的使用

2.1. 使用 load_dotenv() 函数加载环境变量