Ubuntu上Rust开发环境搭建：从rustup安装到关键配置与踩坑

刚接触 Linux 下的 Rust 开发时，我第一反应也是“Rust 都进 Ubuntu 官方仓库了，直接 apt install rustc 不就行了”。这是个很容易踩进去的误判。Ubuntu 仓库里确实有 Rust 工具链，但版本通常比 Rust 官方发布的版本落后不少，日常写个小工具看不出差别，一旦碰上要使用较新语法、需要 nightly 特性、或者某个项目要求最低 Rust 版本的场景，旧版本立刻变成一块挡路的石头。这篇内容主要写给两类人：一类是刚在 Ubuntu 上开始接触 Rust 的新手，另一类是从其他系统切到 Ubuntu、但一直没搞清 rustup、cargo、rustc 之间关系的开发者。我会把完整的安装链路、每一步背后的原理、以及装完之后常见的坑一起讲清楚，尽量让你装完之后不只是“能用”，而是“知道自己装了什么、出了问题能自己排查”。

1. 为什么官方推荐的安装方式是 rustup，而不是 apt install rustc

1.1 Ubuntu 仓库里的 Rust 版本为什么不够用

Ubuntu 的软件仓库一直在做一件事：把上游软件稳定版本打包装进自己的发布渠道。这件事在服务器、桌面系统层面是好事，但在 Rust 这种更新节奏特别快的语言生态里，就变成了一个明显的痛点。Rust 官方大约每六周发布一个新版本，而一个已经发布的长期支持版 Ubuntu，仓库里的 Rust 版本基本就冻结在那个时间点了。你当然可以通过 PPA 或者其他渠道去追新，但那等于放弃仓库的维护体系，还不如直接使用官方工具链。

版本落后最直接的影响是编译失败。举个例子，很多现代 crate 会在 Cargo.toml 里声明rust-version字段，也就是最低支持的 Rust 版本（MSRV）。如果你的 rustc 低于这个版本，cargo 会直接拒绝编译，而不是给你一个可读的警告。我遇到过不止一次，有人在 Ubuntu 自带 Rust 版本上跑某个新项目，一编译就报“current package believes it's in a work-in-progress state”或者一堆莫名其妙的 trait 错误，查到最后发现是编译器版本太老。这种问题排查起来非常浪费时间，而且它本质上不是你项目代码的问题。

1.2 rustup 解决了什么：工具链版本与组件的统一管理

rustup 是 Rust 官方维护的工具链版本管理器。它解决的核心问题是：你的系统里同时存在多套 Rust 工具链时，该怎么选、怎么切换、怎么补装组件。

在 rustup 出现之前，你基本上只能在一台机器上装一个 Rust 版本。想试试 nightly，又不想破坏正在用的 stable，只能折腾环境变量或虚拟机。rustup 把这件事变成了一个非常简单的事情：它把所有工具链都放在统一目录里，然后通过rustup default、rustup override、cargo +toolchain这类命令，按全局或者按项目切换当前生效的编译器版本。rustc、cargo、rustfmt、clippy、rust-analyzer 这些组件，也都可以通过rustup component add按需安装，不需要再单独去网上下载。

所以，虽然apt install rustc也能装出一个可用的编译器，但它只是把 rustc 这个单体二进制放到了 /usr/bin 下面。你没有版本管理的概念，没有组件的概念，也没有升级和回滚的统一入口。尤其当你需要 nightly 做嵌入式、跨平台编译或者某些实验特性时，apt 那条路线基本就走不通了。

1.3 两种安装方式的对比

一句话：如果你只是偶尔用 rustc 编译一下单一文件，apt 并不是不能用；但如果你想正儿八经用 Rust 做项目开发，我强烈建议直接用 rustup。本文后面所有内容都基于 rustup 安装。

2. 动手之前先把系统状态摸清楚

2.1 确认系统版本和 CPU 架构

我见过不少人安装失败，客户端提示“unsupported architecture”或者“can't find shell”，其实问题在安装之前就存在了。运行下面两条命令，先确认你的系统基本盘：

cat /etc/os-release uname -m

