【Python 】dotenv 模块与用法介绍及Flask 集成用法示例

dotenv 模块介绍与用法

Python-dotenv 是一个用于管理环境变量的 Python 库，它通过 .env 文件来存储配置信息，帮助开发者将敏感信息（如 API 密钥、数据库凭证等）与代码分离，从而提高项目的安全性和可移植性。

核心功能与优势

环境变量管理 ：从 .env 文件中加载环境变量到应用程序中，避免敏感信息硬编码在代码中。
多环境支持：可以轻松切换开发/测试/生产环境配置。
类型自动转换：支持字符串到数字/布尔值的自动转换。
嵌套变量解析 ：支持类似 PATH=${ROOT}/bin 的变量引用。
框架集成：与 Flask、Django、FastAPI 等主流框架无缝协作。

安装与基本配置

首先安装 python-dotenv：

bash 复制代码

pip install python-dotenv

然后在项目根目录创建 .env 文件，内容格式为 KEY=VALUE：

bash 复制代码

DEBUG=True
DB_HOST=localhost
DB_PORT=5432
SECRET_KEY=supersecretkey

基本使用方法

python 复制代码

from dotenv import load_dotenv
import os
# 加载.env文件
load_dotenv()
# 访问环境变量
debug_mode = os.getenv('DEBUG')  # 输出: True
db_host = os.getenv('DB_HOST')   # 输出: localhost
db_port = os.getenv('DB_PORT')   # 输出: 5432
print(f"Debug Mode: {debug_mode}")
print(f"Database Host: {db_host}:{db_port}")

多环境配置示例

可以根据环境变量加载不同的配置文件：

python 复制代码

import os
from dotenv import load_dotenv
# 根据环境变量确定加载哪个配置文件
env = os.getenv('ENV', 'dev')  # 默认使用开发环境
load_dotenv(f'.env.{env}')     # 加载 .env.dev 或 .env.prod
# 使用配置
debug_mode = os.getenv('DEBUG')
db_host = os.getenv('DB_HOST')
print(f"Environment: {env}, Debug: {debug_mode}, DB Host: {db_host}")

高级用法

1. 指定 .env 文件路径

python 复制代码

load_dotenv(dotenv_path='/path/to/custom.env')

2. 覆盖现有环境变量

默认情况下，python-dotenv 不会覆盖已经存在的环境变量。可以通过设置 override=True 来覆盖：

python 复制代码

load_dotenv(override=True)

3. 处理默认值

可以为环境变量设置默认值：

python 复制代码

database_url = os.getenv('DATABASE_URL', 'sqlite:///:memory:')

4. 类型安全与验证

使用 pydantic 进行类型验证：

python 复制代码

from pydantic import BaseSettings
class Settings(BaseSettings):
    api_key: str
    debug: bool = False
    rate_limit: int = 100
    class Config:
        env_file = ".env"
settings = Settings()
print(settings.api_key)
print(settings.debug)

5. 嵌套变量解析

在 .env 文件中：

复制代码

ROOT_PATH=/var/www
LOG_DIR=${ROOT_PATH}/logs
CACHE_DIR=${ROOT_PATH}/cache

6. 动态加载配置

python 复制代码

from dotenv import dotenv_values
class Config:
    def __init__(self):
        self.config = {
            **dotenv_values(".env.base"),    # 基础配置
            **dotenv_values(".env.secret"),  # 密钥配置
            **os.environ                    # 系统环境变量
        }
    
    def get(self, key):
        return self.config.get(key)
config = Config()
print(config.get('DATABASE_URL'))

安全最佳实践

避免提交 .env 文件到版本控制 ：

bash 复制代码

echo ".env*" >> .gitignore
echo "!.env.example" >> .gitignore

创建配置模板 ：
bash 复制代码
```
cp .env .env.example
```

多环境部署架构 ：

复制代码

project-root/
    .env.dev        # 开发环境
    .env.staging    # 预发布环境
    .env.prod       # 生产环境

与 Docker 集成 ：

dockerfile 复制代码

