1. 项目背景
cargo-generate 是一个专为 Rust 开发者设计的工具，由 cargo-generate 团队开发并维护，托管在 GitHub 上（cargo-generate/cargo-generate）。它的核心目标是帮助开发者快速创建新的 Rust 项目，通过利用现有的 Git 仓库作为模板，省去手动配置项目结构的繁琐步骤。
在 Rust 生态中，Cargo 是官方的构建工具和包管理器，而 cargo-generate 作为其扩展，进一步提升了开发效率。它特别适合需要快速原型设计、遵循特定项目结构，或复用已有模板的场景。自推出以来，cargo-generate 得到了社区的广泛支持和贡献，已成为许多 Rust 开发者的常用工具。
2. 核心功能
cargo-generate 的主要功能是通过模板生成 Rust 项目，以下是其核心特性：
- 模板支持：从 Git 仓库（支持 GitHub、GitLab、BitBucket 等平台）拉取模板，生成项目结构。
- 占位符替换：支持动态替换模板中的占位符（如项目名称、作者信息等），使用 Liquid 模板语言。
- 灵活性：允许指定模板的子目录、自定义项目名称，甚至支持私有仓库（通过 SSH）。
- 忽略文件：通过
.genignore 文件排除不需要的文件，类似于 .gitignore。
- 交互式 CLI：提供交互式命令行界面，方便用户输入项目参数。
这些功能让 cargo-generate 不仅适用于个人开发者，也适合团队协作或标准化项目创建流程。
3. 安装方法
要使用 cargo-generate，需要先安装它。确保你已安装 Rust 和 Cargo，然后运行以下命令：
cargo install cargo-generate
安装完成后，可以通过以下命令验证是否成功：
cargo generate --help
如果输出版本信息和帮助文档，说明安装无误。
4. 基本使用方法
cargo-generate 的基本用法是通过指定一个 Git 模板来生成项目。以下是几个常见示例：
4.1 从 GitHub 模板生成项目
假设你想使用一个 GitHub 上的模板（例如 https://github.com/username/mytemplate.git），可以运行：
cargo generate --git https://github.com/username/mytemplate.git
执行后，工具会：
- 克隆模板到本地。
- 提示你输入项目名称（如果未指定）。
- 根据模板生成项目文件，并替换占位符。
4.2 指定项目名称
如果你想直接指定项目名称，避免交互式输入，可以使用 --name 或 -n 参数：
cargo generate --git https://github.com/username/mytemplate.git --name myproject
这会生成一个名为 myproject 的项目。
4.3 使用简写形式
对于 GitHub 模板，cargo-generate 支持简写形式：
cargo generate username/mytemplate
这等价于 --git https://github.com/username/mytemplate.git。
4.4 指定模板子目录
如果模板仓库包含多个子模板，可以指定具体路径：
cargo generate --git https://github.com/username/mytemplate.git subfolder
这会使用 subfolder 下的模板作为生成依据。
4.5 支持其他 Git 平台
除了 GitHub，cargo-generate 还支持其他平台，使用前缀简写：
- GitLab：
gl:username/mytemplate
- BitBucket：
bb:username/mytemplate
- SourceHut：
sr:username/mytemplate
例如：
cargo generate gl:username/mytemplate
5. 模板中的占位符
cargo-generate 使用 Liquid 模板语言处理占位符。以下是常用占位符及其含义：
{{project-name}}：项目名称，由 --name 或交互输入提供。{{crate_name}}：项目名称的 snake_case 版本（如 my-project 变为 my_project）。{{authors}}：作者信息，从 Cargo 配置中自动获取（通常是用户名和邮箱）。
模板作者可以在文件内容或文件名中使用这些占位符。例如，模板中的 {{project-name}}.rs 文件在生成时会根据项目名称重命名。
6. 高级用法
6.1 使用私有仓库
对于私有 Git 仓库，可以通过 SSH 访问：
cargo generate --git git@github.com:username/mytemplate.git
确保你的 SSH 密钥已正确配置。
6.2 自定义忽略文件
模板中可以包含 .genignore 文件，列出生成时需要排除的文件。例如：
*.md
.git
这会跳过 Markdown 文件和 .git 目录。
6.3 强制使用原始名称
默认情况下，cargo-generate 会将项目名称转换为符合 Rust 规范的形式（如转换为 kebab-case）。如果想保留原始输入，使用 --force：
cargo generate --git https://github.com/username/mytemplate.git --name MyProject --force
7. 实用建议
- 寻找模板：可以在 GitHub 上搜索带有
cargo-generate 标签的仓库，找到适合的模板。
- 调试模板：如果生成结果不符合预期，检查模板中的
.genignore 和占位符使用是否正确。
- 版本管理：定期更新
cargo-generate（cargo install --force cargo-generate），以获取最新功能和修复。
- 社区贡献：如果你有好的模板，可以分享到社区，或为
cargo-generate 项目提交 PR。
8. 示例项目
假设你想快速创建一个 WebAssembly 项目，可以使用 rustwasm/wasm-pack-template 模板：
cargo generate --git https://github.com/rustwasm/wasm-pack-template.git --name mywasm
生成后，进入 mywasm 目录，运行 cargo build 检查项目是否正常。
9. 总结
cargo-generate 是一个强大而灵活的工具，通过模板化方式简化了 Rust 项目创建过程。无论是快速原型设计还是标准化团队开发，它都能显著提升效率。希望这份文档能帮助你快速上手，并在实际项目中发挥作用！
