本文详细说明在无网络连接的独立计算机上，通过本地构建方式生成 MongoDB 官方 HTML 文档的方法，重点解决 giza 工具链与现代 Python 版本不兼容、Sphinx 模块缺失及依赖冲突等核心问题。
本文详细说明在无网络连接的独立计算机上，通过本地构建方式生成 mongodb 官方 html 文档的方法，重点解决 `giza` 工具链与现代 python 版本不兼容、sphinx 模块缺失及依赖冲突等核心问题。
MongoDB 官方文档源码托管于 GitHub 仓库 mongodb/docs，其构建系统基于已停止维护的 giza（v0.5.18，最后更新于2019年）和旧版 Sphinx，不支持 Python 3.x 原生运行。尽管官方文档页面（如 mongodb.com/docs）提供在线浏览与 PDF/EPUB 下载，但若需完全离线、可本地索引、带完整交叉引用的 HTML 文档集，必须本地构建——而该过程需绕过现代 Python 生态的兼容性陷阱。
✅ 推荐可行路径（经验证，适用于 2026 年环境）：
-
使用 Python 2.7 环境（唯一稳定选项）
giza的sphinx.make_mode模块仅存在于 Sphinx ModuleNotFoundError；Python 2.7 虽已 EOL，但仍是当前构建链的事实标准运行时。# 创建隔离的 Python 2.7 虚拟环境（以 pyenv 或 system python2.7 为例） virtualenv -p python2.7 venv-giza source venv-giza/bin/activate # 安装兼容版本栈（参考 Stack Overflow 验证方案） pip install "Pygments
-
克隆并初始化文档仓库
git clone https://www.php.cn/link/0eb80e91706978817c42133f456e368d.git cd docs # 可选：检出与你使用的 MongoDB 版本匹配的分支（如 v7.0、v8.3） git checkout v8.3
-
执行两次
make html（关键步骤）
第一次运行会因编码错误（如 Unicode 字符\xe1）、远程 intersphinx 引用失败（如https://api.mongodb.com/python/current/objects.inv返回 404）而中断，但会生成基础结构与缓存；
第二次运行则能跳过失败项，完成 HTML 渲染：make html # 首次：预期失败，忽略 ERROR 和 WARNING make html # 再次：成功生成 build/master/html/
✅ 输出目录：
build/master/html/—— 此即完整离线 HTML 文档根目录，含搜索、导航、响应式布局。
⚠️ 重要注意事项：
-
非完全离线：生成的 HTML 中仍包含大量指向
mongodb.com的外部链接（如驱动下载页、指南链接、API 参考跳转），这些需手动替换或通过脚本批量重写为相对路径（例如将https://www.php.cn/link/98a4fe5f4cd325b0d131fffdcb9f618cdrivers/替换为./drivers/index.html）。 -
字体与图标依赖 CDN：部分 CSS 引用了 Google Fonts 或 Font Awesome CDN，离线访问时图标可能缺失。建议提前下载
fonts.googleapis.com相关 CSS/woff2 文件，并修改build/master/html/_static/css/custom.css中的@import语句。 -
替代方案更推荐（尤其对新用户）：
若仅需查阅而非定制化构建，直接下载官方发布的离线包是更优选择：
→ 访问 MongoDB Docs 官网归档页 → 滚动至底部点击 “Download Offline Documentation” → 选择对应版本（如 MongoDB Manual v8.3 (HTML, ZIP)）→ 解压即用（无需构建，100% 离线，含所有内部链接）。该 ZIP 包由 MongoDB 团队每日 CI 构建并验证，稳定性远超本地giza构建结果。
? 总结：本地构建 MongoDB 文档是一项“向后兼容工程”，本质是复现 2018–2019 年的构建环境。对于生产级离线部署，优先采用官方 ZIP 离线包；仅当需定制内容（如内嵌私有扩展、品牌化 CSS、增删章节）时，才启用 giza + Python 2.7 方案，并务必执行两次 make html。随着 MongoDB 文档平台持续演进（如新版采用 Docusaurus 或自研工具链），giza 将逐步退出历史舞台——这也是当前构建困难的根本原因。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
