Python pytest怎么对环境变量进行Mock处理_使用monkeypatch插件

先说个常见的坑：在测试里直接怼一行 os.environ["API_KEY"] = "test"，看起来是挺省事的，但实际跑起来就可能给你埋雷。这个操作会直接污染全局环境变量——后续的测试如果没清理干净，读到这个残留值，就会冷不丁地失败一次。更别提如果测试是并行跑的（比如用了 pytest-xdist），多个测试同时改 os.environ，那简直就是一场混乱。这不是“临时替换”，而是实实在在的“永久污染”。

为什么直接操作 os.environ 这么不靠谱

说白了，os.environ 是个全局的字典，任何地方改了它，整个进程都受影响。测试的本质是隔离，如果你在测试 A 里设了一个变量，测试 B 跑的时候恰好依赖这个变量的默认值，那结果就很微妙了——可能时而通过时而失败，完全取决于执行顺序。而 pytest 的 monkeypatch fixture 就是专门来解决这个问题的，它的核心设计就是“局部修改，自动还原”。

• monkeypatch 会在测试函数退出时，自动把环境变量恢复到原来的值，不用你手动写 del 或者 pop。
• 它只影响当前测试函数，不干扰其他测试，哪怕是并行执行也互不冲突。
• 更重要的是，即使测试中途抛了异常，monkeypatch 也能保证环境变量被还原，不会留下脏数据。

用 monkeypatch.setenv() 替换单个环境变量

这是最常用、也最安全的方式，适合绝大多数需要控制某个环境变量值的场景，比如打开调试模式、注入测试用的 token 等等。

def test_api_client_with_mocked_env(monkeypatch):
    monkeypatch.setenv("DEBUG", "1")
    monkeypatch.setenv("API_URL", "https://test.example.com")
    # 此时代码里调用 os.getenv("DEBUG") 会返回 "1"
    client = APIClient()
    assert client.debug is True
    assert client.base_url == "https://test.example.com"

注意几个细节：

• 传入的值必须是字符串，monkeypatch.setenv("PORT", 8080) 会直接报 TypeError，因为 8080 是整数。
• 如果这个环境变量原本不存在，setenv 会直接新增；如果存在，则覆盖——不需要提前判断。
• 这个操作只影响当前测试函数，函数结束就失效，完全不用写 del os.environ["DEBUG"] 这种清理代码。

用 monkeypatch.delenv() 模拟变量未设置的场景

有些逻辑依赖环境变量“不存在”来走默认分支，比如配置回退到本地文件。这时候不能设为空字符串，而是要彻底删除这个键。

def test_config_falls_back_to_local_file(monkeypatch):
    monkeypatch.delenv("CONFIG_PATH", raising=False)
    config = load_config()
    assert config.source == "local"

这里 raising=False 这个参数很关键：如果变量本来就不在 os.environ 中，设为 True（默认值）会抛 KeyError。而设成 False，它就会静默地忽略，直接跳过。

还有个常见的错误做法：用 os.environ.pop("CONFIG_PATH", None) 手动删除。这个操作绕过了 monkeypatch 的自动还原机制，测试结束后环境变量就真的没了，后面的测试可能因此遭殃。

如果确实需要验证某个变量完全没被读取，可以配合 monkeypatch.setattr(os, "environ", {}) 来彻底清空——但这一招影响范围太大，慎用。

避免在 conftest.py 里全局 monkeypatch.setenv()

有人可能想“一劳永逸”，在 conftest.py 里用 autouse=True 的 fixture 统一设置环境变量，结果发现部分测试行为变得很奇怪。

• monkeypatch fixture 本身的作用域是函数级（scope="function"），即使你在 conftest.py 里定义它，也不能跨测试共享状态。
• 更严重的是：不同测试可能依赖不同的环境变量组合，全局预设会导致冲突，或者掩盖真实的问题——比如某个测试本该因为缺少某个变量而失败，结果因为全局预设而通过了。
• 真有共用需求，应该提取为参数化 fixture，显式传入所需变量。比如：@pytest.mark.parametrize("env_vars", [{"DEBUG": "1"}, {"LOG_LEVEL": "WARN"}])。这样每个测试都能明确知道自己要的环境变量是什么，清晰又可控。

关于环境变量的 mock，有一个基本原则：不是越早设越好，而是越靠近被测代码读取点越稳。多数时候，就放在具体测试函数的开头，干净、明确、没有副作用。