mdBook 安装教程：快速上手，从零到跑起来只需 5 分钟

mdBook 安装教程：快速上手，从零到跑起来只需 5 分钟

【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址: https://gitcode.com/gh_mirrors/md/mdBook

mdBook 是一个用 Rust 编写的开源工具，能把 Markdown 文件自动生成为带目录导航、搜索框的现代化静态文档网站，常被用来编写技术手册与产品文档。整个安装过程只需 3 步、约 5 分钟，装好后马上就能建出你的第一本书。

mdBook 安装前检查清单：环境、依赖与网络

开始前花 30 秒确认下面几项，能省去大部分返工：

• ✅ 操作系统：Windows、macOS、Linux 任一均可，无需额外系统组件
• ✅ 依赖软件：若走 Cargo 安装，需先装好 Rust 工具链（含 Cargo 包管理器）
• ✅ 网络：能正常访问 crates.io 软件源；离线环境请改用预编译二进制方式
• ✅ 权限：Cargo 全局目录~/.cargo/bin可写，多用户机器需留意当前账户权限

⚠️ 前置预警：Rust 版本低于 1.88 时编译会直接报 MSRV（最低支持版本）错误；PATH 没配好时，终端会提示 "command not found"。

Cargo 安装 mdBook：推荐开发者使用的一条命令方案

对绝大多数用户来说，这是最省心的路径——一条命令装好，还能一条命令升级。整个安装分 3 步。

第 1 步：安装 Rust 工具链（1.88 及以上）

如果你还没有 Rust，建议用官方推荐的 rustup 方式安装：Windows 运行 rustup-init.exe，macOS/Linux 执行 rustup-init 脚本，按提示选择默认配置即可。装完后用rustc --version确认版本不低于 1.88。mdBook 当前版本要求 Rust 1.88 及以上，这保证了编译速度和稳定性。

第 2 步：执行安装命令

cargo install mdbook

这条命令会从 crates.io 自动拉取源码、完成编译，并把mdbook可执行文件放入 Cargo 的全局二进制目录（默认~/.cargo/bin）。首次编译需要几分钟，属正常现象，请耐心等待。

第 3 步：把 Cargo 目录加入 PATH

确认~/.cargo/bin（Windows 为%USERPROFILE%\.cargo\bin）已写入系统 PATH 环境变量。重新打开一个终端窗口使其生效，再执行mdbook --version就能看到版本号。建议 PATH 配好再继续，否则后续所有mdbook命令都会提示找不到命令。

升级与卸载同样简单：再次执行cargo install mdbook即可自动更新到最新版；cargo uninstall mdbook一键卸载。

其他安装方式速查：二进制包与源码构建怎么选

• 预编译二进制：从 mdBook 的发布页下载对应平台的压缩包，解压即得可执行文件。适合公司内网、CI 流水线或纯粹不想碰 Rust 工具链的场景。
• 源码构建：git clone https://gitcode.com/gh_mirrors/md/mdBook后进入目录执行cargo install --path .。适合想体验最新功能、或打算阅读/修改源码的开发者。

安装验证与首次运行：30 秒生成你的第一本书

先验证安装是否成功：

mdbook --version

看到形如mdbook 0.5.4的版本号输出即代表安装成功。接下来 30 秒跑通最小示例：

mdbook init my-first-book cd my-first-book mdbook serve --open

init会询问书名并自动生成book.toml配置和src/SUMMARY.md章节目录；serve启动本地服务器并在默认浏览器打开页面，同时监听文件变化——你编辑任意章节保存后，它会自动重建并刷新浏览器。

💡 想发布成静态站点？在项目根目录执行mdbook build，生成的 HTML 会输出到book/目录，把它扔到任意静态服务器或对象存储上即可对外托管。

mdBook 常见报错与避坑指南

为什么提示 command not found？

安装成功但 PATH 未生效。检查~/.cargo/bin是否在 PATH 中，并重新打开终端；Windows 用户还需重开命令行窗口或重启终端程序。

编译时报 Rust 版本过低怎么办？

mdBook 要求 Rust 1.88 及以上。执行rustup update stable升级工具链后重试即可。

cargo install 下载超时、反复失败？

多为网络波动。可稍后重试；若在受限网络环境，建议改走预编译二进制方案，或配置 crates 镜像源加速拉取。

生成的网站没有搜索框？

搜索功能依赖默认启用的 search 特性，安装时请勿加--no-default-features，按本文默认命令安装即可。

结语：装好后还能做什么

装好后，你就能用纯 Markdown 快速产出带目录导航、搜索、代码高亮的文档网站，还能借助mdbook test验证 Rust 代码示例、用mdbook watch实现保存即重建。想深入配置项、主题定制与预处理器玩法，官方使用指南就放在本仓库的guide/src目录下，建议按其中的 SUMMARY.md 顺序阅读，或直接以仓库自带的 guide 为例体验完整效果。

【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址: https://gitcode.com/gh_mirrors/md/mdBook