如何在 Locust 中正确加载并使用 .env 文件中的环境变量

如何在 Locust 性能测试中正确配置与加载 .env 环境变量文件

本文深入解析 Locust 测试框架中无法读取 .env 文件变量的核心原因，并提供基于 python-dotenv 库、Shell 脚本及 Makefile 的多种可靠解决方案，确保 os.environ.get() 方法能稳定获取环境变量值，保障性能测试顺利进行。

在进行 Locust 性能测试时，你是否也遭遇过这样的困境：项目根目录下明明已经配置好了 .env 文件，其中包含了关键的 API 密钥或认证参数，但运行 Locust 脚本后，请求却频繁失败？检查日志发现，构造的 URL 中关键参数值为空，例如 /api/test/apiKey=。

问题的根源非常明确：Locust 框架本身不具备自动加载 .env 文件的能力。这是一个常见的理解误区。需要明确的是，.env 文件只是一种广泛采用的配置文件格式，Python 进程（包括 Locust）在启动时，并不会主动去解析它。你的代码中使用的 os.environ.get("VALUE", "") 方法，读取的是操作系统当前进程的环境变量，而非 .env 文件中的内容。因此，即使你的 .env 文件内写有 VALUE=diuqriqjqj，只要没有进行显式加载，apiKey 变量获取到的就始终是空字符串，最终导致请求 URL 不完整，引发连接错误或 API 认证失败。

✅ 核心解决方案：显式加载 .env 文件并注入环境变量

方案一：使用 python-dotenv 库（推荐，最符合 Python 开发习惯）

1. 安装必要的 Python 包：
   

   pip install python-dotenv

2. 修改你的 locustfile.py，在文件开头添加加载代码：
   

   import os
   from dotenv import load_dotenv
   from locust import HttpUser, task, between
   
   # 显式加载当前目录下的 .env 文件
   load_dotenv()
   
   # 获取环境变量，并进行有效性校验
   apiKey = os.environ.get("VALUE")
   if not apiKey:
       raise ValueError("运行错误：缺少必需的环境变量 ‘VALUE’，请检查 .env 文件配置。")
   
   class ApiUser(HttpUser):
       wait_time = between(1, 5)
   
       @task
       def test_api_endpoint(self):
           # 使用加载的变量构造请求
           self.client.get(f"/api/test/apiKey={apiKey}")

3. 正常启动 Locust 测试：
   

   locust -f locustfile.py

✅ 方案优势：跨平台兼容性好、无需依赖 Shell 环境、支持变量覆盖与文件内注释、可灵活指定配置文件路径（例如 load_dotenv(".env.production")）。

方案二：在 Shell 层面加载环境变量（适用于 CI/CD 或 Makefile 自动化场景）

如果项目环境限制，无法安装额外的 Python 依赖包，可以选择在启动 Locust 的 Shell 命令中预先加载环境变量。

• 使用 source 命令导出变量（Bash/Zsh 环境）：
  

  set -a; source .env; set +a; locust -f locustfile.py

  提示：set -a 命令的作用是自动导出（export）后续定义的所有变量，set +a 则关闭此功能。

• 集成到 Makefile 中进行管理（示例）：
  

  # Makefile 配置示例
  # 检查并加载 .env 文件
  ifneq (,$(wildcard ./.env))
      include .env
      export
  endif
  
  # 定义 locust 运行命令
  locust-run:
      env VALUE=$(VALUE) locust -f locustfile.py

  执行时只需运行 make locust-run。请注意，这种方式要求 .env 文件中的变量名必须严格匹配（例如必须定义为 VALUE=...），且 Makefile 的 include 指令不会处理值两侧的引号。因此，最稳妥的做法是将 .env 文件内容直接写为 VALUE=diuqriqjqj（无空格、无引号）。

⚠️ 关键注意事项与最佳实践

• ❌ 切勿依赖简单的文件存在性判断，如 if test -f .env; then locust ...; fi —— 这条命令仅检查文件是否存在，完全不会加载文件内的环境变量。
• ❌ 避免在 .env 文件中使用引号包裹变量值（例如 VALUE="abc"）。虽然 python-dotenv 库可以解析，但在使用 Shell 的 source 命令时可能导致解析错误。统一采用 VALUE=abc 的无引号格式更为安全可靠。
• ✅ 务必进行变量校验：在代码中始终检查关键环境变量是否成功加载（如示例中的 raise ValueError），防止因配置缺失导致的静默失败，这能极大提升调试效率。