第一条可以看到 Ubuntu 版本号、发布代号，第二条是 CPU 架构。绝大多数情况下你会看到x86_64，如果你用的是树莓派或者其他 ARM 开发板，会看到aarch64。rustup 对这两种架构都支持得很好，无非是安装后的工具链目录结构略有差异。如果你看到的是i686或armv7l这类比较旧的 32 位架构，不一定完全没戏，但后续能用的工具链版本会受限，建议你还是优先换 64 位系统再搞。

系统版本的意义在于：Rust 官方工具链对系统库比如 glibc 有最低版本要求。Ubuntu 22.04 和更新版本基本没有问题，太老的版本比如 18.04 也还能装，但是当你尝试把rustup update升级到很新的工具链时，有可能碰到“GLIBC_2.xx not found”的运行时错误。这个我放到后面踩坑部分详细说。

2.2 补齐编译器与链接器依赖

先问一句：你确定系统里有 gcc 和 make 吗？Rust 编译器本身用 LLVM 做后端，生成的目标文件最后还是要交给系统的链接器链接成可执行文件。Debian 系的最小安装、Docker 容器、云服务器镜像里，很多都没有预装 gcc。而cargo run跑起来的时候，rustc 默认会调用名为cc的链接器，找不到就报linker 'cc' not found。

所以哪怕你只是装 Rust 来写纯 Rust 代码，也建议先把这套基础构建工具装上：

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

curl是接下来执行 rustup 安装脚本要用的；build-essential这个元包会带上 gcc、g++、make、dpkg-dev 等一堆编译必需的工具。很多教程只让你装 curl，结果安装完 Rust，第一个cargo run就卡在链接器缺失上。反正 build-essential 在 Ubuntu 上装一次也不重，彻底免掉这个隐患。

另外，如果你之后要编译依赖 OpenSSL 的 crate，后面可能还会需要libssl-dev和pkg-config。这不是 Rust 安装阶段的必需项，但我习惯一次性装好，省得某个项目构建到一半突然失败：

sudo apt install -y libssl-dev pkg-config

2.3 网络与磁盘的基本预检

rustup 安装脚本会从官方 CDN 下载几百 MB 的工具链包，Cargo 后续编译项目时也会从 crates.io 拉取依赖。如果你的网络对境外资源连接不畅，建议提前准备好镜像配置，这个在第 5 节专门讲。先做个简单自检，看看能不能访问 Rust 官方资源：

curl -I https://sh.rustup.rs curl -I https://static.rust-lang.org

第一条如果返回 HTTP/200，说明安装脚本能正常下载；第二条是工具链包的下载域名。如果两个都通，直接装就行。如果第二个不通，你需要考虑在安装时单独配置镜像的 RUSTUP_DIST_SERVER 环境变量。

磁盘空间方面，一个完整工具链加默认组件大概占 1 到 2 GB，加上后续每个编译项目的 target 目录，建议至少留出 5 GB 空闲。用df -h看一眼/和家目录所在分区，别装到一半磁盘满了，那会留下一个残缺的 rustup 状态，清理起来比正常安装麻烦得多。

3. 用 rustup 安装 Rust：从命令到原理

3.1 执行官方安装脚本

确认系统状态没问题后，执行官方安装命令：

curl https://sh.rustup.rs -sSf | sh

解释一下这里发生了什么：curl把远程的安装脚本下载下来打印到标准输出，-sS表示静默模式但保留错误信息，-f表示遇到 HTTP 错误时立即失败，管道符号把它交给sh执行。这里有个常见的疑问：为什么官方推荐直接管道执行远程脚本？因为脚本本身是 Rust 项目组维护的，而且它会自动检测你的操作系统、架构和当前 shell 环境来配置安装路径。如果你的安全策略不允许管道执行远程脚本，也可以先下载到本地看一眼再执行：

curl https://sh.rustup.rs -sSf -o rustup-init.sh less rustup-init.sh sh rustup-init.sh

两种方式实际运行的程序是一样的。

3.2 安装选项里到底在选什么

脚本运行后会弹出选项：

1) Proceed with standard installation (default - recommended) 2) Customize installation 3) Cancel installation

