LetRecovery 开发指南：从零构建、测试到向这个 Rust 项目提交首个 PR 的完整流程
【免费下载链接】LetRecovery一款免费开源的 Windows 系统重装工具项目地址: https://gitcode.com/gh_mirrors/le/LetRecovery
LetRecovery 是一款免费开源的 Windows 系统重装工具，用 Rust 编写。本文将带你从零完成这个 Rust 项目的构建与测试，并顺利提交你的第一个 PR。无论你是第一次接触 Rust 工作区，还是想为磁盘工具类项目贡献代码，这份开发指南都能帮你快速上手。
1️⃣ 先看懂 LetRecovery 的项目结构
LetRecovery 是一个 Cargo 工作区（workspace），包含三个成员 crate，理解它们的分工是贡献代码的第一步：
| 目录 | 作用 | 入口文件 |
|---|---|---|
lr-core/ | 两端共享的纯逻辑、Windows API 适配层（禁止反向依赖两端） | lr-core/src/lib.rs |
正常系统端/ | Windows 7–11 桌面版主程序：系统安装、备份、下载、工具箱 | 正常系统端/src/main.rs |
PE端/ | WinPE 环境中的安装、备份与扩容程序 | PE端/src/main.rs |
依赖方向必须保持为：两端 → lr-core，lr-core 绝不依赖任一端。当你发现两端出现相同逻辑时，正确的做法是把纯逻辑下沉到 lr-core/src/。
工作区根配置在 Cargo.toml，锁定了 Rust 1.88 与 PolyForm Noncommercial 许可；发布用的opt-level = "z"、lto = true等优化配置也在这里统一声明。
💡 每个文件的详细职责说明都在 AGENTS.md 的“Rust 文件职责目录”中，贡献前务必通读，它是本项目最重要的开发契约。
2️⃣ 快速配置 Rust 开发环境
按照 CONTRIBUTING.md 的要求，环境准备很简单：
- Rust 1.88+（CI 固定使用 1.88.0，并需要
rust-src组件） - Visual Studio Build Tools 2022，勾选“使用 C++ 的桌面开发”与 Windows 10/11 SDK（链接 Win32 程序必需）
- Git，并从仓库根目录拉取代码：
git clone https://gitcode.com/gh_mirrors/le/LetRecovery cd LetRecovery⚠️ 注意：仓库已提交Cargo.lock，没有真实依赖变化时不要重建 lockfile。CI 会设置SOURCE_DATE_EPOCH以保证构建可复现，本地复现发布二进制时应设置相同值。
3️⃣ 从零构建：本地编译这个 Rust 项目
先做只读检查（推荐日常使用）
提交代码前，从仓库根目录依次运行以下命令，它们与 CI 完全一致：
cargo fmt --all --check cargo check --workspace --all-targets --locked cargo clippy --workspace --all-targets --locked \ --features "LetRecovery/non-elevated-tests,letrecovery-pe/non-elevated-tests" \ -- -D warnings -A clippy::uninlined_format_args正式构建两端的 EXE
正常系统端必须面向x86_64-win7-windows-msvc目标重编译标准库，以兼容未安装 UCRT 平台更新的 Windows 7：
# 正常系统端（统一走共享构建脚本，不要直接用 cargo build） powershell -ExecutionPolicy Bypass -File .github/scripts/build-win7-normal.ps1 # PE 端（仅运行在现代 WinPE，用普通 MSVC 目标单独构建） cargo +1.88.0 build -p letrecovery-pe --release --locked --target x86_64-pc-windows-msvc⚠️常见坑：不要用
cargo build --workspace --release生成要在 Windows 7 上运行的正常端程序，否则可能静态导入 Windows 8+ 的 API。构建脚本会自动运行verify-win7-imports.ps1检查导入表，发现问题将阻断打包。
4️⃣ 运行测试：non-elevated-tests 是关键开关
cargo test -p lr-core --locked cargo test -p letrecovery-pe --locked --features non-elevated-tests cargo test -p LetRecovery --locked --features non-elevated-testsnon-elevated-testsfeature 会把测试程序清单从requireAdministrator改为asInvoker，让 CI 和你在本地跑测试时不需要 UAC 提权；release 构建会拒绝该 feature。
🚫 本项目最重要的测试红线
LetRecovery 是一个高权限磁盘工具，CONTRIBUTING.md 明确规定：
- 自动化测试与 CI严禁执行真实的
format、DiskPart、DISM 写盘、BCD 修改、分区变更、重启或镜像还原； - 危险命令路径必须用纯函数、mock、临时文件或
DryRunCommandExecutor测试，参考 lr-core/src/command.rs 的类型化执行器设计； - 需要读取真实 Windows 状态的测试必须标记
#[ignore]，只允许在可丢弃虚拟机中手动运行。
5️⃣ 提交首个 PR：改动纪律与检查清单
选一个合适的切入点
- 新增用户可见中文字符串：记得同步英文翻译到 assets/release/lang/en-US.json；
- 新增 Rust 文件：接入对应
mod.rs，添加针对性测试，并更新 AGENTS.md 职责目录（文档同步是“完成定义”的一部分）； - 第三方二进制变化：必须同步更新 docs/THIRD_PARTY_BINARIES.md 及许可证；
- 行为兼容的改动保持小而可评审，不要顺手重写无关界面或工作流。
提交前检查清单 ✅
cargo fmt --all --check、cargo check --workspace --all-targets --locked全部通过git diff --check无空白错误git status --short确认没有误提交pkg/、日志、构建产物或用户文件- 如实记录未运行的测试——“无法执行”不能写成“测试通过”
- 提交信息准确描述本次修改，只包含本次任务范围的文件
6️⃣ 常见问题速答（FAQ）
Q：我改了一行代码，为什么 clippy 报错？A：本项目用-D warnings阻断所有 Clippy 警告（仅放行uninlined_format_args这一项跨工具链表现不一致的纯样式 lint），按提示修复即可。
Q：能在自己电脑上直接跑安装流程测试吗？A：不可以。真实写盘流程只能在可丢弃虚拟机、可丢弃 VHDX 和专用测试盘上人工验证，这也是项目防止误操作的核心保障。
Q：CI 都会做什么？A：PR 与 main 分支流水线会编译全部测试目标并运行确定性单元测试，见 .github/workflows/pr-build.yml；发布流水线见 .github/workflows/build-and-release.yml。CI 从不执行真实格式化、分区或引导修改。
总结
本文完整走通了 LetRecovery 开发指南的全部核心环节：看懂lr-core+ 正常系统端 + PE 端的三 crate 结构，用 Rust 1.88 从零构建这个 Windows 系统重装工具，用non-elevated-tests安全地运行测试，最后按改动纪律提交你的第一个 PR。记住三句话：先读 AGENTS.md、危险路径永不真实执行、文档与代码同步更新——做到这三点，你的贡献就能顺利合入。🚀
【免费下载链接】LetRecovery一款免费开源的 Windows 系统重装工具项目地址: https://gitcode.com/gh_mirrors/le/LetRecovery
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
