这是一个 **Sphinx 文档构建工具与 Jinja2 模板引擎版本不兼容** 的典型错误，根本原因是： > ❌ **你安装的 `jinja2` 版本过高（≥ 3.1.0），而当前 Sphinx 版本太旧，不支持新 Jinja2 的 API 变更。** --- ### 🔍 错误链解析（逐层拆解） ```text ImportError: cannot import name 'pass_environment' from 'jinja2' ``` - ✅ `pass_environment` 是 Jinja2 **在 3.0.0 版本中引入**、用于装饰器标记函数需注入 `Environment` 实例的工具函数。 - ⚠️ 但在 **Jinja2 3.1.0+ 中，`pass_environment` 被彻底移除**（[官方 PR #1659](https://github.com/pallets/jinja/pull/1659)），改用 `@pass_context` + `context.environment` 替代。 - 📉 旧版 Sphinx（如 `< 4.0.0`）仍硬编码 `from jinja2 import pass_environment`，因此在 Jinja2 ≥ 3.1.0 环境下直接 `ImportError` 崩溃。 紧接着的 traceback： ```text File "...sphinx\util\rst.py", line 15, in <module> from jinja2 import Environment, pass_environment ``` → 明确指向 Sphinx 内部代码试图导入已删除的符号。 而前面的 `WARNING: Failed to collect submodules for 'sphinx.ext.napoleon'` 是 PyInstaller（或 sphinx-autobuild）在扫描依赖时，因 `import sphinx.ext.napoleon` 触发了 `sphinx` 全量导入 → 进而触发 `jinja2` 导入失败 → 整个模块加载中断，属于**连锁故障现象**，不是主因。 --- ### ✅ 解决方案（按推荐顺序） #### ✅ 方案 1：【最推荐】升级 Sphinx 到兼容新版 Jinja2 的版本（✅ 一劳永逸） ```bash pip install --upgrade sphinx>=4.0.0 ``` - ✅ `Sphinx >= 4.0.0`（发布于 2021-07）已完全移除对 `pass_environment` 的依赖，全面适配 Jinja2 3.0+（包括 3.1+）。 - ✅ 同时获得安全更新、新功能（如 MyST 支持、更好的 HTML 主题）。 - 💡 验证命令： ```bash python -c "import sphinx; print(sphinx.__version__)" python -c "import jinja2; print(jinja2.__version__)" ``` #### ⚠️ 方案 2：降级 Jinja2（临时 workaround，不推荐长期使用） ```bash pip install "jinja2<3.1.0" ``` - ✅ 例如安装 `jinja2==3.0.3`（最后支持 `pass_environment` 的稳定版）。 - ❌ 缺点：放弃 Jinja2 新特性 & 安全补丁；可能与其他依赖冲突（如 Flask ≥ 2.2.0 要求 Jinja2 ≥ 3.1.0）。 #### 🚫 方案 3：不要做（危险！） - ❌ 手动修改 `sphinx/util/rst.py` 删除 `pass_environment` —— 极易引发运行时错误，且每次 `pip install -U sphinx` 都会被覆盖。 - ❌ 使用 `--exclude-module sphinx` 让 PyInstaller 忽略 Sphinx —— 如果你**确实不需要 Sphinx**（比如只是误装了），可卸载它；但若你在构建文档，此操作将导致 `sphinx-build` 命令失效。 --- ### 🧪 如何快速诊断你的环境？ 运行以下命令，查看关键版本： ```bash pip show sphinx jinja2 ``` 输出示例（问题环境）： ```text Name: sphinx Version: 3.5.4 ← ❌ 太旧（<4.0.0） ... Name: jinja2 Version: 3.1.2 ← ❌ 太新（≥3.1.0） ``` ✅ 正确组合应为： - `sphinx>=4.0.0` + `jinja2>=3.0.0`（任意新版，如 3.1.x / 3.2.x / 4.x） - 或 `sphinx<4.0.0` + `jinja2<3.1.0`（如 3.0.3） --- ### 📌 附：PyInstaller 打包时遇到此错？说明什么？ 你在用 PyInstaller 打包一个**依赖 Sphinx 的脚本**（比如自动生成文档的工具），但打包环境里 `sphinx` 和 `jinja2` 版本不匹配。 ✅ 正确做法： 1. 先在开发环境修复版本（`pip install --upgrade sphinx`）； 2. 再运行 `pyinstaller your_script.py`； 3. PyInstaller 会自动收集修复后的 `sphinx` 模块，不再报错。 ⚠️ 注意：PyInstaller 的 `--exclude-module sphinx` 只是跳过收集，**不能解决运行时 `sphinx-build` 调用失败的问题**。 --- ### ✅ 总结一句话 > 这个错误 = **旧 Sphinx × 新 Jinja2**，本质是 API 移除导致的兼容性断裂；**升级 Sphinx 到 4.0.0+ 是唯一健壮、安全、可持续的解决方案。** ---