输入 1 使用默认配置即可，这也是绝大多数人的选择。默认配置的含义是：安装 stable 工具链、使用 default profile，并把 cargo 的 bin 目录写入你的 shell 配置文件。

如果你选 2，会进入自定义安装，里面有三个 profile 可以选：

• minimal：只装 rustc、cargo、rust-std，适合极简环境或者后面想手动控制一切的情况。
• default：除上述外，还包含 rust-docs、rustfmt、clippy。日常开发推荐。
• complete：把所有官方组件全装上，包括各种平台的目标交叉编译支持，如果你要搞嵌入式、WASM 等，选这个会比较省事。

另外自定义里还能让你改安装目录、设置 RUSTUP_HOME 和 CARGO_HOME 的路径。强烈建议新用户保持默认，不要随手改目录。一旦改了，后续 bash 配置、编辑器插件、cargo 全局配置的路径全都对不上，问题排查成本立刻上天。

3.3 环境变量配置：为什么新终端才能用 rustc

安装结束时，脚本会提示环境变量已经写入 shell 配置，然后让你重新启动终端，或者手动执行：

source "$HOME/.cargo/env"

这里有个细节很容易被忽略：脚本检测到你是哪个 shell，就把source那一行写进对应的配置文件。如果你当前用的是 bash，它会写进~/.bashrc；如果是 zsh，会写进~/.zshrc。所以你在安装完 rustup 之后，再切换到另一个 shell，比如从 bash 切到 zsh，发现 rustc 命令找不到，不要慌，这很正常，在对应的配置文件里手动加上这一行即可。

~/.cargo/env这个文件本身内容很简单，主要是让 shell 把$HOME/.cargo/bin加入 PATH。rustc、cargo、rustup 的可执行文件都放在这个目录下。理解这一点之后，你以后遇到“命令找不到”的问题，第一反应就不会是重装一遍，而是检查 PATH 里有没有这个目录。

3.4 安装到底装到了哪里

安装完成后，你的家目录下会出现两个目录：

• ~/.rustup：rustup 自己的数据目录，所有工具链版本都放在这里。
• ~/.cargo：Cargo 的 HOME，包含了bin（可执行文件）、registry（依赖缓存）、config.toml（Cargo 全局配置）。

这两个目录就是你 Rust 开发环境的全部家当。想卸载干净，一条命令就够了：

rustup self uninstall

它会把 rustup 本身、所有工具链、相关配置全部清除。这也是我推荐 rustup 的另一个原因：装错了、不想用了、想重来了，恢复成本极低。相比之下，apt 装的 Rust 如果清理不干净，会在 /usr/bin 下留下各种残留文件，还容易和后续手动安装的版本混淆。

4. 验证安装并跑通第一个 Rust 项目

4.1 检查 rustc 和 cargo

安装完成后，先检查工具链是否正常。开一个新终端，或者执行source "$HOME/.cargo/env"，然后运行：

rustc --version cargo --version rustup show

正常情况下rustc --version会输出类似rustc 1.80.0 (000000000 2024-07-25)的格式，包含大版本号、commit hash 和发布日期，证明编译器的发布渠道和日期信息都正常。cargo --version会输出cargo 1.80.0或类似。rustup show则会列出当前默认工具链、已安装的工具链列表，以及有没有被某个项目目录指定的 override。

如果此时提示rustc: command not found，不要急着怀疑安装失败。先看是不是新开终端了，可以用which rustc确认，也能用echo $PATH看一下$HOME/.cargo/bin是否在路径里。这是新手遇到的第一大坑，我在第 7 节里会详细讲。

4.2 用 cargo 创建并运行第一个项目

工具链正常之后，找一个空目录，跑一遍标准的项目创建流程：

cargo new hello_world --bin cd hello_world cargo run

cargo new会自动生成一个 git 仓库、一个src/main.rs、一个Cargo.toml文件。--bin表示这是一个可执行程序项目，如果你是建库项目，用--lib。cargo run会先编译再执行，第一次运行你会看到类似下面的输出：

Compiling hello_world v0.1.0 (/home/你的用户名/hello_world) Finished dev [unoptimized + debuginfo] target(s) in 0.25s Running `target/debug/hello_world` Hello, world!

