Python subprocess.run 怎样为子进程传入独立环境变量

需要给外部命令临时注入环境变量时，直接给 subprocess.run() 传 env 映射即可。工程代码通常先复制 os.environ，再覆盖少量业务变量；这样子进程能拿到 APP_MODE、API_BASE 等配置，Python 父进程的环境不会被改写。

官方地址：https://docs.python.org/3/library/subprocess.html#subprocess.run

关键点是：env 不是“在子进程里执行 export”，而是创建子进程时传入一份环境映射。传入的映射会替代默认继承行为；如果只想改一个变量，先复制父环境再覆盖通常最稳妥。

复制父环境并覆盖业务变量

默认情况下，subprocess.run() 会继承当前进程环境。只改一个配置时，不建议从空字典开始，因为外部命令可能依赖 PATH、代理或平台变量。复制后覆盖既清晰，也不会污染后续代码。

import os

# 复制当前进程环境，避免直接改写 os.environ
child_env = os.environ.copy()
# 只为这次子进程覆盖业务配置
child_env["APP_MODE"] = "staging"
child_env["API_BASE"] = "https://api.example.test"

如果配置值来自用户输入或密钥管理系统，应在进入命令参数和日志前分别处理，避免把敏感值拼进 shell 命令。这里的示例地址只是演示值，不代表真实服务入口。

把 env 显式传给 subprocess.run

将字典作为关键字参数传入即可。下面让 Python 子进程读取变量并输出，使用列表参数避免额外 shell 解析；capture_output=True 便于程序检查结果。

import os
import subprocess

child_env = os.environ.copy()
child_env["APP_MODE"] = "staging"

try:
    result = subprocess.run(
        ["python", "-c", "import os; print(os.getenv('APP_MODE', 'missing'))"],
        env=child_env,             # 只把这份环境交给新进程
        capture_output=True,       # 同时收集 stdout 和 stderr
        text=True,                 # 按文本读取输出，便于比较结果
        check=True,                # 非零退出码转为 CalledProcessError
    )
except subprocess.CalledProcessError as exc:
    # 命令失败时保留退出码和错误输出，便于定位环境问题
    print(f"exit={exc.returncode}, stderr={exc.stderr.strip()}")
else:
    # 输出应为 staging，说明子进程读取到了覆盖后的变量
    print(result.stdout.strip())

程序退出后，当前 Python 进程中的 os.getenv("APP_MODE") 不会因为这次调用自动变成 staging。这是父子进程环境隔离的正常结果，不是参数失效。

区分继承环境、替换环境与跨平台边界

三种写法的差异可以先用一张表判断：

最小映射容易踩到两个坑：命令只写 python 或 git 时可能找不到 PATH；Windows 程序还可能需要有效的 SystemRoot。跨平台脚本更适合从 os.environ.copy() 起步，再按需删除变量，而不是凭经验手写一套空环境。

另外，env 的键和值在常规场景使用字符串即可；POSIX 允许使用字节映射，但没有必要为了普通配置引入额外编码复杂度。

用返回码和输出验证结果

不要只看命令有没有启动。对脚本任务，至少同时观察返回码、标准输出和标准错误；需要失败即中断时启用 check=True，需要自行分支时则读取 returncode。

import os
import subprocess

env = os.environ.copy()
env["FEATURE_FLAG"] = "on"

# 用当前解释器启动子进程，减少不同机器上的 python 命令差异
cmd = [
    os.sys.executable,
    "-c",
    "import os; print(os.getenv('FEATURE_FLAG', 'off'))",
]
result = subprocess.run(cmd, env=env, capture_output=True, text=True)

# 返回码为 0 且输出为 on，才同时说明命令成功并读到了变量
if result.returncode != 0:
    raise RuntimeError(result.stderr.strip() or "child process failed")
if result.stdout.strip() != "on":
    raise RuntimeError("child process did not receive FEATURE_FLAG")

检查清单可以压缩成四项：变量是否写入传给 run() 的那份字典；命令是否依赖 PATH；是否错误地期待子进程修改父环境；失败时是否保留 stderr 与退出码。做到这四点，绝大多数“env 不生效”都能定位。

常见问题

给 env 传一个新字典后，为什么命令找不到？

新字典不会自动补齐父进程环境。使用 os.environ.copy()，或在最小映射中显式提供正确的 PATH。

子进程里设置的变量能回到当前终端吗？

不能。子进程只拥有自己的环境副本；要改变父 shell，需要由 shell 本身执行设置，不能靠子进程反向修改。

什么时候应该使用 check=True？

当非零退出码代表当前任务失败时使用；如果某些退出码是业务分支，就保留默认值并自行检查 returncode。