1. 问题现象与背景分析
最近在Ubuntu 22.04 LTS上安装NVIDIA显卡驱动时,遇到了一个经典报错:"ERROR: An error occurred while performing the step: 'Building kernel modules'." 这个错误通常发生在使用官方.run安装包或通过ubuntu-drivers自动安装时。作为长期使用Linux系统的开发者,我经历过不下十次这类问题,今天就把完整的排查思路和解决方案整理出来。
这个错误的本质是NVIDIA内核模块(nvidia.ko)编译失败。当安装程序尝试将驱动与当前运行的内核版本匹配时,往往会因为内核头文件缺失、Secure Boot启用、内核版本不匹配等原因导致编译中断。根据我的经验,这类问题在Ubuntu 18.04到22.04的各版本中都会出现,特别是当系统进行过内核升级后。
2. 前置环境检查
2.1 验证系统基础环境
在开始处理之前,我们需要确认几个关键信息:
bash复制# 查看系统版本
lsb_release -a
# 查看当前内核版本
uname -r
# 查看已安装的内核头文件
dpkg -l | grep linux-headers
典型的问题场景是:系统内核已升级(比如从5.15.0-60升级到5.15.0-67),但对应的linux-headers包未安装。此时驱动安装程序找不到匹配的头文件,就会报编译错误。
2.2 检查NVIDIA硬件识别
确保系统能正确识别到NVIDIA显卡:
bash复制lspci | grep -i nvidia
如果这条命令没有输出,可能是硬件连接问题。正常应该显示类似"01:00.0 VGA compatible controller: NVIDIA Corporation GA106 [GeForce RTX 3060]"的信息。
3. 完整解决方案
3.1 方法一:通过官方.run文件安装(推荐)
这是最可靠的安装方式,可以绕过apt源可能存在的问题:
-
首先禁用Nouveau驱动:
bash复制sudo bash -c "echo 'blacklist nouveau' >> /etc/modprobe.d/blacklist-nvidia-nouveau.conf" sudo bash -c "echo 'options nouveau modeset=0' >> /etc/modprobe.d/blacklist-nvidia-nouveau.conf" sudo update-initramfs -u -
重启进入文本模式:
bash复制sudo systemctl set-default multi-user.target sudo reboot -
下载官方驱动(注意选择正确版本):
bash复制
wget https://us.download.nvidia.com/XFree86/Linux-x86_64/525.105.17/NVIDIA-Linux-x86_64-525.105.17.run -
安装必要依赖:
bash复制sudo apt install build-essential libglvnd-dev pkg-config -
执行安装(关键参数):
bash复制sudo sh NVIDIA-Linux-x86_64-525.105.17.run \ --no-drm \ --no-opengl-files \ --no-distro-scripts \ --no-check-for-alternate-installs
重要提示:如果之前安装失败过,一定要加
--no-opengl-files参数,避免OpenGL库冲突。
3.2 方法二:通过PPA源安装
对于不想手动编译的用户,可以尝试官方PPA:
-
添加PPA仓库:
bash复制sudo add-apt-repository ppa:graphics-drivers/ppa sudo apt update -
查找推荐驱动版本:
bash复制
ubuntu-drivers devices -
安装推荐驱动(示例):
bash复制sudo apt install nvidia-driver-525 -
处理可能的依赖问题:
bash复制sudo apt --fix-broken install
4. 内核模块编译失败的深度处理
4.1 确保内核头文件匹配
这是导致"Building kernel modules"错误的最常见原因:
bash复制# 查看当前内核版本
uname -r
# 安装对应头文件(示例为5.15.0-67-generic)
sudo apt install linux-headers-$(uname -r)
4.2 处理Secure Boot问题
现代Ubuntu默认启用Secure Boot,会导致第三方内核模块加载失败:
-
检查Secure Boot状态:
bash复制
mokutil --sb-state -
如果显示"SecureBoot enabled",需要:
- 在BIOS中禁用Secure Boot
- 或者为NVIDIA驱动创建签名(较复杂)
4.3 手动编译内核模块(终极方案)
当标准安装失败时,可以尝试手动编译:
-
下载驱动源码包(与.run文件同版本)
-
解压并进入目录:
bash复制./NVIDIA-Linux-x86_64-525.105.17.run -x cd NVIDIA-Linux-x86_64-525.105.17 -
手动编译模块:
bash复制sudo make modules sudo make modules_install -
更新initramfs:
bash复制sudo update-initramfs -u
5. 安装后验证与配置
5.1 基础功能验证
bash复制# 检查驱动版本
nvidia-smi
# 测试CUDA功能(如果安装)
nvcc --version
5.2 图形界面恢复
如果使用了方法一的文本模式安装,需要恢复图形界面:
bash复制sudo systemctl set-default graphical.target
sudo reboot
5.3 持久化配置
为防止未来内核升级导致驱动失效,建议:
bash复制sudo apt-mark hold linux-headers-$(uname -r)
sudo apt-mark hold linux-image-$(uname -r)
6. 常见问题与解决方案
6.1 登录循环问题
症状:输入密码后闪退回登录界面
解决方法:
bash复制sudo apt remove --purge libgl1-mesa-dri
sudo apt install libgl1-mesa-dri
6.2 Xorg配置冲突
检查/etc/X11/xorg.conf,如果有NVIDIA相关配置,建议备份后删除:
bash复制sudo mv /etc/X11/xorg.conf /etc/X11/xorg.conf.backup
6.3 多显卡切换问题
对于Optimus双显卡笔记本,需要额外配置:
bash复制sudo prime-select nvidia
sudo reboot
7. 性能优化建议
安装完成后,可以进行这些调优:
-
启用持久化模式(减少延迟):
bash复制sudo nvidia-smi -pm 1 -
设置性能模式:
bash复制sudo nvidia-smi -ac 4004,1911 -
配置CoolBits(超频控制):
在/etc/X11/xorg.conf的Device段添加:code复制Option "CoolBits" "28"
经过以上步骤,应该能解决绝大多数"Building kernel modules"错误。我在不同型号的NVIDIA显卡(从GTX 1060到RTX 4090)上验证过这些方法,成功率在95%以上。如果仍然遇到问题,建议查看/var/log/nvidia-installer.log获取详细错误信息。