默认情况下cargo run使用的是 debug 构建，编译快、运行慢，适合开发阶段。真正需要性能时用cargo run --release，或者cargo build --release，会启用优化，编译时间会长一些，但程序的运行性能会好很多。

如果这一步能顺利跑出 Hello, world!，说明整个工具链、链接器、标准库、动态库依赖都正常。后面遇到编译失败的时候，你至少能确定不是基础环境的问题。

4.3 把 lint 和格式化工具顺手补齐

Rust 生态里有两把官方提供的趁手工具：rustfmt 负责代码格式化，clippy 负责代码检查。很多编辑器里集成 Rust 插件都依赖它们，所以我一般在装完环境后顺手确认一下：

rustup component add rustfmt clippy

如果安装时选了 default profile，它们通常已经在了，上面的命令会提示已经安装。之后你可以试试：

cargo fmt cargo clippy

cargo fmt会按官方统一的代码风格重新格式化代码，团队协作时能避免大量格式争论；cargo clippy会跑一整套 lint 规则，指出代码里可能有问题、有性能隐患的地方。养成每次提交前跑一遍 clippy 的习惯，Rust 代码质量会有非常明显的提升。

5. 网络不友好时的 Cargo 下载加速配置

5.1 crates.io 的下载链路为什么会慢

Rust 项目的依赖都托管在 crates.io 上，Cargo 在构建时需要访问它的索引，并下载对应的 crate 压缩包。如果你的网络访问这些境外服务速度不理想，最典型的表现是：运行cargo build时卡在Updating crates.io index或者Downloading crates ...，进度条半天不动。

需要先说明一点，很多网络问题并不是 crates.io 本身不可用，而是索引仓库体积较大、连接建立不稳定。Cargo 过去默认通过 git 方式拉取整个 crates.io-index 仓库，这个仓库有好几百 MB，首次配置时非常慢。新版本 Cargo 已经默认切换到 sparse 协议，也就是通过 HTTP 请求按需获取某个 crate 的索引信息，速度明显提升。

5.2 配置镜像源的核心思路

如果你的网络环境下访问 crates.io 确实不理想，可以考虑配置一个 Cargo 源镜像。原理很简单：在~/.cargo/config.toml文件里，把默认的 crates-io 源替换成另一个镜像源。

~/.cargo/config.toml是 Cargo 的全局配置文件，没有的话就自己创建一个。配置的核心结构如下：

[source.crates-io] replace-with = "my-mirror" [source.my-mirror] registry = "sparse+https://my-mirror.example.com/index/"

这里replace-with的作用是：声明的库依赖默认从 crates-io 找的时候，实际上切换到my-mirror这个源。“sparse+” 前缀表示使用 sparse 协议，后面的地址要替换成实际镜像站的地址。

至于具体用什么镜像，我建议你根据自己网络环境的实际情况去选，并优先选择口碑好、更新及时、你所在网络能够稳定访问的地址。部分团队内网还会维护自己的 Cargo 镜像，这种情况直接向运维同事要联系方式最靠谱。另外，如果你用的是海外云服务器，访问 crates.io 本身很快，那就完全没必要折腾镜像，保持默认即可。

5.3 用 sparse 协议减少不必要的开销

如果你的 Cargo 版本比较老，且选择了一个支持 sparse 协议的镜像，配置里记得带上sparse+前缀。这个前缀告诉 Cargo 走 HTTP 稀疏索引，而不是去 clone 整个索引仓库。

验证当前 Cargo 的默认协议版本，可以用：

cargo -V

Cargo 1.70 以后默认就是 sparse 方式，如果你还在用很老的 Cargo 版本，建议先把 rustup 升级到最新。新版 Cargo 在拉取依赖时的体验真是天壤之别，尤其是在依赖很多的项目里，整个“解析依赖”阶段可能从几分钟缩短到几秒。

5.4 验证配置是否生效

配置完成后，随便建一个带依赖的项目测试一下。比如在项目里执行：

cargo add serde --features derive cargo build

