tox 是 Python 多版本测试自动化与环境隔离工具，它通过声明式配置（如 envlist、deps、commands）将“在不同 Python 环境中可靠、可重复、可审计地运行测试”变为一条命令即可完成的确定性流程，解决环境碎片化与执行不可控问题，而非简单多装 Python。
tox 不是让你“多装几个 Python”，而是帮你把“哪个版本跑什么命令、装什么依赖”这件事，变成一条命令就能确定执行的流程。 它解决的不是“能不能跑”，而是“每次跑的结果是否可复现、可审计、可跨人复用”。本地能过 CI 报错？同事环境不一致？升级 Python 后不敢合代码？这些都不是配置问题，是执行路径没被声明和隔离——tox 就是干这个的。
怎么写 envlist 才不会报 InterpreterNotFound
envlist 不是标签，是 tox 去系统里找真实可执行文件的指令。它默认按 python3.X 的名字去 PATH 里查，比如 py38 对应 python3.8，py310 对应 python3.10。
- 如果本地没装
python3.10，运行tox -e py310会直接失败，报错InterpreterNotFound: python3.10 - 加
skip_missing_interpreters = true可以跳过缺失版本，但别依赖它——CI 环境必须提前装好对应解释器，否则矩阵就断了 - 用
pyenv管理多版本时，确保已执行pyenv global 3.8.18 3.10.12 3.12.6，且pyenv shell或pyenv local不干扰全局查找逻辑 - Windows 用户注意：
python3.10.exe必须在 PATH 中，不能只靠py -3.10；tox 不识别pylauncher 语法
deps 里怎么处理不同 Python 版本的依赖差异
很多包只在旧版本需要 backport，比如 typing_extensions 在 Python
- 用条件表达式：
typing_extensions ; python_version < "3.8"—— 注意分号后有空格，<要 HTML 实体转义为（在 <code>.ini中）或直接写<（在.toml中） - 也可以拆成环境特化配置：
[testenv:py38]下单独写deps = typing_extensions，避免条件判断复杂化 - 不要在
deps里写-e .或./src这类路径依赖，tox 默认不自动安装项目本身；要用install_command或显式加pip install -e .到commands - 若依赖含 C 扩展（如
cryptography），注意某些 Python 版本可能因 OpenSSL 版本不匹配而编译失败，建议在 CI 中预装对应 dev 包
为什么 tox -e lint 和 tox -e py312 是同一套机制
tox 的环境名不是预设关键词，而是任意字符串——lint、type、build 和 py312 在 tox 看来没有本质区别，都是你定义的执行上下文。
立即学习“Python免费学习笔记（深入）”；
-
[env.lint]（TOML）或[testenv:lint]（INI）可以完全脱离 Python 版本，只装black和flake8，命令也只跑格式检查 - 这种写法让
tox成为“任务调度器”，不只是“Python 版本测试器”；CI 里一个tox命令就能串起 lint → typecheck → test → docs 构建 - 注意：自定义环境不继承
[testenv]的basepython，所以[env:lint]默认用当前系统 Python，不需要指定basepython = python3.10 - 多个环境并行跑用
tox -p auto，但并非所有命令都适合并行（比如写同一份 coverage 文件时会冲突）
CI 中 tox 失败最常见的三个盲点
CI 报错信息常掩盖真正原因，表面是 ModuleNotFoundError，实际可能是路径、缓存或权限问题。
- 忘记在 CI 配置中预装目标 Python 版本（GitHub Actions 要用
actions/setup-python显式指定，不能只靠系统自带） -
tox默认会构建源码分发包（sdist），若项目没配pyproject.toml或setup.py，会卡在python -m build阶段；加skipsdist = true可跳过 - 缓存虚拟环境导致依赖未更新（尤其用了
--recreate但没清掉旧缓存目录），建议 CI 中统一用tox --recreate --parallel-no-file-lock避免锁竞争
最易被忽略的是：tox 的环境隔离只管 Python 解释器和 pip 包，不管系统级工具（如 git、make）或环境变量（如 LD_LIBRARY_PATH）。这些必须在 CI 脚本里显式设置，不能指望 tox 自动继承。
