本文详细讲解如何在无网络环境（如内网或隔离服务器）中成功构建 mongodb 官方 html 文档，涵盖 python 版本适配、giza 工具链兼容性修复、两次 make 执行机制及生成后文档的本地化注意事项。
本文详细讲解如何在无网络环境（如内网或隔离服务器）中成功构建 mongodb 官方 html 文档，涵盖 python 版本适配、giza 工具链兼容性修复、两次 make 执行机制及生成后文档的本地化注意事项。
MongoDB 官方文档仓库（mongodb/docs）虽提供开源的文档源码，但其构建系统 giza 依赖陈旧且高度定制化的 Python 生态，直接在现代环境中（如 Python 3.10+）执行 make html 极易失败——典型错误如 ModuleNotFoundError: No module named 'sphinx.make_mode'，根源在于 giza（v0.5.18）与新版 Sphinx（≥4.0）不兼容，且其内部硬编码了已废弃的 sphinx.make_mode 模块。
✅ 推荐路径：使用 Python 2.7 + 兼容版依赖组合
尽管 Python 2.7 已于 2020 年终止支持，但这是目前唯一能稳定驱动 giza 的运行时环境。请按以下步骤操作（所有操作均在离线前提下可复现）：
-
准备 Python 2.7 环境
使用pyenv或系统包管理器安装 Python 2.7.18（最终稳定版），并创建干净虚拟环境：pyenv install 2.7.18 pyenv virtualenv 2.7.18 giza-py27 pyenv activate giza-py27
-
安装兼容依赖（关键！）
避免直接pip install giza（会触发 Pygments ≥2.12.0 冲突）。应手动指定历史兼容版本：pip install "Pygments==2.11.2" \ "requests==2.22.0" \ "urllib3==1.25.11" \ "sphinx==1.8.5" \ "giza==0.5.18"⚠️ 注意：
sphinx==1.8.5是giza能识别sphinx.make_mode的最高兼容版本；更高版本已移除该模块。 -
克隆并构建文档
git clone https://www.php.cn/link/0eb80e91706978817c42133f456e368d.git cd docs # 第一次执行（必失败，用于初始化缓存与配置） make html 2>&1 | grep -E "(ERROR|WARNING)" # 第二次执行（关键！自动跳过已失败任务，完成构建） make html
成功后，HTML 文件将输出至
build/master/html/目录。 -
重要限制与本地化建议
- ✅ 生成的 HTML 可完全离线浏览（含全部章节、搜索、导航）；
- ❌ 但部分链接仍指向外部资源（如
https://www.mongodb.com/docs/drivers/、API 参考objects.inv文件），需手动替换为本地路径或使用sed批量重写：sed -i 's|https://www\.mongodb\.com/docs/|/docs/|g' build/master/html/*.html
- ? 首次构建失败日志中的 Unicode 错误（如
ascii codec can't encode character u'\xe1'）属正常现象，源于早期源码未声明 UTF-8 编码，第二次构建会自动绕过。
? 替代方案提示（推荐给新项目）
若仅需查阅而非贡献文档，强烈建议优先使用 MongoDB 官方提供的离线友好型文档分发方式：
- 访问 MongoDB Docs 下载页 → 查找 “Download PDF/EPUB/HTML” 按钮（部分版本提供预构建 ZIP 包）；
- 或直接使用 MongoDB Atlas 文档镜像服务（支持离线导出）；
- 对于最新版（如 v8.3+），官方已逐步迁移至基于 Docusaurus 的新构建流程，未来将原生支持 Python 3 和现代工具链。
综上，Python 2.7 + sphinx 1.8.5 + giza 0.5.18 是当前离线构建 MongoDB 传统文档的唯一经验证通路。虽技术栈陈旧，但步骤明确、可重复。建议将整个构建环境（含 Python 2.7、依赖包 wheel 文件、docs 仓库快照）打包为离线镜像，供团队长期复用。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
