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 curl

2. 确保启用 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.service

nvidia-powerd 和 nvidia-suspend-then-hibernate 通常已被包自动启用，前三个一般需要手动 enable。

8. 重启

bash 复制代码

sudo reboot

9. 重启后验证

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 一条命令的事。

如果遇到坑点欢迎评论交流。

Debian 13 + NVIDIA Optimus 笔记本：从零配置 Wayland Explicit Sync 完整指南