pytest-xdist的--ssh远程执行实为通过execnet通道间接实现，并非真正远程启动进程，常见失败原因包括execnet兼容性问题、ssh配置解析失败、远端python环境缺失或版本不匹配等。
pytest-xdist 本身不支持真正的“远程执行”——它只做本地多进程分发，所谓“远程”其实是靠 execnet 的 socket 或 SSH 通道间接实现的。直接跑 pytest -n 4 --ssh 并不会把测试进程真正在远端启动，而是复用 execnet 的通道机制在远端机器上拉起 Python worker 进程。
为什么 --ssh 参数常报错或静默失败
常见现象是命令无报错但测试全在本地跑、stderr 显示 Connection refused、或者卡在 execnet.gateway_bootstrap 阶段。
-
pytest-xdist的--ssh依赖已停止维护的execnet库，而新版paramiko（如 3.0+）与之存在兼容问题 -
~/.ssh/config中若用了ProxyCommand、Include或非标准密钥路径（比如IdentityFile ~/.ssh/id_ed25519），execnet 无法正确解析 - 远端机器必须预装 Python 且可执行
python -c "import execnet"，否则 worker 启动失败，但错误不透出到主进程 - SSH 用户需有免密 sudo 权限（如果测试涉及服务启停等操作），否则
rsync或python调用会因权限被拒中断
--tx socket= 模式比 --ssh 更可控
socket 模式绕过 SSH 密钥和配置复杂度，适合局域网内快速验证，但要注意路径同步和端口冲突。
- 远端先手动运行
python socketserver.py（注意：GitHub 上的原始链接已失效，应使用https://raw.githubusercontent.com/pytest-dev/execnet/master/execnet/script/socketserver.py） - 本地执行时必须加
--rsyncdir ./，否则远端 worker 找不到测试文件；若项目含子模块或src/结构，需显式列出所有要同步的目录，例如--rsyncdir ./ --rsyncdir ./src --rsyncdir ./conftest.py - 避免硬写
-n 4，改用-n auto—— execnet 的 socket worker 启动慢，固定数量容易因超时导致部分 worker 未就绪就开跑，造成断连重试 - 端口
8888若被占用，远端启动时不会报错，但本地--tx socket=127.0.0.1:8888会连接失败；建议启动前用lsof -i :8888或netstat -tuln | grep 8888检查
远端环境必须满足的最小条件
不是“能 SSH 登录就行”，而是 execnet worker 进程实际运行所需的上下文。
- 远端 Python 版本需与本地一致（至少主版本相同），否则
execnet序列化失败，报错类似ValueError: unsupported pickle protocol - 远端需安装
pytest和所有测试依赖（如requests、pytest-mock），但pytest-xdist本身不用装——worker 只用execnet和pytestcore -
--rsyncdir同步后，远端工作目录是./下的副本，所以测试中用os.path.dirname(__file__)获取路径是安全的；但若用os.getcwd()，得到的是 execnet 启动时的工作目录（通常是/tmp附近），不可靠 - 远端不能启用 SELinux 或 AppArmor 限制 Python 执行网络或临时文件，否则 socket worker 会静默退出
真正麻烦的从来不是命令怎么写，而是 execnet 在远端启动 worker 时那一秒发生了什么——它不打日志、不抛异常、只默默失败。最稳的做法：先在远端手动跑一次 python -c "import execnet; gw = execnet.makegateway('socket=127.0.0.1:8888'); ch = gw.remote_exec('print(1)'); print(ch.receive())"，通了再套 pytest。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
