Rust 语言入门：从环境搭建到发布第一个 CLI 工具

安装完成后，验证安装：
打开 PowerShell 或命令提示符，输入以下命令：

rustc --version
cargo --version

✅ 成功标志：显示 rustc 1.78.0 (9b00956e5 2024-04-29) 和 cargo 1.78.0 (54d8815d0 2023-03-26) 类似的版本信息

2.1.2 macOS 安装

1. 打开终端（Terminal）
2. 输入以下命令下载并运行 rustup 安装脚本：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. 按 1 键选择默认选项

验证安装：

rustc --version
cargo --version

2.1.3 Linux 安装（以 Ubuntu/Debian 为例）

1. 打开终端
2. 更新系统软件源并安装依赖：

sudo apt update && sudo apt install -y build-essential curl git

3. 下载并运行 rustup 安装脚本：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

验证安装：

rustc --version
cargo --version

2.2 配置国内镜像源——加速依赖下载

⚠️ 警告：由于网络原因，直接从 crates.io 下载依赖可能会非常慢，甚至失败。建议配置国内镜像源。

1. 创建或编辑 ~/.cargo/config.toml 文件（Windows 用户路径是 C:\Users\你的用户名\.cargo\config.toml）
2. 保存并退出

输入以下内容：

[source.crates-io]
replace-with = 'ustc'
[source.ustc]
registry = "git://mirrors.ustc.edu.cn/crates.io-index"
# 如果 git 协议访问慢，可以尝试 https 协议
# registry = "https://mirrors.ustc.edu.cn/crates.io-index"

2.3 配置开发工具

推荐使用VS Code作为 Rust 开发 IDE，因为它有非常强大的 Rust 插件支持。

2.3.1 安装 VS Code

访问 VS Code 官方网站：https://code.visualstudio.com/，下载并安装对应系统的版本。

2.3.2 安装 Rust 相关插件

打开 VS Code，点击左侧的插件图标（Extensions），搜索并安装以下插件：

1. Rust Analyzer：由 Rust 官方团队主导开发，提供代码补全、语法检查、定义跳转、重构等核心功能
2. CodeLLDB：用于 Rust 程序的调试
3. Cargo：Cargo 命令的集成支持
4. Even Better TOML：用于格式化 Cargo.toml 等 TOML 配置文件

三、第一个 Rust 项目：从 Hello, World!到可发布的 CLI 工具

3.1 使用 Cargo 创建标准项目

⌨️ 操作步骤：

1. 打开终端（或 VS Code 的终端）
2. 进入你想存放项目的目录，比如 ~/projects
3. 进入项目目录：

cd hello_rust_cli

4. 输入以下命令创建项目：

cargo new hello_rust_cli

3.2 项目目录结构解析

📊 项目目录结构：

hello_rust_cli/
├── Cargo.lock # 项目依赖的精确版本锁定文件（自动生成，不要手动修改）
├── Cargo.toml # 项目配置文件（手动编辑）
└── src/
    └── main.rs # 主源码文件（入口函数所在位置）

3.2.1 Cargo.toml 内容解析

[package]
name = "hello_rust_cli" # 项目名称（必须符合 Rust 的命名规范：小写字母 + 下划线）
version = "0.1.0" # 项目版本（遵循语义化版本控制：MAJOR.MINOR.PATCH）
edition = "2021" # Rust 的版本（目前最新稳定版是 2021）
[dependencies] # 项目依赖的库（可以手动添加，也可以用 cargo add 命令）

3.2.2 src/main.rs 内容解析

// src/main.rs - Hello, Rust! 的标准写法
fn main() {
    println!("Hello, Rust World!");
}

• fn main()：Rust 程序的入口函数，Rust 会自动执行这个函数
• println!()：Rust 的宏（不是函数，注意后面的感叹号），用于向控制台输出内容

3.3 编译、运行、测试项目

3.3.1 编译项目

cargo build # 编译为 debug 版本（默认，用于开发和调试）
cargo build --release # 编译为 release 版本（优化后的，用于生产环境）

