mdBook 完整安装指南：如何快速创建属于你的在线文档书籍

mdBook 完整安装指南：如何快速创建属于你的在线文档书籍

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

你是否有过这样的经历：写了一堆 Markdown 文档，散落在各个文件夹里，想分享给团队却找不到统一的展示方式；想搭一个项目文档站，却被 Hexo、VuePress 的配置折腾得头大。mdBook 就是为了解决这个痛点而生的开源工具——它是一个用 Rust 实现、可以把 Markdown 文件一键编译成现代风格在线书籍的静态站点生成器。你只需要按章节写 Markdown，它就能自动帮你生成目录导航、全文搜索和漂亮的页面主题，像 GitBook 一样好用，却不需要部署任何后端服务。下面这份教程会带你从零开始，把 mdBook 装好并跑起来。

先给自己 3 分钟：最快跑通一条路

在纠结"选哪种安装方式"之前，我建议你先用最省事的方式把它装起来，感受一下这本书到底长什么样。整个过程只需要两条命令，耗时取决于你的网络速度，通常在 3~5 分钟以内。

前提是你已经装好了 Rust 工具链，版本不低于 1.88（mdBook 的 Cargo.toml 里明确标注了rust-version = "1.88.0"）。如果还没装，先去 Rust 官网用官方脚本装好rustup，这一步同样很快。

打开终端，执行：

cargo install mdbook

Cargo 会从 crates.io 拉取 mdBook 的源码、完成编译，然后把可执行文件放进 Cargo 的全局二进制目录，默认是~/.cargo/bin/。安装完成后先验证一下：

mdbook --version

如果屏幕上出现了类似mdbook v0.5.4的版本号，恭喜你，安装成功。

接下来立刻体验"3 分钟造一本书"的快乐。随便找个空目录，执行：

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

serve会在本地启动一个预览服务器，--open参数会自动帮你打开浏览器。你会看到 mdBook 自动生成的默认页面——左侧是章节目录，右侧是正文，右上角还有搜索框。现在，打开src/chapter_1.md随便改几个字保存，浏览器里的页面会实时刷新。整个过程不需要写一行 HTML、不需要配置任何依赖，这就是 mdBook 最打动人的地方。

三条安装路线怎么选：一张表看明白

前面那条命令只是其中一种安装方式。mdBook 总共提供了三条安装路线，分别对应三类不同的使用场景。你可以先看下面这张对比表，再决定哪条路适合你。

路线一：下载预编译二进制，适合"我不想装 Rust"

去项目的发布页面，找到对应你系统平台的压缩包（Windows 选.zip，macOS 和 Linux 选.tar.gz），下载后解压，里面就是一个可以直接执行的mdbook文件。把解压出来的目录加进系统环境变量PATH，之后在任何终端里都能直接敲mdbook命令了。如果你从来没有接触过 Rust，这条路的门槛最低。

路线二：cargo install，适合"我日常写 Rust"

这也是官方文档里最推荐的安装方式，就是你刚才用的那条命令。它还有一个隐藏优点：想升级时，把cargo install mdbook原样再执行一遍，Cargo 会自动检查 crates.io 上有没有新版本，有就帮你重新编译安装。不想用了，一条cargo uninstall mdbook就能干净卸载。

路线三：从源码构建，适合"我要最新功能"

crates.io 上发布的版本总会比 GitHub 仓库里的开发版慢半拍。如果你急着用某个刚合入的新特性，可以指定 Git 地址直接构建。需要注意，开发版可能包含未稳定的接口和未修复的 bug，只推荐在测试环境或本地试用，别直接用在生产构建流水线上。

如果你想把代码拉下来本地研究，也可以克隆官方仓库自己编译。仓库地址是 https://gitcode.com/gh_mirrors/md/mdBook ，克隆后进入目录执行cargo build --release，编译产物在target/release/mdbook。

安装完先别急着写：这 4 个命令够你撑起一天的工作

装好只是起点。mdBook 的核心工作流就是"初始化 → 写作 → 构建/预览 → 测试"，下面这几个命令按使用频率排个序，你大概率都会用到：

• mdbook init [目录]：在当前目录或指定目录生成书籍骨架。第一次运行它会问你两个问题：书籍标题、要不要创建.gitignore。想跳过提问，可以加--force，或者直接用--title "我的书"预设标题。
• mdbook serve --open：本地预览，支持文件变动自动刷新，写文档时保持它开着就行。
• mdbook build：正式构建，把 Markdown 编译成静态 HTML 输出到book/目录。构建完成后可以整包扔到任意静态托管服务上。加--open参数会在构建完成后自动用浏览器打开。
• mdbook test：对书里的 Rust 代码片段做编译测试，保证文档里的示例代码不会过时，这一点对技术文档特别实用。

另外，.gitignore记得把book/目录忽略掉——它是构建产物，随时可以重新生成，不该进版本库。

排错问答：装不上的时候，多半是这几件事

Q：我执行mdbook显示"command not found"，是怎么回事？A：两种情况最常见。一是安装完没有重新打开终端，PATH还没刷新，退出重进或执行source ~/.bashrc试试。二是~/.cargo/bin不在你的PATH里，手动把它加进去即可。

Q：cargo install mdbook编译报错，跟 Rust 版本有关？A：很可能是你的工具链太旧。mdBook 要求 Rust 1.88 或更高，先执行rustc --version确认，然后运行rustup update stable升级到最新稳定版再重装。

Q：我明明装了最新版，为什么mdbook --version显示的版本号还是旧的？A：检查一下你的PATH里是否同时存在多个mdbook。用which mdbook看它实际指向哪里，很可能你系统里同时有源码构建版和 cargo 安装版，把旧的那个目录从PATH里挪走就行。

Q：cargo install下载太慢或者失败怎么办？A：大概率是网络问题。可以换用国内镜像源（修改 Cargo 的 config 配置），也可以退而求其次，直接下载预编译二进制，这条路完全不依赖网络编译。

Q：我不想每次都用--open，能直接设定默认行为吗？A：可以。书籍根目录下的book.toml是全局配置文件，serve和build的很多参数都能写进[build]或对应 renderer 的配置节里，不用每次都在命令行重复敲。

下一步，把这些事情挨个做一遍

安装只是开始，想让这本书真正用起来，按下面这份清单往下走，每一步都跟本文的内容直接相关：

1. 用mdbook init my-first-book建一个自己的书，把默认的chapter_1.md改成你的真实内容。
2. 打开src/SUMMARY.md看它的结构，把新的 Markdown 文件按格式加进去——这是 mdBook 生成左侧目录的依据。
3. 打开book.toml，把title改成你的书名，认识一下[book]、[build]、[output.html]这几段配置的作用。
4. 在写代码片段时用mdbook test跑一遍，体验一下文档即测试的流程。
5. 构建成功后，把book/目录部署到你的静态托管平台，用域名访问一下成品。

等你把这几步走完，mdBook 的核心用法就算真正上手了。再往后，你可以去探索mdbook serve的自动刷新、主题定制、多语言支持这些进阶能力——那些话题，我们留到下一篇再聊。

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