遇到 CUDA 初始化失败、找不到设备或程序启动即报错，先别急着重装。CUDA兼容性与驱动版本管理的关键，是分清显卡、NVIDIA 驱动、CUDA Toolkit 和应用程序各自的版本关系；其中一项不匹配，就可能导致运行失败。下面按六项逐步排查。
先核对硬件和驱动：前两项检查
1. 确认程序实际看到的显卡
先运行 nvidia-smi，确认显卡型号、数量和驱动版本。若命令提示找不到，或列表中没有预期设备，问题可能在驱动安装、设备识别或运行环境权限，尚未到 CUDA Toolkit 这一层。再对照 NVIDIA 公布的显卡计算能力列表，确认目标 CUDA 应用支持该型号；较旧显卡可能无法使用较新的工具包或应用构建版本。
2. 查清驱动是否满足工具包要求
用 nvidia-smi 查看当前驱动版本，再查对应 CUDA Toolkit 版本发布说明中的最低驱动要求。不同操作系统、工具包小版本及安装方式可能有差异，应以对应版本的兼容说明为准。驱动较新时，通常可以运行使用较旧 CUDA 版本构建的程序，但仍受兼容规则和程序是否依赖特定功能等条件限制；旧驱动则不能当然运行新版本程序。
分清“显示的版本”和“实际使用的版本”
3. 不要把 nvidia-smi 的 CUDA 字样当成已安装工具包
nvidia-smi 显示的 CUDA Version，表示驱动支持的 CUDA 兼容能力信息，并不等于本机已安装的 CUDA Toolkit 版本。若需要编译，运行 nvcc --version 查看编译器版本；若提示命令不存在，可能是未安装 Toolkit，也可能是 PATH 未配置。CUDA兼容性与驱动版本管理要分别记录驱动版本和工具包版本，不能只看一处输出。
4. 核对应用或框架对应的 CUDA 构建
同一应用可能提供面向不同 CUDA 版本的安装包。查看安装包说明、依赖信息或启动日志，确认它实际携带或要求的 CUDA runtime 版本，并与驱动兼容要求比对。若使用 cuDNN，还要确认其版本与所用 CUDA 及框架构建相匹配。编译器版本、运行时库版本和驱动版本不是同一个概念，单独升级其中一项不一定能解决冲突。
检查系统环境与运行位置
5. 排除多套库和路径冲突
同一台机器可能留有多个 Toolkit，应用启动时却加载了另一套动态库。Linux 可检查 PATH、LD_LIBRARY_PATH 及包管理器安装记录；Windows 可检查 PATH 中是否有多个 CUDA 目录，并确认程序实际找到的 DLL 所在位置。先关闭相关程序，再核对它使用的库路径；不要在不清楚依赖关系时直接删除目录或覆盖系统库。
6. 容器场景检查宿主机驱动映射
若程序在容器里运行，先在宿主机运行 nvidia-smi，再进入容器检查是否能看到设备。容器通常提供应用所需的 CUDA 用户态库，显卡驱动则由宿主机提供并通过容器运行配置映射；因此容器里安装一套驱动并不能替代宿主机驱动。核对容器启动参数、设备权限和 NVIDIA Container Toolkit 配置，并确认容器内的应用版本没有超出宿主机驱动支持范围。
按顺序定位，比反复重装更稳妥
- 保存完整报错信息，尤其是驱动初始化、设备不可见或库加载失败等提示。
- 记录显卡型号和 nvidia-smi 输出，再确认 nvcc 版本；注意两者回答的是不同问题。
- 查工具包或应用发布说明中的驱动要求，逐项比对系统、显卡与软件构建。
- 若仅某个环境失败，优先检查路径、依赖和容器映射；确认原因后再调整单一组件。
- 改动后重新启动相关程序并复查输出。CUDA兼容性与驱动版本管理应保留变更前后的版本记录，便于回退和复现。
通常，先定位不匹配的层级，再决定更新驱动、切换应用构建还是修正库路径，比一次性重装所有组件更容易控制影响范围。
常见问题
nvidia-smi 能运行，为什么程序仍报 CUDA 错误？
它只能说明驱动工具能够查询设备，不代表应用所需的运行时库、框架构建或显卡计算能力一定匹配。
只升级驱动可以解决问题吗？
如果原因是驱动低于应用要求，升级可能有效；若是库路径冲突、容器未映射设备或应用不支持该显卡，升级驱动未必有用。
必须安装完整 CUDA Toolkit 才能运行应用吗？
不一定。预编译应用可能自带所需运行时库；需要使用 nvcc 编译 CUDA 程序时，才需要相应工具包。
应当优先记下哪些版本？
至少记录显卡型号、驱动版本、Toolkit 或应用所用 CUDA 版本，以及操作系统。这样才能按 CUDA兼容性与驱动版本管理的思路准确判断问题。
