企业官网建设流程全解析

做深度学习或者图像渲染的，基本都逃不过这一关：在Linux上装CUDA。这事儿官网看着很简单，页面右上角点两下就能拿到安装命令，但真到自己动手，那真是一堆坑等着你。我第一次装的时候，光一个"CUDA .run gzip: stdin: invalid compressed># 用apt卸载旧驱动 sudo apt purge nvidia-* -y # 用runfile装过就用runfile自带卸载 sudo /usr/bin/nvidia-uninstall # 顺手清理一下可能残留的库 sudo apt autoremove -y

卸载干净后重启一次再装新的，这个习惯能救你很多次。尤其是你之前装的是NVIDIA显卡驱动，后来换成AMD显卡，或者反过来，残留的内核模块会导致启动黑屏。别问我是怎么知道的。

3.2 禁用Nouveau，这一步不能省

Nouveau是Linux内核自带的NVIDIA显卡开源驱动，虽然功能弱，但它会跟官方闭源驱动抢设备。不把它禁用掉，装驱动时大概率报错，或者装完驱动加载不了。

Ubuntu和Debian系系统里建一个黑名单文件：

sudo nano /etc/modprobe.d/blacklist-nouveau.conf

写上：

blacklist nouveau options nouveau modeset=0

然后更新内核引导并重启：

sudo update-initramfs -u sudo reboot

重启后执行lsmod | grep nouveau，没有输出就说明禁用成功了。CentOS/RHEL系用的是dracut，流程类似但命令不同，这里不再赘述。

3.3 跑runfile时遇到"gzip: stdin: invalid compressed># 官网页面会有md5值，把它跟本地文件对比 md5sum cuda_12.4.0_550.54.14_linux.run

第二，下载到的其实是个HTML页面。这种情况多发生在公司代理、镜像站或者wget带错了参数的时候。runfile实际没下下来，而是保存了一个错误页。用file命令一看就露馅：

file cuda_12.4.0_550.54.14_linux.run

正常情况应该输出ELF 64-bit LSB executable或者类似的行，如果你看到HTML document，那恭喜你，白下了。

第三，下载的是Windows版或者架构不对的包。Linux runfile和Windows安装包虽然都带cuda字样，但字节结构完全不同。x86_64的机器别下ARM/aarch64版本。检查方法还是file命令加uname -m对照。

处理完这三个原因，这个报错基本能解决。顺带说一句，那个报错前面还经常带着"cuda .run"字样，看起来很吓人，其实就是压缩层校验没通过，问题不在系统，在文件本身。

3.4 安装并配置环境变量与验证

确认文件没问题后，开始安装。我的习惯是最小化安装：

sudo sh cuda_12.4.0_550.54.14_linux.run

交互界面里注意，第一步选择接受协议，第二步有个很关键的选项：如果你系统里已经用apt或其它方式装好了驱动，这里一定要把Driver那一项的[X]给去掉，让它只装Toolkit。如果你想顺带装驱动，先确认系统里没有旧驱动，否则容易冲突。

选好组件后，安装器会问安装路径，默认是/usr/local/cuda-12.4，这个路径很有用，后面多版本切换就靠它。装完末尾提示要添加环境变量，官方推荐写进~/.bashrc：

export PATH=/usr/local/cuda-12.4/bin${PATH:+:${PATH}} export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

然后source ~/.bashrc，验证三板斧：

nvcc --version nvidia-smi ls /usr/local/cuda-12.4

nvcc能出版本号，nvidia-smi能看到显卡和驱动信息，第三个目录存在，说明安装基本成功。

4. 多版本CUDA共存与切换

4.1 为什么需要多版本共存

搞深度学习的人电脑里大概率同时有好几个项目，有的项目只能在PyTorch 1.12 + CUDA 11.3下跑，有的项目又要求CUDA 12.1，强迫你只保留一个版本，那基本等于告别某些老项目。

多版本共存不是装好几个驱动，而是装多个CUDA Toolkit。注意，驱动只需要一个，且驱动版本要大于等于你所有Toolkit中要求的最高版本。Toolkit则可以并列装在/usr/local/cuda-11.x、/usr/local/cuda-12.x，互不干扰。

4.2 安装目录规划与软链接管理

