Debian 13 + NVIDIA Optimus 笔记本：从零配置 Wayland Explicit Sync 完整指南
适用于 Debian 13 (trixie) + GNOME Wayland，NVIDIA Turing 及以上架构显卡（RTX 20/30/40 系列），通过 NVIDIA 官方 CUDA APT 仓库安装
nvidia-open开源内核模块，获得现代驱动栈与 Wayland Explicit Sync 体验。
前言
Debian stable 仓库的 NVIDIA 驱动版本会被冻结在某个 LTS 分支（trixie 当前是 550.163.01 ），不会随上游升大版本。而 Wayland Explicit Sync 需要 driver ≥ 555，新的开源内核模块（nvidia-open）也只能从更新的版本拿到。这就需要走 NVIDIA 官方 CUDA APT 仓库这条路。
本文按一个全新装好的 Debian 13 顺序走完所有步骤，最终目标：
- NVIDIA 驱动升级到 nvidia-open 595.71.05（或更新版本）
- GNOME Wayland 下 Explicit Sync 默认启用
- Optimus 双显卡（NVIDIA 独显 + AMD/Intel 集显）正常工作
- 挂起/恢复、视频播放、3D 加速、CUDA 全部就绪
适用环境
- 系统：Debian 13 (trixie)
- 桌面：GNOME Wayland
- 显卡 ：NVIDIA Turing 架构及以后（RTX 20/30/40 系列、A 系列等）
nvidia-open开源内核模块要求 Turing 及以后- Pascal/Volta 等更老的卡只能用闭源（走
cuda-drivers而不是nvidia-open）
- 建议：Secure Boot 已禁用（否则 DKMS 编出的内核模块需要 MOK 签名，处理流程繁琐）
整体流程
1. 系统更新和必要工具
2. 启用 contrib/non-free 源
3. 检查 Secure Boot 状态
4. 添加 NVIDIA CUDA APT 仓库
5. 模拟预检
6. 安装 nvidia-open
7. 重启前自检（关键！）
8. 重启
9. 重启后验证
10. 收尾清理1. 系统基础准备
bash
sudo apt update
sudo apt upgrade -y
# 装基础工具和内核头（DKMS 编译要用）
sudo apt install -y build-essential dkms linux-headers-$(uname -r) wget curl2. 确保启用 contrib + non-free（firmware 需要）
bash
grep -E '^[^#]*deb' /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null确认每行有 main contrib non-free non-free-firmware。Debian 13 安装器默认会启用，但建议手动确认。如果只有 main，编辑 sources.list 把每行末尾加上 contrib non-free non-free-firmware，然后 sudo apt update。
3. 检查 Secure Boot
bash
mokutil --sb-state- disabled ✓ → 直接进第 4 步
- enabled → 进 BIOS 关掉是最省事的；或者用
mokutil --import注册 DKMS 签名密钥（折腾）
4. 添加 NVIDIA CUDA APT 仓库（debian13）
bash
cd /tmp
wget https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update文件名版本号可能更新，到 https://developer.download.nvidia.com/compute/cuda/repos/debian13/x86_64/ 查看最新的
cuda-keyring_*.deb。
5. 模拟预检（不会真装）
bash
# 看可用版本
apt-cache policy nvidia-open
# 模拟安装看会动哪些包
sudo apt-get install --simulate nvidia-open关注点：
- 没有
unmet dependencies或held broken packages错误 - 移除列表里都是 Debian 自带的
nvidia-*旧包和 GLX alternative helper（全新系统这一项会是空的）
6. 安装 nvidia-open
bash
sudo apt install nvidia-open会经历：下载（≈300MB） → 卸旧包（如有） → 装新包 → DKMS 编译 + 签名内核模块 → 重建 initramfs。耗时几分钟，耐心等。
关键检查（命令完成后看输出末尾）：
- DKMS 必须看到
Building module(s).................. done. - 不能有
errors were encountered while processing - 留意是否出现
libkmod: ERROR: ... /etc/modprobe.d/nvidia.conf这类错误 ------ 见第 7 步处理
7. 重启前自检（关键，别跳过）
bash
# 7.1 DKMS 状态
dkms status
# 期望：nvidia/<version>, <kernel>, x86_64: installed
# 7.2 包版本是否对齐
dpkg -l | grep -E '^ii.*nvidia' | awk '{print $2, $3}' | sort
# 7.3 内核模块文件
ls /lib/modules/$(uname -r)/updates/dkms/ | grep nvidia
# 应该看到 5 个文件：
# nvidia.ko.xz / nvidia-modeset.ko.xz / nvidia-drm.ko.xz / nvidia-peermem.ko.xz / nvidia-uvm.ko.xz
# 7.4【最重要】blacklist nouveau 和 modeset 配置是否激活
ls -la /etc/modprobe.d/ | grep -iE 'nvidia|nouveau'
grep -rE 'blacklist[[:space:]]+nouveau|nvidia[-_]drm.*modeset' /etc/modprobe.d/ /usr/lib/modprobe.d/
# 7.5 initramfs 内容
sudo lsinitramfs /boot/initrd.img-$(uname -r) | grep -E '/(nvidia\.conf|nvidia-kms\.conf|nouveau\.ko)'⚠️ 坑点：如果出现 nvidia.conf.dpkg-new 但没有 nvidia.conf
这种情况发生于：之前装过 Debian 自己的 nvidia-driver 包，nvidia-alternative 残留导致 dpkg 不敢直接覆写新文件。后果：blacklist nouveau 不会生效，重启可能黑屏。
修复：
bash
# 先确认 .dpkg-new 内容包含 "blacklist nouveau"
cat /etc/modprobe.d/nvidia.conf.dpkg-new
# 激活
sudo mv /etc/modprobe.d/nvidia.conf.dpkg-new /etc/modprobe.d/nvidia.conf
sudo update-initramfs -u
# 重新验证
sudo lsinitramfs /boot/initrd.img-$(uname -r) | grep -E 'nvidia\.conf$|nouveau'
grep -rE 'blacklist[[:space:]]+nouveau' /etc/modprobe.d/启用挂起/恢复服务
bash
sudo systemctl enable nvidia-suspend.service nvidia-resume.service nvidia-hibernate.service
# 确认 5 个服务都 enabled
systemctl is-enabled \
nvidia-suspend.service \
nvidia-resume.service \
nvidia-hibernate.service \
nvidia-powerd.service \
nvidia-suspend-then-hibernate.servicenvidia-powerd 和 nvidia-suspend-then-hibernate 通常已被包自动启用，前三个一般需要手动 enable。
8. 重启
bash
sudo reboot9. 重启后验证
bash
# 9.1 驱动 & GPU 状态
nvidia-smi
cat /proc/driver/nvidia/version
# 关键看是否包含 "Open Kernel Module"
# 9.2 nouveau 没在跑
lsmod | grep -E '^nouveau' && echo "❌ nouveau 仍加载" || echo "✅ nouveau 未加载"
# 9.3 nvidia 模块全部加载
lsmod | grep -E '^(nvidia|nvidia_modeset|nvidia_drm|nvidia_uvm)'
# 9.4 仍是 Wayland 会话
echo "Session: $XDG_SESSION_TYPE / Desktop: $XDG_CURRENT_DESKTOP"
# 9.5 启动日志里 nvidia/drm/nouveau 相关错误（应该为空）
journalctl -b 0 -p err --no-pager | grep -iE 'nvidia|drm|nouveau'
# 9.6 Explicit Sync 间接验证（GNOME Shell 启动日志）
journalctl -b 0 --user-unit 'org.gnome.Shell*' --no-pager | grep -iE 'atomic|gbm|sync|egl'第 9.6 步应该能看到这几行关键日志：
Added device '/dev/dri/cardN' (nvidia-drm) using atomic mode setting------ atomic KMS 启用（Explicit Sync 的前提）Created gbm renderer for '/dev/dri/cardN'------ 现代 GBM 路径（注意是gbm，不是老式EGLStream）Obtained a high priority EGL context
只要日志里出现这三条，加上驱动版本 ≥ 555，Explicit Sync 就是默认启用的。日志里偶尔出现的 Invalid sequence for VSYNC frame info 是无害提示，可以忽略。
10. 收尾清理
bash
# 10.1 移除 Debian 旧 GLX alternative 体系的孤儿包
sudo apt autoremove --simulate # 先看一眼会动什么
sudo apt autoremove
# 10.2 清掉 rc 状态残留（已卸但配置文件还在）
dpkg -l | awk '/^rc/ && /nvidia|cuda/ {print $2}'
# 如果上面有输出，purge 掉：
sudo dpkg --purge $(dpkg -l | awk '/^rc/ && /nvidia|cuda/ {print $2}')
# 10.3 清掉旧 Debian nvidia-alternative 留下的目录
sudo rm -rf /etc/nvidia关键配置文件清单
| 路径 | 来源 | 作用 |
|---|---|---|
/etc/modprobe.d/nvidia.conf |
nvidia-open 包 | blacklist nouveau + 三条 NVreg_* 选项 |
/etc/modprobe.d/nvidia-kms.conf |
nvidia-open 包 | options nvidia-drm modeset=1 |
/usr/share/X11/xorg.conf.d/nvidia-drm-outputclass.conf |
nvidia-open 包 | X11 fallback OutputClass |
/etc/apt/sources.list.d/cuda-debian13-x86_64.list |
cuda-keyring 包 | CUDA APT 源定义 |
/lib/modules/<kernel>/updates/dkms/nvidia*.ko.xz |
DKMS 编译产物 | 5 个内核模块 |
故障排查
| 症状 | 排查方向 |
|---|---|
| 重启后黑屏 | GRUB 按 e 编辑内核命令行，加 nomodeset 进系统再排查 |
| GDM 循环登录 | Ctrl+Alt+F3 进 TTY；journalctl -b 0 -p err；多半是 nouveau 没 blacklist |
nvidia-smi: command not found |
nvidia-driver-cuda 包没装上或 PATH 问题 |
NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver |
内核模块没加载；`lsmod |
| Wayland 撕裂 / 拖窗口卡顿 | 确认 driver ≥ 555；确认日志里是 gbm renderer 而不是 EGLStream |
| 挂起后唤醒花屏 | 确认 nvidia-suspend/resume 服务 enabled；确认 NVreg_PreserveVideoMemoryAllocations=1 生效 |
完整回滚方案（如果一切完蛋）
进 TTY（Ctrl+Alt+F3）或 GRUB recovery 模式：
bash
sudo apt purge 'nvidia-*' 'libnvidia-*' 'cuda-*' 'libcuda*'
sudo apt autoremove --purge
sudo apt install nvidia-driver # 回到 Debian 仓库的 LTS 驱动
sudo reboot如果连 TTY 都进不去：GRUB 启动时按 e 编辑内核命令行，在 linux ... ro quiet 行末尾加 nomodeset，按 Ctrl-X 启动。
后续维护
- 内核更新时 ：DKMS 自动为新内核重编 nvidia 模块。重启前可
dkms status确认看到installed。 - 驱动版本升级 ：CUDA 仓库会持续推送新
nvidia-open版本，sudo apt update && sudo apt upgrade即可。不要 回头用 Debian backports 的nvidia-driver，会被版本降级冲突卡住。 - 想装 CUDA 工具链做 ML 开发 ：仓库已经配好了，直接
sudo apt install cuda-toolkit-13-X（X 看当时版本）。
不需要做的事
下面这些操作在一些早期教程里能看到，但 nvidia-open 路线下不再需要：
- ❌ 改
/etc/gdm3/daemon.conf强开 Wayland ------ NVIDIA 现代驱动下 GDM 会自动用 Wayland - ❌ 注释
/usr/lib/udev/rules.d/61-gdm.rules------ 同上 - ❌ 改 GRUB cmdline 加
nvidia-drm.modeset=1------ modprobe.d 已经覆盖 - ❌ 手动写
/etc/X11/xorg.conf------ 让 OutputClass 自动管 - ❌ 装
nvidia-driver（Debian 仓库）------ 会和 CUDA 仓库冲突 - ❌ 用
.run安装器 ------ Optimus + Wayland 场景排错痛苦，不推荐
总结
这套配置的核心思路是 绕过 Debian stable 的版本冻结 ，直接从 NVIDIA 官方 CUDA APT 仓库拿现代驱动，配合 nvidia-open 开源内核模块，让 GNOME Wayland 跑在 Explicit Sync 路径上。
整个流程跑下来大约 15-30 分钟（含下载和重启），稳定性远高于 .run 安装器路线，未来维护也是 apt upgrade 一条命令的事。
如果遇到坑点欢迎评论交流。