FROM python:3.10
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY .env.prod .env
COPY . .
CMD ["python", "main.py"]

常见问题与解决方案

变量未生效 ：
- 强制覆盖现有环境变量：load_dotenv(override=True)
- 检查文件路径：load_dotenv('/custom/path/.env')
Flask 项目无法启动 ：
- 避免在项目根目录创建 .env 文件，正确位置应在应用目录内。

Docker 部署问题 ：

使用构建参数传递敏感信息：

dockerfile 复制代码

FROM python:3.9
ARG DB_PASS
ENV DB_PASS=${DB_PASS}
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

构建时传递参数：

bash 复制代码

docker build --build-arg DB_PASS=my_secret -t myapp .

Flask 集成

在 Flask 中集成 python-dotenv 模块可以方便地管理环境变量，使配置更加安全且易于维护。以下是具体的集成步骤和示例代码：

1. 安装 python-dotenv

首先，确保已安装 python-dotenv 模块。可以通过以下命令安装：

bash 复制代码

pip install python-dotenv

2. 创建 .env 文件

在 Flask 项目的根目录下创建一个名为 .env 的文件，用于存储环境变量。例如：

ini 复制代码

# .env 文件示例
DATABASE_URL=postgresql://user:password@localhost/mydatabase
SECRET_KEY=your_secret_key
DEBUG=True

注意：.env 文件通常不提交到版本控制系统（如 Git），因为它可能包含敏感信息。

3. 在 Flask 中加载 .env 文件

在 Flask 应用的入口文件（通常是 app.py 或 main.py）中，使用 python-dotenv 加载 .env 文件，并读取环境变量。以下是一个完整的示例：

python 复制代码

# app.py
from flask import Flask
from dotenv import load_dotenv
import os
# 加载 .env 文件中的环境变量
load_dotenv()
app = Flask(__name__)
# 从环境变量中读取配置
app.config['DATABASE_URL'] = os.getenv('DATABASE_URL')
app.config['SECRET_KEY'] = os.getenv('SECRET_KEY')
app.config['DEBUG'] = os.getenv('DEBUG', 'False').lower() == 'true'
@app.route('/')
def hello():
    return f"Hello, World! Debug mode: {app.config['DEBUG']}"
if __name__ == '__main__':
    app.run()

说明：

load_dotenv() 会自动加载项目根目录下的 .env 文件。

os.getenv('KEY') 用于从环境变量中读取值，如果变量不存在，则返回 None。

通过 os.getenv('KEY', 'default_value') 可以设置默认值。

4. 启动 Flask 应用

在终端中运行以下命令启动 Flask 应用：

bash 复制代码

flask run

或者，直接运行 Python 文件：

bash 复制代码

python app.py

5. 高级用法：区分开发与生产环境

Flask 支持通过环境变量 FLASK_ENV 区分开发环境和生产环境。可以在 .env 文件中设置：

ini 复制代码

# .env 文件
FLASK_ENV=development

在代码中，可以根据环境变量动态加载不同的配置：

python 复制代码

if os.getenv('FLASK_ENV') == 'development':
    app.config['DEBUG'] = True
else:
    app.config['DEBUG'] = False

提示：Flask 默认支持从 .env 和 .flaskenv 文件加载环境变量，优先级为：手动设置的环境变量 > .env 文件中的变量 > .flaskenv 文件中的变量。

6. 避免常见问题

确保文件路径正确 ：如果 .env 文件不在项目根目录，需要指定路径，例如：
python 复制代码
```
load_dotenv(dotenv_path='/path/to/.env')
```
避免提交敏感信息 ：在 .gitignore 文件中添加 .env，避免将敏感信息提交到版本控制系统中。
检查环境变量是否生效 ：可以通过 print(os.getenv('KEY')) 打印环境变量，确保配置正确加载。

总结

通过 python-dotenv，Flask 应用可以轻松管理环境变量，避免敏感信息硬编码在代码中，同时支持多环境配置。以上示例展示了基本用法，可以根据实际需求进一步扩展。更多高级用法可参考官方文档或相关教程。