安装了 python-dotenv 后出现报错 “ModuleNotFoundError: No module named ‘dotenv’”

一、背景与问题

在开发 Python 应用时，我们常常需要管理环境变量。python-dotenv 是一个流行的库，用于将 .env 文件中的环境变量加载到 os.environ 中。然而，许多开发者在使用过程中会遇到以下错误：

ModuleNotFoundError: No module named 'dotenv'

尽管已经通过 pip install python-dotenv 安装了库，但仍然报错。这个错误通常与模块名称、版本兼容性、导入方式或项目结构有关。

二、基本原理

python-dotenv 的核心功能是将 .env 文件中的键值对加载到当前 Python 进程的环境变量中。它的实现依赖于以下机制：

模块结构：python-dotenv 的源码中包含 dotenv 模块，但该模块的导入路径可能因版本不同而变化。
动态加载：通过 load_dotenv() 函数读取 .env 文件，并将变量注入 os.environ。
版本差异：不同版本的 python-dotenv 可能在模块命名或导入方式上存在差异。

三、环境准备

1. 安装依赖

确保已安装 python-dotenv：

pip install python-dotenv

2. 创建 `.env` 文件

在项目根目录创建 .env 文件，内容如下：

DEBUG=True
SECRET_KEY=your_secret_key

3. 项目结构示例

my_project/
├── .env
├── main.py
├── requirements.txt
└── README.md

四、核心实现

1. 正确的导入方式

在 Python 脚本中，需要正确导入 python-dotenv 的模块。注意模块名与包名的区别：

# 正确导入方式（v1.0.0 及以上版本）
from dotenv import load_dotenv

# 错误导入方式（可能因版本或路径问题导致报错）
import dotenv  # 此处可能报错，需确认模块路径

错误原因分析

版本差异：早期版本（如 v0.14.0）可能使用 dotenv 模块，而新版本改为 dotenv 模块的子模块。
路径问题：若项目结构复杂，可能需要显式指定 .env 文件路径。

2. 加载环境变量

import os
from dotenv import load_dotenv

# 加载当前目录下的 .env 文件
load_dotenv()

# 使用环境变量
print(os.getenv("DEBUG"))  # 输出: True

关键代码解释

load_dotenv() 会读取当前目录下的 .env 文件，若未找到则忽略。
os.getenv() 用于获取环境变量，若未设置则返回 None。

3. 指定 `.env` 文件路径

from dotenv import load_dotenv

# 指定其他路径的 .env 文件
load_dotenv(".env.prod")  # 加载 .env.prod 文件

注意事项

路径必须相对于当前工作目录，否则会抛出 FileNotFoundError。
若未指定路径，默认加载 ./.env，但此行为可能因版本不同而变化。

五、完整案例

场景：Flask 应用中使用 `python-dotenv`

1. 项目结构

flask_app/
├── .env
├── app.py
└── requirements.txt

2. `requirements.txt`

Flask==2.3.2
python-dotenv==1.0.0

3. `app.py`

from flask import Flask
from dotenv import load_dotenv
import os

app = Flask(__name__)

# 加载环境变量
load_dotenv()

@app.route("/")
def index():
    return f"Debug mode: {os.getenv('DEBUG')} | Secret Key: {os.getenv('SECRET_KEY')}"

if __name__ == "__main__":
    app.run(debug=os.getenv("DEBUG") == "True")

4. 运行应用

python app.py

5. 预期输出

Debug mode: True | Secret Key: your_secret_key

6. 错误处理

若 .env 文件不存在，load_dotenv() 会静默忽略，但环境变量会缺失。建议添加验证逻辑：

if not os.getenv("SECRET_KEY"):
    raise ValueError("Secret key not found in .env file")

六、源码解析

1. `python-dotenv` 的核心逻辑

查看 python-dotenv 的源码（以 v1.0.0 为例），核心代码位于 dotenv.py：

import os
import dotenv

def load_dotenv(filename=None):
    if filename is None:
        filename = ".env"
    dotenv.load_dotenv(filename)

关键点

load_dotenv() 会调用 dotenv.load_dotenv()，但此函数在旧版本中可能不存在。
路径处理依赖 os.path 模块，需确保路径正确。

2. 版本差异分析

版本	模块名	导入方式	路径处理方式
v0.14.0	dotenv	`import dotenv`	相对路径
v1.0.0+	dotenv	`from dotenv import load_dotenv`	绝对路径或相对路径

七、进阶使用

1. 环境变量优先级

python-dotenv 会覆盖系统环境变量，但可以通过 override=False 避免：

load_dotenv(override=False)  # 系统变量优先

2. 多环境配置

创建多个 .env 文件并按需加载：

# 生产环境
load_dotenv(".env.prod")

# 开发环境
load_dotenv(".env.dev")

3. 安全性考虑

敏感信息泄露风险：.env 文件可能被提交到版本控制（如 Git），需在 .gitignore 中声明：
```
.env
.env.*  # 匹配所有 .env 文件
```
环境变量注入：在生产环境中，建议通过运维工具（如 Docker、Kubernetes）注入环境变量，而非依赖 .env 文件。

八、性能与工程实践

1. 性能优化

避免重复加载：在应用启动时加载一次，避免重复调用 load_dotenv()。
缓存环境变量：使用 os.environ 的不可变性，避免频繁修改。

2. 异常处理

try:
    load_dotenv()
except Exception as e:
    print(f"Failed to load .env: {e}")

3. 日志记录

import logging
logging.basicConfig(level=logging.INFO)

def load_dotenv_with_logging(filename=None):
    try:
        load_dotenv(filename)
        logging.info("Successfully loaded .env")
    except Exception as e:
        logging.error(f"Failed to load .env: {e}")

九、常见问题与踩坑

1. 模块名混淆

错误代码：

import dotenv  # 错误！可能报错

正确方式：

from dotenv import load_dotenv  # 正确

2. 路径错误

错误场景：

.env 文件位于 config/ 目录，但代码中未指定路径。

解决方案：

load_dotenv("config/.env")  # 指定完整路径

3. 版本兼容性问题

问题描述：

使用 python-dotenv v0.14.0 时，load_dotenv() 需要 dotenv 模块。