subprocess调用Python脚本未识别PYTHONPATH报ModuleNotFound错误

AI 小北

2026-8-31

问题根因

这个异常本质是子进程的运行环境和预期环境不一致，和本地/服务器的系统差异无关，核心触发点有三个：

服务启动模式的环境隔离：预发布环境的Django基本都是用systemd、supervisor这类进程管理器托管启动，启动时不会加载当前用户.bashrc/.profile里配置的交互式shell环境变量。你在终端登录后能查到PYTHONPATH配置正确，不代表Django服务进程自身的环境里存在这个变量。本地开发时是在终端里直接启动runserver，继承了终端的环境变量，所以不会复现问题。
非交互式shell的变量过滤：用shell=True启动子进程时，Ubuntu默认的bash配置会对非交互式shell做环境变量裁剪，很多用户自定义的环境变量不会传递到nohup启动的后台进程里。
subprocess参数写法不规范：shell=True时传入列表参数，Python只会把列表第一个元素作为shell命令执行，其余元素会被识别为shell进程本身的启动参数，不会传给目标python命令，进一步放大了环境传递的异常概率。

快速排查步骤

第一步：在触发subprocess调用的view代码里，先打印Django进程自身的PYTHONPATH值，确认服务进程是否真的拿到了配置：

import os
# 触发调用前打印，看输出日志里的值
print("当前Django进程PYTHONPATH：", os.environ.get("PYTHONPATH", "未找到该变量"))

第二步：临时修改subprocess调用，让子进程输出自己的PYTHONPATH到临时文件，确认子进程拿到的环境：

subprocess.run("echo $PYTHONPATH > /tmp/sub_pythonpath.log", shell=True)

触发接口后查看/tmp/sub_pythonpath.log，大概率文件内容为空，或者不包含/home/myproject路径。

修复方案

优先选第一种显式传参的方案，完全不依赖系统环境配置，兼容性最好：

调用subprocess时显式注入需要的环境变量，修正不规范的参数写法：

import os
import subprocess

# 复制当前进程环境，手动追加项目路径到PYTHONPATH
run_env = os.environ.copy()
project_root = "/home/myproject"
if run_env.get("PYTHONPATH"):
    run_env["PYTHONPATH"] = f"{project_root}:{run_env['PYTHONPATH']}"
else:
    run_env["PYTHONPATH"] = project_root

# 不依赖shell解析，直接传参数列表，去掉不必要的shell=True风险
with open("/dev/null", "wb") as devnull:
    subprocess.Popen(
        ["python3", "/home/myproject/scripts/script.py"],
        env=run_env,
        stdout=devnull,
        stderr=devnull,
        start_new_session=True # 等价于nohup后台运行，避免父进程退出后子进程被终止
    )

如果是进程管理器托管的Django服务，直接在服务配置里写死环境变量，从根源避免环境传递问题：
- systemd托管：在对应的.service文件中添加Environment="PYTHONPATH=/home/myproject"，执行systemctl daemon-reload后重启服务即可
- supervisor托管：在对应的配置块中添加environment=PYTHONPATH="/home/myproject"，重载配置后重启服务即可

注意：不要把服务运行依赖的环境变量配置在.bashrc、.zshrc这类仅交互式登录shell才会加载的配置文件中，这类配置只对用户手动打开的终端生效，后台服务进程启动时不会读取。

内容的提问来源于stack exchange，提问作者Kravennagen