跑runfile安装多个版本时，每装一个都有一步选择安装路径。默认路径是/usr/local/cuda-版本号，比如cuda-12.4，这个路径建议直接保留。NVIDIA安装器最后通常还会问你"是否创建/usr/local/cuda软链接"，如果它帮你创建了，这个软链接默认指向最新安装的版本。

软链接/usr/local/cuda就是我们切换版本的关键。比如当前指向12.4：

ls -l /usr/local/cuda # /usr/local/cuda -> /usr/local/cuda-12.4

笔记里还没提到的是，除了PATH变量，LD_LIBRARY_PATH也要跟着变，很多动态库找不到的问题就是变量没切干净。

4.3 用切换脚本快速换版本

手工每次改~/.bashrc里的路径太累，写个小脚本放~/.cuda_switch.sh，每次要切换的时候执行一下：

#!/bin/bash # 用法：source ~/.cuda_switch.sh 12.4 CUDA_VERSION=$1 export PATH=/usr/local/cuda-${CUDA_VERSION}/bin:${PATH} export LD_LIBRARY_PATH=/usr/local/cuda-${CUDA_VERSION}/lib64:${LD_LIBRARY_PATH} export CUDA_HOME=/usr/local/cuda-${CUDA_VERSION}

或者更简单，直接改软链接本身：

sudo rm /usr/local/cuda sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda

只要你的~/.bashrc里写的是软链接路径而不是写死的版本号，改一次软链接就能全局切换。这个思路最稳，推荐。

4.4 新老版本迁移时的建议

热搜词里有"Cuda迁移"，这里提醒一个原则：别删旧版本。把新版本装好、把项目在新环境跑通、把验证结果对比过，确认无差异之后再考虑清理旧版本。清理时直接删目录就行，不用卸载器，因为Toolkit只是文件，不涉及内核模块。

迁移最常翻车的点在cuDNN。cuDNN是按CUDA主版本对应下载的，比如8.x对应CUDA 12.x，迁移后忘换cuDNN，程序会在运行时直接报找不到libcudnn.so或者版本不匹配。装的时候记得把对应版本的libcudnn替换或链接到新的/usr/local/cuda/lib64里。

5. 常见问题与排查技巧实录

5.1 版本查看命令全家桶

每次帮人排查环境，第一件事就是让他把下面的输出贴给我：

nvidia-smi # 驱动版本、显卡、驱动支持的CUDA上限 nvcc --version # 当前默认Toolkit版本 ls /usr/local/cuda*/version.json # 看具体每个Toolkit的版本信息 cat /usr/local/cuda/version.json # CUDA 12.x以后用这个 python -c "import torch; print(torch.version.cuda)" # PyTorch自带的运行时CUDA版本 python -c "import torch; print(torch.backends.cudnn.version())" # PyTorch里的cuDNN版本 conda list cudatoolkit # conda环境下的CUDA版本 conda list cudnn # conda环境下的cuDNN版本

这一套命令打出去，绝大多数版本不匹配问题都能暴露出来。特别提醒，看到torch.version.cuda跟nvcc --version不一致是正常的，因为PyTorch wheel自带运行库，跟系统nvcc没有直接关系。

5.2 WSL2里装CUDA的特殊之处

很多人现在喜欢在Windows上用WSL2跑Linux环境，这个方案我很喜欢，但要注意一点：WSL2里不要装NVIDIA驱动，也不要装CUDA里的Driver组件。

WSL2使用Windows侧的显卡驱动，Linux端只需要装CUDA Toolkit即可。官方推荐的做法是：

sudo apt-key del 7fa2af80 wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update sudo apt install cuda-toolkit-12-4

装完在WSL里敲nvidia-smi，能正常显示显卡信息。如果发现WSL里nvidia-smi报错，多半是Windows侧驱动太老或者没装，不是Linux侧的问题。另外，WSL2里跑CUDA程序一般直接走Windows驱动，性能损耗很小，放心用。

5.3 conda环境下cudnn版本匹配

用conda装cudatoolkit=11.7之后，配套的cuDNN最好也交给conda管：

conda install -c conda-forge cudnn=8.4.1

conda会检查cudatoolkit和cudnn的依赖关系，一般不会出错。如果你非要手动下NVIDIA官网的cuDNN，就必须去官网对应页面下载with CUDA 11.x的版本，然后把解压出来的lib和include分别复制到conda环境的lib和include目录里。两种方式我都用过，结论是让conda管最省事，手动复制容易漏文件。

5.4 其他让人崩溃的报错速查表