✅ 成功标志：编译完成后，会在 target/debug/ 或 target/release/ 目录下生成可执行文件。

3.3.2 运行项目

cargo run # 同时完成编译和运行 debug 版本
cargo run --release # 同时完成编译和运行 release 版本

✅ 成功标志：输出 Hello, Rust World!。

3.3.3 测试项目

Rust 的测试功能非常强大，我们可以在 src/main.rs 中添加测试代码，也可以创建专门的测试文件。
⌨️ 测试代码示例：
在 src/main.rs 的末尾添加以下代码：

#[cfg(test)]
mod tests {
    #[test]
    fn test_hello_world() {
        assert_eq!(1 + 1, 2); // 简单的测试断言
    }
}

运行测试：

cargo test # 运行所有测试

✅ 成功标志：显示 test tests::test_hello_world ... ok。

3.4 扩展项目：添加命令行参数支持

现在，我们要将 Hello, Rust! 扩展为一个支持命令行参数的 CLI 工具，比如：

cargo run -- --name "张三"

输出：Hello, 张三!

⌨️ 操作步骤：

修改 src/main.rs：

use clap::Parser;

/// 一个简单的 Hello, Rust! CLI 工具
#[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)]
struct Args {
    /// 你的名字
    #[arg(short, long)]
    name: String,
}

fn main() {
    let args = Args::parse();
    println!("Hello, {}!", args.name);
}

添加依赖：我们需要使用 clap 库来处理命令行参数

cargo add clap --features derive

运行扩展后的项目：

cargo run -- --name "张三"

✅ 成功标志：输出 Hello, 张三!。

3.5 调试项目

我们可以使用 VS Code 的 CodeLLDB 插件来调试 Rust 程序。
⌨️ 操作步骤：

1. 在 VS Code 中打开项目
2. 在 src/main.rs 的 println!() 一行设置断点（点击行号左侧的空白处）
3. 点击左侧的运行图标（Run and Debug）
4. 点击'创建 launch.json 文件'，选择'LLDB: Launch'
5. 点击'运行'按钮
6. 程序会在断点处停止，我们可以查看变量值、调用栈等信息

修改 launch.json 文件：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "(lldb) Launch",
      "type": "lldb",
      "request": "launch",
      "program": "${workspaceFolder}/target/debug/hello_rust_cli",
      "args": ["--name", "张三"],
      "cwd": "${workspaceFolder}",
      "preLaunchTask": "cargo build"
    }
  ]
}

3.6 发布项目

我们可以使用 Cargo 将项目发布到 crates.io 上，供其他开发者使用。
⚠️ 注意：发布项目之前，你需要先在 crates.io 上注册账号，并配置 API 密钥。
⌨️ 操作步骤：

1. 在 crates.io 上注册账号：https://crates.io/users/sign_up

发布项目：

cargo publish

✅ 成功标志：显示 Updating crates.io index 和 Published hello_rust_cli v0.1.0。

创建 README.md 文件：

# hello_rust_cli

一个简单的 Hello, Rust! CLI 工具。

## 安装

```bash
cargo install hello_rust_cli

使用

hello_rust_cli --name "张三"

输出：Hello, 张三!

许可证

MIT

修改 Cargo.toml 文件：  
添加作者、描述、仓库地址等信息：

```toml
[package]
name = "hello_rust_cli"
version = "0.1.0"
edition = "2021"
authors = ["你的名字 <你的邮箱>"]
description = "一个简单的 Hello, Rust! CLI 工具"
repository = "https://github.com/你的用户名/hello_rust_cli"
readme = "README.md"
license = "MIT"
[dependencies]
clap = { version = "4.5.4", features = ["derive"] }

配置 API 密钥：
在终端中输入以下命令：

cargo login

然后输入你在 crates.io 上获得的 API 密钥。

四、Rust 新手常见陷阱与避坑指南

4.1 混淆变量的可变性与不可变性

⚠️ 陷阱：在 Rust 中，变量默认是不可变的（immutable），如果你尝试修改一个不可变变量，会导致编译错误。
⌨️ 错误示例：

