Tox 4 升级指南：全面解析重大变更与迁移策略

Tox 4 升级指南：全面解析重大变更与迁移策略

tox Command line driven CI frontend and development task automation tool. 项目地址: https://gitcode.com/gh_mirrors/to/tox

前言

Tox 作为 Python 生态中广泛使用的测试工具，其第四版带来了诸多重要改进。本文将从技术角度深入解析 Tox 4 的升级要点，帮助开发者顺利完成迁移。

Python 版本支持变更

Tox 4 对运行环境提出了更高要求：

• 最低 Python 版本：必须使用 Python 3.7 或更高版本
• 解释器支持：仅官方测试 CPython 环境
• 兼容性说明：
  • 仍可为旧版 Python 创建测试环境
  • PyPy 支持转为"尽力而为"模式（社区贡献驱动）

配置文件语法变更

注释与转义规则

Tox 4 严格规范了注释处理：

# Tox 3 有效写法
commands = bash -c "echo 'foo#bar'"

# Tox 4 正确写法（需转义）
commands = bash -c "echo 'foo\#bar'"

环境变量传递

pass_env 的分隔符规则统一：

# 旧版空格分隔（不再支持）
passenv = ALPHA BETA

# 新版逗号或换行分隔
passenv = ALPHA, BETA
passenv =
    ALPHA
    BETA

依赖安装限制

• 禁止在 deps 中使用 -U 标志
• install_command 必须返回非空值

重要行为变更

环境命名规范

禁止使用含多个 Python 版本的混淆命名：

• ❌ name-py39-pypy
• ❌ py39-py310

可通过 ignore_basepython_conflict 临时绕过，但建议重构命名方案。

执行结果判定

当所有环境都被跳过时，Tox 4 将返回失败状态码：

tox run --skip-missing-interpreters=true -e py35  # 若无Python 3.5则失败

变量替换调整

• 移除 distshare 和 homedir 替换变量
• basepython 保持原始格式（如 py39），建议改用：
  • py_impl：Python 实现（如 cpython）
  • py_dot_ver：版本号（如 3.9）

插件系统重构

Tox 4 进行了彻底的重构，关键变化包括：

• 不兼容的 API：所有插件必须针对新架构重写
• 开发指南：参考官方插件文档进行适配
• 兼容层：仅保留配置格式兼容性

废弃配置项替代方案

| 废弃项 | 替代方案 | |---------------------|----------------------------------| | indexserver | 使用自定义 PyPI 服务器配置 | | whitelist_externals | 改用 allowlist_externals | | isolated_build | 隔离构建现为默认行为 | | distdir | 使用 TOX_PACKAGE 环境变量 |

命令行接口变更

子命令体系

Tox 4 引入现代子命令结构：

# 传统用法（兼容模式）
tox -e py310,style

# 推荐新写法
tox run -e py310,style
tox r -e py310,style  # 简写形式

参数解析调整

• 移除 --parallel--safe-build 参数
• 测试命令参数必须用 -- 分隔
• --index-url 改用 PIP_INDEX_URL 环境变量

打包环境改进

隔离构建

• 默认启用隔离构建环境
• 构建环境命名规则：
  • 源码分发：.pkg
  • Wheel：.pkg-<impl><version>（如 .pkg-cpython311）

配置继承

[pkgenv]  # 公共配置
pass_env = PKG_CONFIG_PATH

[testenv:.pkg-cpython311]  # 特定环境
pass_env = {[pkgenv]pass_env}

可编辑安装

支持 PEP 660 标准：

[testenv:dev]
package = editable  # 首选现代模式
package = editable-legacy  # 回退方案

输出与交互改进

• 彩色输出：默认启用，可通过以下方式禁用：
  • 环境变量：TERM=dumb 或 NO_COLOR=1
  • 参数：--colored no
• 调试信息：-v 参数改为交错显示模式

环境复用限制

禁止环境复用行为（原为未定义行为）：

[testenv]
envdir = .tox/venv  # 多个环境共享目录将报错

最佳实践建议

1. 渐进式迁移：先确保现有配置在 Tox 3 下正常工作
2. 环境隔离：为不同 Python 版本创建独立环境
3. 明确依赖：避免使用隐式继承的配置
4. 现代语法：优先采用子命令等新特性
5. 构建优化：合理规划打包环境配置

通过理解这些关键变更点，开发者可以更顺利地完成到 Tox 4 的过渡，充分利用新版本带来的改进。

tox Command line driven CI frontend and development task automation tool. 项目地址: https://gitcode.com/gh_mirrors/to/tox