需要按背景系统学习 Rust 或构建/部署…

适用于从 C/C++、C#/Java、Python 等背景系统学习 Rust，并用 Microsoft RustTraining 的 7 本 mdBook 教材进行本地构建、预览和部署。

适用场景

解决思路

1. 按书单选择教材：`c-cpp-book`（C/C++ 桥接：move 语义、RAII、FFI、embedded、no_std）；`csharp-book`（C#/Java/Swift 桥接：ownership 与类型系统）；`python-book`（Python 桥接：动态到静态类型、无 GIL 并发）；`async-book`（深入：Tokio、streams、取消安全）；`rust-patterns-book`（高级：Pin、allocators、lock-free structures、unsafe）；`type-driven-correctness-book`（专家：type-state、phantom types、capability tokens）；`engineering-book`（实践：build scripts、cross-compilation、CI/CD、Miri）。
2. 按背景选择阅读路径：Python 背景走 `python-book` → `async-book` → `rust-patterns-book`；C/C++ 背景走 `c-cpp-book` → `rust-patterns-book` → `type-driven-correctness-book`；C#/Java 背景走 `csharp-book` → `async-book` → `engineering-book`；已会 Rust 基础走 `rust-patterns-book` → `type-driven-correctness-book` → `engineering-book`；生产 Rust 用 `engineering-book` + `async-book`（取消安全章节）。
3. 安装 Rust：运行 `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`。
4. 安装 mdBook 和 Mermaid 预处理器：运行 `cargo install mdbook mdbook-mermaid`。
5. 克隆并进入仓库：运行 `git clone https://github.com/microsoft/RustTraining.git`，然后 `cd RustTraining`。
6. 构建所有书到 `site/`：运行 `cargo xtask build`。
7. 本地服务所有书：运行 `cargo xtask serve`，访问 `http://localhost:3000`。
8. 生成 GitHub Pages 部署输出到 `docs/`：运行 `cargo xtask deploy`。
9. 清理构建产物：运行 `cargo xtask clean`。
10. 单独服务某本书：运行 `cd c-cpp-book && mdbook serve --open`、`cd python-book && mdbook serve --open`、`cd async-book && mdbook serve --open`。
11. 按仓库结构定位内容：各书目录含 `book.toml` 和 `src/`（`SUMMARY.md` 与章节 md）；`xtask/src/main.rs` 是构建自动化；`docs/` 是 GitHub Pages 输出；`site/` 是本地预览输出；`.github/workflows/pages.yml` 负责 push 到 master 自动部署。
12. 每本书的 `book.toml` 配置模式：`[book]` 设置 title/authors/language/src；`[build] build-dir = '../site/<book-name>'`；`[preprocessor.mermaid] command = "mdbook-mermaid"`；`[output.html]` 设置 default-theme/preferred-dark-theme/git-repository-url/edit-url-template；`[output.html.search] enable = true`。
13. 在 `c-cpp-book` 中复现 ownership/move 示例：默认 move；函数取得 String 所有权后调用方不可再用；需要深拷贝时显式 `.clone()`。
14. 在 `c-cpp-book` 中复现 RAII 示例：用 `File::create` 和 `write_all`，文件在作用域结束时自动关闭，无需手动 close。
15. 在 `c-cpp-book` 中复现 FFI 示例：用 `extern "C" { fn abs(x: i32) -> i32; }`，在 `unsafe` 块中调用 C 函数。
16. 在 `python-book` 中复现静态类型与类型推断：用 `Vec::new()` 后 `push(1_i32)` 让 Rust 推断；必要时显式 `let numbers: Vec<i32> = vec![1, 2, 3];`。
17. 在 `python-book` 中复现错误处理：用 `Result<i32, ParseIntError>`，用 `?` 传播错误，在 `main` 中 `match` 处理 `Ok`/`Err`。
18. 在 `python-book` 中复现无 GIL 并发：用 `thread::spawn`、`Arc<Mutex<i32>>`、`lock().unwrap()`、`join()` 实现多线程计数器。
19. 在 `async-book` 中复现基础 async：用 `#[tokio::main]`、`tokio::time::sleep` 和 `.await`。
20. 在 `async-book` 中复现并发任务：用 `tokio::join!` 配合 `task::spawn` 并发执行多个 async 计算。
21. 在 `async-book` 中复现取消安全 stream：用 `tokio_stream::iter` 和 `StreamExt::next().await` 遍历。
22. 在 `rust-patterns-book` 中复现类型安全 builder：为 `ConfigBuilder` 实现 `new` 和返回 `Self` 的链式 setter，最后 `build()` 得到 `Config`。
23. 在 `rust-patterns-book` 中复现自定义 allocator：实现 `GlobalAlloc` 的 `alloc`/`dealloc`，用 `AtomicUsize` 跟踪分配字节数，并用 `#[global_allocator]` 注册。
24. 在 `type-driven-correctness-book` 中复现 typestate：用 `Locked`/`Unlocked` 状态类型和 `PhantomData`，只在 `Safe<Unlocked>` 上提供 `get_contents`，通过 `unlock`/`lock` 转移状态。
25. 在 `type-driven-correctness-book` 中复现 Phantom Types 单位安全：定义 `Meters`/`Feet` 和 `Distance<Unit>`，只给 `Distance<Meters>` 实现 `to_feet`，防止单位混用。
26. 在 `engineering-book` 中复现 build script：在 `build.rs` 中用 `cargo:rerun-if-changed`、`cc::Build::new().file(...).compile(...)`、`cargo:rustc-link-search`、`cargo:rustc-link-lib`。
27. 在 `engineering-book` 中执行交叉编译：运行 `rustup target add aarch64-unknown-linux-gnu`；运行 `cargo build --target aarch64-unknown-linux-gnu`；在 `.cargo/config.toml` 的 `[target.aarch64-unknown-linux-gnu]` 设置 `linker = "aarch64-linux-gnu-gcc"`。
28. 在 `engineering-book` 中运行 Miri 检测未定义行为：运行 `rustup component add miri`；运行 `cargo miri test`；运行 `cargo miri run`。
29. 在书中新增章节：编辑对应书的 `src/SUMMARY.md`，按层级添加 Markdown 链接（如 Introduction、Chapter 1、Borrowing、Lifetimes、Chapter 2）。
30. 在章节中插入 Mermaid 图：使用 `mermaid` 代码块，例如 `graph TD` 描述所有权转移/借用流程。
31. 在章节中插入 Rust Playground 链接：使用 `https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&code=...` 格式。
32. 用 xtask 模式写构建脚本：在 `xtask/src/main.rs` 中读取 `std::env::args().nth(1)`，按 `build`/`serve`/`deploy`/`clean` 分支调用 `Command::new("mdbook").args([...]).status()`；在 `.cargo/config.toml` 配置别名后运行 `cargo xtask build`。
33. 配置 GitHub Pages 自动部署：在 `.github/workflows/pages.yml` 中监听 push 到 `master`；步骤包括 `actions/checkout@v4`、`dtolnay/rust-toolchain@stable`、`cargo install mdbook mdbook-mermaid`、`cargo xtask deploy`、`peaceiris/actions-gh-pages@v3`，`publish_dir: ./docs`。
34. `mdbook` 命令找不到：运行 `cargo install mdbook mdbook-mermaid`；确保 `~/.cargo/bin` 在 `PATH`，必要时运行 `export PATH="$HOME/.cargo/bin:$PATH"`。
35. Mermaid 图不渲染：运行 `cargo install mdbook-mermaid`；确认 `book.toml` 有 `[preprocessor.mermaid]` 且 `command = "mdbook-mermaid"`。
36. 端口被占用：用 `mdbook serve --port 3001`。
37. 某本书构建失败：运行 `cd <book-name>`；运行 `mdbook build 2>&1` 查看完整错误。
38. Miri 测试失败：运行 `rustup update nightly`；运行 `rustup component add miri --toolchain nightly`；运行 `cargo +nightly miri test`。
39. 交叉编译 linker 错误：安装 `cross`：运行 `cargo install cross`；用 `cross build --target aarch64-unknown-linux-gnu`。

适用边界 · 注意事项

• 只想零散查询 Rust 语法，不需要按 7 本书的课程/练习体系系统学习时，不适用。
• 环境无法安装 Rust/cargo、mdBook/mdbook-mermaid 或无法访问 GitHub 时，不适用。
• 不想使用 Microsoft RustTraining 仓库或 mdBook 工作流，而使用其他教材/构建系统时，不适用。