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

dotenv 模块介绍与用法

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

核心功能与优势

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

安装与基本配置

首先安装 python-dotenv：

pip install python-dotenv

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

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

基本使用方法

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}")

多环境配置示例

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

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 文件路径

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

2. 覆盖现有环境变量

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

load_dotenv(override=True)

3. 处理默认值

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

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

4. 类型安全与验证

使用 pydantic 进行类型验证：

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. 动态加载配置

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'))

安全最佳实践

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

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

2. 创建配置模板：

   cp .env .env.example
   

3. 多环境部署架构：

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

4. 与 Docker 集成：

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

常见问题与解决方案

1. 变量未生效：
   • 强制覆盖现有环境变量：load_dotenv(override=True)
   • 检查文件路径：load_dotenv('/custom/path/.env')
2. Flask 项目无法启动：
   • 避免在项目根目录创建 .env 文件，正确位置应在应用目录内。
3. Docker 部署问题：
   • 使用构建参数传递敏感信息：

     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"]
     

   • 构建时传递参数：

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

Flask 集成

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

---

1. 安装 python-dotenv

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

pip install python-dotenv

---

2. 创建 .env 文件

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

# .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 文件，并读取环境变量。以下是一个完整的示例：

# 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 应用：

flask run

或者，直接运行 Python 文件：

python app.py

---

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

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

# .env 文件
FLASK_ENV=development

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

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

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

---

6. 避免常见问题

• 确保文件路径正确：如果 .env 文件不在项目根目录，需要指定路径，例如：

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

• 避免提交敏感信息：在 .gitignore 文件中添加 .env，避免将敏感信息提交到版本控制系统中。
• 检查环境变量是否生效：可以通过 print(os.getenv('KEY')) 打印环境变量，确保配置正确加载。

---

总结

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