Ubuntu Rust 配置常见问题

Ubuntu 上配置 Rust 的常见问题与解决

一 安装与镜像加速

• 使用官方脚本安装时卡住或很慢，多为网络问题。优先设置 rustup 镜像再安装，命令如下（临时生效，也可写入 shell 配置文件使其永久生效）：
  • 设置镜像
    • export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
    • export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup
  • 安装 rustup
    • curl --proto ‘=https’ --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • 激活环境
    • source “$HOME/.cargo/env”
• 若仍出现下载组件缓慢或失败，可检查网络 DNS（如将 /etc/resolv.conf 的 nameserver 临时改为 8.8.8.8），再重试安装。
• 安装前建议先准备编译工具链，避免后续构建失败：
  • sudo apt update && sudo apt install -y curl build-essential gcc make
• 验证安装
  • rustc --version
  • cargo --version
• 说明：通过 APT 安装（sudo apt install rustc cargo）版本通常较旧；开发建议使用 rustup 获取最新稳定版与完整工具链。

二 工具链与构建问题

• 编译报错 linker ‘cc’ not found：缺少系统链接器/编译器。
  • 解决：sudo apt install -y build-essential（提供 gcc、make 等）。
• 需要特定目标（如 wasm32-unknown-unknown）时未安装对应目标。
  • 解决：rustup target add wasm32-unknown-unknown（如需指定工具链：rustup target add wasm32-unknown-unknown --toolchain 1.80）。
• 升级或回退工具链
  • 升级：rustup update
  • 切换版本：rustup default 1.80（示例版本）
• 验证工具链与目标
  • rustup toolchain list
  • rustc -Vv && cargo -V

三 crates.io 下载加速与私有仓库

• 为加速依赖下载，配置 Cargo 镜像（以中科大为例，写入 ~/.cargo/config）：

  • mkdir -p ~/.cargo

  • cat < ~/.cargo/config [source.crates-io] replace-with = ‘ustc’

    [source.ustc] registry = “sparse+https://mirrors.ustc.edu.cn/crates.io-index/”

    [net] git-fetch-with-cli = true EOF

• 说明：sparse 索引更快；某些网络下开启 git-fetch-with-cli 可提升稳定性。
• 若项目使用私有 Git 依赖或自建 crates.io 镜像，可在 ~/.cargo/config 增加对应 source 段（replace-with 指向你的私有源）。

四 多用户与卸载

• 多用户共用：rustup 默认安装到用户目录（如 ~/.rustup 与 ~/.cargo），不会污染系统目录；其他用户如需使用，在其各自账户下同样安装 rustup 即可。
• 卸载
  • 仅卸载工具链：rustup self uninstall
  • 若通过 APT 安装过系统包，可额外执行：sudo apt remove --purge rustc cargo && sudo apt autoremove
• 权限与环境
  • 安装与更新无需 sudo；确保 PATH 包含 $HOME/.cargo/bin
  • 新开终端或执行 source “$HOME/.cargo/env” 使环境生效。

五 快速排查清单

• 命令未找到：echo $PATH 是否包含 $HOME/.cargo/bin；若不包含，执行 source “$HOME/.cargo/env” 或重新登录。
• 安装或更新卡顿：确认已设置 RUSTUP_DIST_SERVER / RUSTUP_UPDATE_ROOT；必要时更换 DNS 为 8.8.8.8 后重试。
• 构建失败提示缺少 cc/linker：sudo apt install -y build-essential。
• 需要 WASM 目标：rustup target add wasm32-unknown-unknown（按需指定工具链版本）。
• 依赖拉取慢：检查 ~/.cargo/config 是否配置了镜像与 sparse 索引。