网站导航
> 技术文档 > 【Python 】dotenv 模块与用法介绍及Flask 集成用法示例

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

网友: 技术文档 2025-07-26 19:43:56

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=TrueDB_HOST=localhostDB_PORT=5432SECRET_KEY=supersecretkey

基本使用方法

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

多环境配置示例

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

import osfrom 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 BaseSettingsclass 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/wwwLOG_DIR=${ROOT_PATH}/logsCACHE_DIR=${ROOT_PATH}/cache

6. 动态加载配置

from dotenv import dotenv_valuesclass 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*\" >> .gitignoreecho \"!.env.example\" >> .gitignore
  2. 创建配置模板： 
    cp .env .env.example
  3. 多环境部署架构： 
    project-root/ .env.dev # 开发环境 .env.staging # 预发布环境 .env.prod # 生产环境
  4. 与 Docker 集成： 
    FROM python:3.10WORKDIR /appCOPY requirements.txt .RUN pip install -r requirements.txtCOPY .env.prod .envCOPY . .CMD [\"python\", \"main.py\"]

常见问题与解决方案

  1. 变量未生效：
    • 强制覆盖现有环境变量：load_dotenv(override=True)
    • 检查文件路径：load_dotenv(\'/custom/path/.env\')
  2. Flask 项目无法启动：
    • 避免在项目根目录创建 .env 文件，正确位置应在应用目录内。
  3. Docker 部署问题：
    • 使用构建参数传递敏感信息： 
      FROM python:3.9ARG DB_PASSENV DB_PASS=${DB_PASS}COPY requirements.txt .RUN pip install -r requirements.txtCOPY . .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/mydatabaseSECRET_KEY=your_secret_keyDEBUG=True

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

3. 在 Flask 中加载 .env 文件

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

# app.pyfrom flask import Flaskfrom dotenv import load_dotenvimport 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\'] = Trueelse: 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 应用可以轻松管理环境变量，避免敏感信息硬编码在代码中，同时支持多环境配置。以上示例展示了基本用法，可以根据实际需求进一步扩展。更多高级用法可参考官方文档或相关教程。

网络标签：

相关问题