如果你的镜像源正常，构建过程不会长时间停在“Updating crates.io index”，依赖下载速度也会明显变快。想确认 Cargo 当前是不是真的在用镜像源，可以用：

cargo tree

或者直接看依赖缓存目录~/.cargo/registry里的包来自哪里。遇到疑似源配置不起作用的情况，打开~/.cargo/config.toml，检查有没有拼写错误、是不是存在多个重复的[source]段，以及配置文件有没有被某个项目目录下的.cargo/config.toml覆盖。项目级配置比用户级配置优先级更高，这个顺序要记清楚。

6. 日常开发更顺手的几个配置

6.1 多版本工具链与 override

rustup 最值钱的能力是版本管理。装完默认 stable 之后，你可能会需要 nightly 版本来使用一些实验性特性。安装很简单：

rustup toolchain install nightly

装完可以用rustup toolchain list查看本机已安装的所有工具链。之后你有几种切换方式：

• 全局切换默认版本：rustup default nightly
• 只在某个项目目录里固定版本：rustup override set nightly
• 临时用指定工具链跑一次命令：cargo +nightly build

我比较推荐用rustup override set这种方式，因为它不会影响其他项目。更规范的是在项目根目录创建一个rust-toolchain.toml文件，把工具链要求写进代码仓库，这样团队成员一进入项目，rustup 就会自动读取并切换：

[toolchain] channel = "stable" components = ["rustfmt", "clippy"]

这个做法在团队协作时非常稳，它消除了“我机器上用的是 nightly，为什么你的 stable 编译不过”这类摩擦。

6.2 编辑器与 rust-analyzer 的联动

只要你用现代编辑器写 Rust，基本都会通过 rust-analyzer 做语言服务。rust-analyzer 是一个实现了 LSP（Language Server Protocol）的独立进程，负责提供补全、跳转、重构、类型标注、实时错误提示等功能。

你的编辑器只需要装一个支持 LSP 的 Rust 插件，并通过它启动 rust-analyzer 即可。新版本 rustup 可以直接安装组件：

rustup component add rust-analyzer

装好后，在编辑器里打开 Rust 项目，就会发现代码高亮、补全、错误提示都出来了。如果你之前遇到过编辑器里报错说找不到 rust-analyzer，多半就是少了这一步组件安装。另外，编辑器插件通常会按照当前活动的工具链工作，所以在多个版本共存的情况下，编辑器里的行为会跟随你在该目录选择的 override 变化。

6.3 我常用的 Cargo 工作流命令

分享一套我日常写 Rust 项目时最常用的命令组合，虽然不是安装环境的必须内容，但可以帮你更快进入状态：

cargo init # 当前目录初始化项目 cargo add 依赖名 # 添加并写入 Cargo.toml cargo check # 快速检查编译错误，不生成二进制 cargo build # 构建 debug 版本 cargo build --release # 构建 release 优化版本 cargo run # 编译并运行 cargo test # 跑测试 cargo fmt # 格式化代码 cargo clippy # 检查潜在问题 cargo doc --open # 生成项目文档并打开

cargo check是我用得最多的一条，因为它不会生成最终二进制，只做一次快速的类型和所有权检查，在大型项目里能节省大量编译时间。写完一段代码，先 check 一遍，再跑格式化，最后补测试，基本就是我个人的标准节奏。

7. 安装和使用过程中反复踩过的坑

7.1 sudo 装的 rustup 后面全是麻烦

经常在论坛里看到有人问“为什么我明明装好了 rustup，打开终端却找不到 rustc”。一问大概率是执行了sudo curl https://sh.rustup.rs | sh。一旦用了 sudo，脚本会把 Rust 环境装到 root 的家目录下面，普通用户访问不到，而且~/.cargo、~/.rustup的所有者也变成了 root。更麻烦的是，事后想清理还得用 sudo，不然连删都删不干净。

正确的姿势是：使用普通用户直接执行安装脚本，不需要也不需要 sudo。如果你手滑已经装到了 root 目录，先确认一下：

ls -la /root/.cargo ls -la ~/.cargo

