pytest-xdist是Python 3.11下唯一靠谱的并发方案，必须安装（pip install pytest-xdist）并用-n参数启用多进程（如-n 4或-n auto），它绕过GIL实现真正并行，而其他方案仅能异步调度。
pytest-xdist 是唯一靠谱的并发方案
Python 3.11 原生不支持 pytest 并发，必须依赖 pytest-xdist。它不是“可选插件”，而是当前事实标准——其他方案（如自写线程池、pytest-asyncio 配合协程）无法真正并行执行测试函数，仅能异步调度或模拟并发。
安装只需一行：
pip install pytest-xdist注意：不要装
pytest-xdist-legacy 或旧版 fork，它们不兼容 Python 3.11 的 asyncio 运行时和新语法。
用 -n 参数启动多进程，别碰 --workers
-n 是启用并发的核心开关，值可以是数字（如 -n 4）或特殊字符串（如 -n auto、-n logical）。它控制的是 worker 进程数，不是线程数，因此天然绕过 GIL 限制。
--workers 是旧版 xdist 的废弃参数，Python 3.11 下会直接报错：
unrecognized arguments: --workers务必只用
-n。
立即学习“Python免费学习笔记（深入）”；
-
-n auto：自动检测 CPU 核心数（含超线程），适合 CI/CD 环境 -
-n 2：明确指定 2 个进程，调试时更可控 - 避免
-n 0或负数——会静默退化为单进程，且无提示
fixture 和 setup/teardown 在并发下默认不共享
每个 worker 进程独立运行，意味着 session、package、module 级 fixture 的 scope 行为不变，但实际执行是隔离的：同一 @pytest.fixture(scope="session") 会在每个 worker 中各执行一次。
如果你依赖全局状态（如临时数据库、mock server），必须手动同步或改用外部协调机制：
- 用
tmpdir_factory而非tmp_path，前者支持跨 worker 共享临时目录路径 - 避免在
conftest.py中用模块级变量存状态——每个进程有独立内存空间 - 需要共享资源时，改用 Redis、文件锁或
pytest-xdist提供的worker_id标识做分片
常见报错：ImportError / ModuleNotFoundError 与路径问题
并发模式下，worker 进程可能因 sys.path 不一致而找不到模块，典型错误是：
ImportError: attempted relative import with no known parent package或
ModuleNotFoundError: No module named 'tests'。
根本原因是 xdist 启动子进程时未自动继承主进程的 PYTHONPATH 或当前工作目录。解决方法只有两个：
- 始终从项目根目录运行 pytest，且确保该目录在
sys.path首位（可用python -m pytest强制） - 在
pyproject.toml中显式配置：[tool.pytest.ini_options]<br>pythonpath = ["."]
- 绝对不要依赖 IDE 自动添加的路径——xdist 的子进程看不到 IDE 的环境变量
并发本身不会导致断言失败，但会让资源竞争类 bug（如共享文件写入、数据库连接复用）更快暴露出来。这类问题往往在单进程下不出现，一开 -n 就崩，得靠日志和 worker_id 定位具体是哪个进程踩了坑。
