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.88mdBook 的 Cargo.toml 里明确标注了rust-version 1.88.0。如果还没装先去 Rust 官网用官方脚本装好rustup这一步同样很快。打开终端执行cargo install mdbookCargo 会从 crates.io 拉取 mdBook 的源码、完成编译然后把可执行文件放进 Cargo 的全局二进制目录默认是~/.cargo/bin/。安装完成后先验证一下mdbook --version如果屏幕上出现了类似mdbook v0.5.4的版本号恭喜你安装成功。接下来立刻体验3 分钟造一本书的快乐。随便找个空目录执行mdbook init my-first-book cd my-first-book mdbook serve --openserve会在本地启动一个预览服务器--open参数会自动帮你打开浏览器。你会看到 mdBook 自动生成的默认页面——左侧是章节目录右侧是正文右上角还有搜索框。现在打开src/chapter_1.md随便改几个字保存浏览器里的页面会实时刷新。整个过程不需要写一行 HTML、不需要配置任何依赖这就是 mdBook 最打动人的地方。三条安装路线怎么选一张表看明白前面那条命令只是其中一种安装方式。mdBook 总共提供了三条安装路线分别对应三类不同的使用场景。你可以先看下面这张对比表再决定哪条路适合你。安装方式适用人群优点代价核心命令预编译二进制不想装 Rust 工具链的新手、只要稳定版的人无需编译环境解压即用1 分钟装完更新要重新下载版本比源码仓库略旧下载压缩包后放入 PATHcargo install已经装了 Rust 的开发者一条命令装好升级卸载都简单首次编译要等几分钟cargo install mdbook从 Git 源码构建想尝鲜最新开发版、要改源码的人永远拿到最新功能可能有未稳定功能、存在 bug、编译更慢cargo install --git https://github.com/rust-lang/mdBook.git mdbook路线一下载预编译二进制适合我不想装 Rust去项目的发布页面找到对应你系统平台的压缩包Windows 选.zipmacOS 和 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里手动把它加进去即可。Qcargo install mdbook编译报错跟 Rust 版本有关A很可能是你的工具链太旧。mdBook 要求 Rust 1.88 或更高先执行rustc --version确认然后运行rustup update stable升级到最新稳定版再重装。Q我明明装了最新版为什么mdbook --version显示的版本号还是旧的A检查一下你的PATH里是否同时存在多个mdbook。用which mdbook看它实际指向哪里很可能你系统里同时有源码构建版和 cargo 安装版把旧的那个目录从PATH里挪走就行。Qcargo install下载太慢或者失败怎么办A大概率是网络问题。可以换用国内镜像源修改 Cargo 的 config 配置也可以退而求其次直接下载预编译二进制这条路完全不依赖网络编译。Q我不想每次都用--open能直接设定默认行为吗A可以。书籍根目录下的book.toml是全局配置文件serve和build的很多参数都能写进[build]或对应 renderer 的配置节里不用每次都在命令行重复敲。下一步把这些事情挨个做一遍安装只是开始想让这本书真正用起来按下面这份清单往下走每一步都跟本文的内容直接相关用mdbook init my-first-book建一个自己的书把默认的chapter_1.md改成你的真实内容。打开src/SUMMARY.md看它的结构把新的 Markdown 文件按格式加进去——这是 mdBook 生成左侧目录的依据。打开book.toml把title改成你的书名认识一下[book]、[build]、[output.html]这几段配置的作用。在写代码片段时用mdbook test跑一遍体验一下文档即测试的流程。构建成功后把book/目录部署到你的静态托管平台用域名访问一下成品。等你把这几步走完mdBook 的核心用法就算真正上手了。再往后你可以去探索mdbook serve的自动刷新、主题定制、多语言支持这些进阶能力——那些话题我们留到下一篇再聊。【免费下载链接】mdBookCreate book from markdown files. Like Gitbook but implemented in Rust项目地址: https://gitcode.com/gh_mirrors/md/mdBook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考