4、CUDA Toolkit安装：下载、安装步骤、环境变量配置、验证安装

核心原理：CUDA Toolkit的组成与安装本质

CUDA Toolkit并非单一程序，而是一套完整的异构计算开发栈。理解其组成是正确安装的前提。它主要包含以下层次：

NVIDIA驱动程序：负责操作系统与GPU硬件之间的底层通信，是运行任何CUDA程序的基础。Toolkit安装包通常自带匹配版本的驱动，但若系统已安装较新的驱动，可选择跳过。
CUDA运行时库（Runtime API）：提供 cudaMalloc、cudaMemcpy 等核心API，链接时使用 libcudart.so（Linux）或 cudart.lib（Windows）。
CUDA驱动API库：更底层的 libcuda.so，通常由驱动安装，应用开发中较少直接使用。
CUDA核心头文件：位于 include/ 目录，包含 cuda_runtime.h、device_launch_parameters.h 等。
NVCC编译器：将 .cu 源文件编译为GPU可执行的机器码，是开发流程中的关键工具。
CUDA数学库与工具：如 cuBLAS、cuFFT、Nsight 调试器，以及 nsys 性能分析器。

安装的本质是将上述组件正确部署到系统路径，并让编译器和链接器能够找到它们。因此，环境变量配置与安装文件复制同等重要，后者决定了 nvcc 能否被shell找到，以及运行时能否加载动态库。

版本匹配原则：务必确认CUDA Toolkit版本与显卡驱动版本、以及后续要安装的TensorRT、PyTorch等框架的版本兼容。例如，TensorRT 8.5通常要求CUDA 11.8或12.0。使用 nvidia-smi 右上角显示的CUDA版本号，表示当前驱动支持的最高CUDA版本，而非系统已安装的Toolkit版本。

方法流程：从下载到验证的完整步骤

步骤一：下载安装包

访问NVIDIA官网的CUDA Toolkit存档页面，根据操作系统选择对应的安装包格式。以Linux（Ubuntu 22.04）为例，推荐使用 deb (local) 版本，因为它支持离线安装且依赖管理更可靠。下载命令通常为：

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin
sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600
wget https://developer.download.nvidia.com/compute/cuda/12.3.1/local_installers/cuda-repo-ubuntu2204-12-3-local_12.3.1-545.23.08-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2204-12-3-local_12.3.1-545.23.08-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2204-12-3-local/cuda-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update

步骤二：执行安装

更新软件源后，执行安装命令。若系统已有驱动，建议使用 --no-install-recommends 避免自动安装驱动造成冲突：

sudo apt-get -y install cuda-toolkit-12-3

安装完成后，Toolkit默认位于 /usr/local/cuda-12.3 目录，同时会创建软链接 /usr/local/cuda 指向该版本，方便多版本切换。

步骤三：配置环境变量

编辑 ~/.bashrc 或 ~/.zshrc，添加以下内容：

export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

执行 source ~/.bashrc 使配置立即生效。对于Windows系统，则需在“系统属性 → 环境变量”中手动添加 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.3 到 PATH，并新建 CUDA_PATH 变量。

步骤四：验证安装

验证分为三个层次，缺一不可：

驱动验证：运行 nvidia-smi，确认GPU被正确识别，且右上角显示的CUDA版本号 ≥ 你安装的Toolkit版本。
编译器验证：运行 nvcc --version，应显示Cuda compilation tools的版本信息。
运行时验证：进入 /usr/local/cuda/samples/1_Utilities/deviceQuery 目录，执行 sudo make 后运行 ./deviceQuery，看到 PASS 字样即表示GPU与运行时通信正常。

快速自检命令组合：

# 一键检查驱动与Toolkit版本
nvidia-smi | grep "CUDA Version"
nvcc --version | grep "release"

# 编译并运行官方示例
cd /usr/local/cuda/samples/1_Utilities/bandwidthTest
sudo make
./bandwidthTest

案例/场景：多版本CUDA共存与切换

实际开发中，不同项目可能依赖不同CUDA版本。例如，旧版TensorRT要求CUDA 11.8，而新项目使用12.3。此时不应反复卸载重装，而是利用软链接切换：

操作	命令	说明
查看已安装版本	`ls /usr/local/ \| grep cuda`	列出所有cuda目录
切换默认版本	`sudo rm /usr/local/cuda` `sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda`	将软链接指向目标版本
验证当前版本	`nvcc --version`	确认已切换成功

此方法要求所有版本安装时均保留独立目录，且环境变量中 CUDA_HOME 指向软链接路径。对于使用 conda 的环境，也可通过 conda install cudatoolkit=11.8 实现项目级隔离，但系统级 nvcc 仍由软链接控制。

误区/复盘：常见安装失败原因与排查

误区一：混淆驱动自带CUDA与Toolkit
nvidia-smi 显示的CUDA版本是驱动支持的最大版本，不代表系统已安装Toolkit。很多初学者看到驱动显示12.3就认为无需安装Toolkit，导致 nvcc 命令找不到。记住：驱动提供运行时，Toolkit提供编译器。

误区二：环境变量未生效或路径错误
配置了 ~/.bashrc 但忘记 source，或使用了错误的库路径（如 lib64 与 lib 混淆）。排查时执行 echo $LD_LIBRARY_PATH 确认路径包含 /usr/local/cuda/lib64。若运行程序报 libcudart.so.12: cannot open shared object file，则说明动态库路径未配置正确。

误区三：权限不足导致编译失败
在 samples 目录下编译时，若未使用 sudo make，可能因无法写入生成文件而报错。此外，某些Linux发行版需要额外安装 gcc、make 和 linux-headers，否则 nvcc 无法调用宿主编译器。

复盘清单：安装完成后的必查项

✅ nvidia-smi 能列出GPU型号，且驱动版本 ≥ Toolkit版本。
✅ nvcc --version 输出与安装版本一致。
✅ deviceQuery 运行结果为 PASS，且显示GPU的算力能力（Compute Capability）。
✅ bandwidthTest 测得的H2D/D2H带宽接近理论值（如PCIe 3.0 x16约12GB/s）。
✅ 环境变量在重启终端后依然生效（已写入 ~/.bashrc）。
✅ 若使用IDE（如VS Code），已配置 includePath 指向 /usr/local/cuda/include。

完成以上步骤后，你的系统已具备编译和运行CUDA程序的基础能力。接下来可以放心安装TensorRT，因为其依赖的CUDA运行时环境已经就绪。若后续遇到链接错误，优先检查 LD_LIBRARY_PATH 是否被其他软件覆盖，以及是否存在多个CUDA版本导致的符号冲突。