fn main() {
    let x = 5;
    x = 6; // 编译错误：x is declared as immutable
}

✅ 避坑方法：如果你需要修改一个变量，必须在声明时添加 mut 关键字：

fn main() {
    let mut x = 5;
    x = 6;
    println!("x = {}", x); // 输出 x = 6
}

4.2 忘记处理 Result 类型

⚠️ 陷阱：Rust 中的很多函数会返回 Result 类型，它表示操作成功或失败。如果你忘记处理 Result 类型，会导致编译错误。
⌨️ 错误示例：

use std::fs::File;
fn main() {
    let file = File::open("test.txt"); // 返回 Result<File, io::Error>
}

✅ 避坑方法：有三种方法处理 Result 类型：

使用 ? 运算符：

use std::fs::File;
use std::io;
fn read_file() -> io::Result<()> {
    let _file = File::open("test.txt")?;
    Ok(())
}
fn main() {
    if let Err(e) = read_file() {
        println!("文件操作失败：{}", e);
    }
}

使用 if let 表达式：

use std::fs::File;
fn main() {
    if let Ok(f) = File::open("test.txt") {
        println!("文件打开成功");
    } else {
        println!("文件打开失败");
    }
}

使用 match 表达式：

use std::fs::File;
use std::io::ErrorKind;
fn main() {
    let file = File::open("test.txt");
    match file {
        Ok(f) => println!("文件打开成功"),
        Err(e) => match e.kind() {
            ErrorKind::NotFound => println!("文件不存在"),
            _ => println!("文件打开失败：{}", e),
        },
    }
}

4.3 混淆引用与所有权

⚠️ 陷阱：Rust 的所有权系统是它最核心的内存安全机制，也是最容易让新手困惑的地方。简单来说，每个值都有且仅有一个所有者，当所有者离开作用域时，值会被自动释放。
⌨️ 错误示例：

fn main() {
    let s = String::from("hello");
    takes_ownership(s); // s 的所有权转移到 takes_ownership 函数
    println!("{}", s); // 编译错误：s 已经没有所有权了
}
fn takes_ownership(s: String) {
    println!("{}", s);
}

✅ 避坑方法：如果我们不想转移所有权，可以使用引用（reference）：

fn main() {
    let s = String::from("hello");
    borrows_ownership(&s); // 传递 s 的引用
    println!("{}", s); // 编译成功：s 的所有权还在
}
fn borrows_ownership(s: &String) {
    println!("{}", s);
}

4.4 忘记处理生命周期

⚠️ 陷阱：Rust 的生命周期系统用于确保引用的有效性，防止出现悬垂引用。如果我们忘记处理生命周期，会导致编译错误。
⌨️ 错误示例：

fn main() {
    let r;
    {
        let x = 5;
        r = &x; // 编译错误：x 的生命周期比 r 短
    }
    println!("{}", r);
}

✅ 避坑方法：确保引用的生命周期不超过所有者的生命周期：

fn main() {
    let x = 5;
    let r = &x;
    println!("{}", r);
}

五、总结与展望

5.1 总结

✅ 完成了 Rust 开发环境的完整搭建（Windows/macOS/Linux），配置了国内镜像源加速依赖下载
✅ 理解了 Cargo 作为 Rust 标准构建系统和包管理器的核心功能
✅ 成功创建了第一个 Rust 项目 Hello, Rust!，并将其扩展为支持命令行参数的 CLI 工具
✅ 掌握了 Rust 程序的编译、运行、测试、调试、发布流程
✅ 了解了 Rust 新手常见的陷阱与避坑方法

5.2 展望

下一篇文章，我们将深入学习 Rust 的基本数据类型和变量系统，包括：

• 标量类型（整数、浮点数、布尔值、字符）
• 复合类型（元组、数组、切片）
• 字符串类型（String 和&str）
• 变量的作用域和 shadowing（变量隐藏）
• 类型转换

通过学习这些内容，我们将能够编写更复杂的 Rust 程序。