只需安装 allure-pytest，它作为 pytest 与 Allure 报告的唯一 Python 桥梁生成 JSON 数据；pytest-allure-adaptor 已废弃，allure-commandline 需单独安装 Java CLI 工具。
直接装 allure-pytest 就够了，不用装 pytest-allure-adaptor（已废弃）或 allure-commandline（命令行工具需单独安装，不是 Python 包）。
为什么只装 allure-pytest？
它负责让 pytest 在运行时生成 Allure 兼容的原始数据（JSON 格式），是连接 pytest 和 Allure 报告的唯一 Python 层桥梁。旧版 pytest-allure-adaptor 不支持 Allure 2.x 的新特性，且已停止维护；allure-commandline 是 Java 写的 CLI 工具，必须独立安装，不能用 pip install 装。
常见错误现象：
• 安装了 pytest-allure-adaptor 后报 ImportError: No module named 'allure'
• 运行 pytest --alluredir=report 没反应、无文件生成 —— 很可能是插件没装对或版本冲突
- 正确命令：
pip install allure-pytest - 验证是否生效：
pytest --help | findstr alluredir（Windows）或pytest --help | grep alluredir（macOS/Linux），能看到该参数说明即成功 - 注意版本兼容性：Allure 2.13+ 对应
allure-pytest>=2.10.0；若用 Python 3.12+，建议选allure-pytest>=2.13.5避免pydantic冲突
--alluredir 参数必须显式指定路径
它不默认写入当前目录，也不接受相对路径缩写（如 --alluredir report 可能被误解析）。路径必须存在或可自动创建，但建议提前建好，避免权限或路径空格导致静默失败。
立即学习“Python免费学习笔记（深入）”；
- 推荐写法：
pytest --alluredir=./allure-results（Linux/macOS）或pytest --alluredir=.\allure-results（Windows） - 避免写法：
pytest --alluredir=report/（末尾斜杠在某些 shell 下引发异常）、pytest --alluredir="my report"（含空格未引号包裹，Windows CMD 下大概率失败） - 生成后检查：
ls ./allure-results应看到一堆*.json文件，至少一个非空文件；全为空或只有.lock文件，说明测试根本没跑进去（比如文件名拼错、pytest 没识别到 test_*.py）
allure CLI 工具必须单独安装，且 PATH 要配对
allure-pytest 只管“写数据”，真正“读数据并渲染 HTML”的是 allure 命令行程序（Java 实现）。它不在 Python 生态里，不能靠 pip 装完就用。
- Windows：下载
allure-2.21.0.zip（2026 年最新稳定版），解压后把allure-2.21.0\bin加进系统PATH，重启终端后运行allure --version确认 - macOS：用
brew install allure最省事；若用curl手动装，注意allure脚本里硬编码的JAVA_HOME路径可能指向已卸载的 JDK - 常见卡点：
'allure' is not recognized（PATH 没生效）、Could not find or load main class io.qameta.allure.CommandLine（JRE 版本太低，Allure 2.20+ 需 JDK 11+）
生成报告时 --clean 不是可选项，是必选项
重复执行 allure generate 时不加 --clean，旧报告资源（JS/CSS/图片）会残留，新 JSON 数据可能被旧缓存覆盖，导致页面空白、图表错乱、用例数不更新等诡异问题。
- 安全写法：
allure generate ./allure-results -o ./allure-report --clean - 别图省事写成：
allure generate ./allure-results -o ./allure-report（尤其在 CI 中，历史残留极易引发误判） - 如果只想快速预览，用
allure serve ./allure-results更稳妥——它每次启动都临时构建，天然隔离
最易被忽略的是：Allure 报告依赖前端资源加载，直接双击 index.html 必然白屏（浏览器禁止本地 file:// 协议跨域读取 JS）。必须用 allure serve 或 allure open 启服务，或者用 PyCharm 右键 Open in Browser（它内部起了本地服务）。这点和 pytest-html 完全不同，别凭经验跳过。