如果确认装错位置，就该清理重来。清理 root 目录下的环境需要权限，务必看清楚路径再操作，不要随手写一个rm -rf /之类的危险命令。清完后，在家目录下重新执行一次安装脚本即可。我还在项目 README 里专门加过一条提示：任何 Rust 相关操作都不要用 sudo 执行，其中也包括sudo cargo。cargo 会把编译缓存写到当前用户的~/.cargo下，一旦混入 root 权限，后续普通用户构建就会各种权限错误。

7.2 链接器找不到：Rust 编译器不是万能的

第二个高频错误是编译时出现：

error: linker `cc` not found | = note: No such file or directory (os error 2)

很多人以为 Rust 自带完整的编译和链接能力，其实 rustc 只是负责把 Rust 源码编译成目标文件，最后一步链接成可执行文件还是要交给系统里的 C 链接器。Ubuntu 容器、精简云服务器和部分发行版桌面系统默认都没有 gcc，所以这个错误出现得特别频繁。

解决办法就是补上基础构建工具：

sudo apt install -y build-essential

装完之后重新cargo build就能正常链接了。这类问题也提醒我们：Rust 生态里不少 crate 会依赖系统的 C 库，比如 OpenSSL、libpq、SQLite 等。你可能会在编译某些项目时遇到openssl-sys、pq-sys这类 crate 编译失败，多半是缺少对应的系统开发库。这不是 Rust 安装的问题，而是系统依赖缺失，按错误提示把对应的-dev包装上就行。

7.3 安装中断或升级失败怎么办

rustup 安装过程中如果网络中断、磁盘满了，或者你看到一堆半途而废的文件，最稳妥的办法是直接重置。先卸载旧状态，再重新安装：

rustup self uninstall rm -rf ~/.cargo ~/.rustup

rustup self uninstall在常态下会自动清理，但如果状态已经损坏，它可能跑不完，所以第二步手动删目录做兜底。这里要特别注意：~/.cargo里不只有配置文件，还有你所有第三方 crate 的缓存和已安装的全局工具。清理后第一次编译项目会比较慢，因为依赖要重新下载，这是正常现象。

rustup update升级失败的另一个原因是网络。升级时需要从 static.rust-lang.org 下载工具链包，如果你的网络对境外资源不稳定，可以考虑配置RUSTUP_DIST_SERVER环境变量，指向你所在网络能稳定访问的 Rust 工具链镜像。我这里就不推荐具体地址了，建议根据你的实际网络环境去查询“Rust 工具链官方镜像”这类资源来选一个适合的。

7.4 老系统上运行新工具链的兼容性问题

最后说一个比较隐蔽的问题，出现频率低，但一旦遇到就会让人抓狂。某个老版本的 Ubuntu 系统上，升级 rustup 和工具链到最新后，执行任何 rustc 命令都报错：

version 'GLIBC_2.29' not found

这就是 Rust 工具链包本身要求系统 glibc 版本足够新，而你系统里的 glibc 太老。Rust 官方在发布工具链时，会选择一个较新的最小系统库版本作为编译基准。对于这种系统，通常没有太好的完美解决方案，优先推荐把 Ubuntu 升级到较新的长期支持版本。如果你的业务场景必须留在老系统上，可以尝试使用特定历史版本的工具链：

rustup toolchain install 1.75.0 rustup default 1.75.0

老版本工具链依赖的系统库要求相对宽松，有时候能绕过这个限制。但本质上这只是权宜之计，新版编译器带来的性能优化、新特性和更好的错误提示都享受不到。所以我个人在给老系统装 Rust 之前，都会先提醒对方：你的系统皮太老了，强烈建议升级系统而不是委屈 Rust。

这些年我一直保持的一个习惯是：每周固定跑一次rustup update stable。Rust 的版本更新速度很快，每周都有大量改进和 bugfix，及时跟上能少踩很多编译器本身的坑。设置 override 和 rust-toolchain.toml 文件后，多版本共存也完全不会互相干扰。如果哪天你的 Rust 项目突然遇到奇怪的问题，先不要怀疑代码，按这篇文章的顺序查一遍环境：PATH 有没有问题、工具链是不是被 override 到了别的版本、系统依赖库有没有装齐。绝大多数安装层面的问题，都能在这三步里找到答案。