本文是《AI工程师踩坑实录》系列第 2 篇，接上一篇的三个 CUDA 数字，讲遇到 is_available 返回 False 时怎么把断点定位出来，而不是瞎重装。所有输出截图都来自我这台 GTX 1660 Ti 的老笔记本真机复现。
本篇配套的 cuda_doctor 定位脚本（三条命令打包成一条）查看博主简介。
一个灵魂拷问。GPU 用不上的时候，你的第一反应是什么。
我见过最多的答案是，卸载驱动，重装驱动。不行？卸载 CUDA，重装 CUDA。还不行？重装系统。三连打完，问题还在原地等你。
这就是本篇要解决的事。上一篇讲清了三个数字各是谁（没看的话建议先翻第 1 篇），这一篇给你一套定位方法，一条命令，把断点钉在哪一层直接说出来。
一、先看断点全绿长什么样
先给个健康基准。下面是修好之后我这台机器的真实输出，三层全通。
驱动层，GTX 1660 Ti，驱动 580.88，上限 CUDA 13.0。框架层，torch 2.9.1+cu126，version.cuda 是 12.6。配置层，干净。结论一行字，三层全通，GPU 可用。
记住这个样子，下面两个断点案例都是它坏掉的样子。
二、断点 A · 框架层，CPU 版 wheel（最常见）
占比最大的断点。特征有两个，torch.version 带 +cpu 尾巴，version.cuda 是 None。
上一篇详细讲过它怎么来的（Windows 下 PyPI 默认源给的就是 CPU 版），这里只强调定位视角。三层信息摆在一起，驱动层是好的，配置层是干净的，断点只可能在框架层，version.cuda 那个 None 就是铁证。
修法上篇讲过，换官方 cu 源的轮子，五分钟的事。
三、断点 B · 配置层，环境变量把设备藏了（最隐蔽）
这个断点我专门留着这篇讲，因为它坑人的方式和 A 完全不同。
我在同一个环境里，一行配置没改 torch，一秒钟让 GPU 失踪。看真实输出。
注意三层信息有多迷惑人。驱动层正常，框架层 version.cuda 是 12.6，轮子没问题。全都是好的，is_available 却是 False，device_count 是 0。
真凶在最后一层，CUDA_VISIBLE_DEVICES 被设成了 -1。这个环境变量的意思是，对后面的程序宣布，一块可见显卡都没有。它常出现在三种场景，你之前调试时手动设过忘了清、启动脚本或者自动化流水线里有人写死、从某个继承了配置的容器或远程会话里带过来的。
这种断点最气人的地方在于，报错一个都没有，所有版本号全对，你按上一篇的思路查三个数字，全查不出毛病。所以定位脚本必须把配置层也扫一遍。
清掉它，一行命令的事，立刻恢复全绿。
四、断点 C · 驱动层，为什么放最后查
还有一种情况，轮子带 CUDA、配置也干净，is_available 还是 False。这时候才轮到驱动层，典型原因是驱动太老，带不动轮子里打包的 CUDA 版本。
我把它放在最后，两个理由。一是概率，前三层断点占了实际案例的绝大多数，驱动问题的比例小得多。二是代价，重装驱动有风险（中断、装错版本、双显卡笔记本切换出问题），把它当最后的排查手段才合理，当第一反应就是灾难。
五、四步定位，一张图带走
把四步排查画成决策树，按概率排序，从最常见查到最隐蔽。
再配一张速查表，断在哪层、看什么特征、干什么动作。
| 断点 | 一眼特征 | 动作 |
|---|---|---|
| A 框架层 | 版本号带 +cpu 尾巴，version.cuda 是 None | 换官方 cu 源轮子，别动驱动 |
| B 配置层 | 一切正常但 device_count 是 0，环境变量被设值 | 清环境变量，查清是谁设的 |
| C 驱动层 | 轮子带 CUDA、配置干净，仍然 False | 升级驱动到轮子要求的版本之上 |
| 无断点 | is_available 是 True，device_count ≥ 1 | 开工 |
六、常见问题 3 连
1. 我不想跑脚本，手动按什么顺序查？
照决策树的顺序来。一敲 nvidia-smi 看驱动在不在，二看 torch 版本有没有 +cpu 尾巴，三看环境变量里有没有人动了 CUDA_VISIBLE_DEVICES，四才考虑驱动升级。每一步十秒钟，比一次盲目的驱动重装快得多。
2. CUDA_VISIBLE_DEVICES=-1 到底是谁设的？
常见三个来源。当前 PowerShell 会话里自己设过（重启会话就没了），系统环境变量面板里被写死（这个最坑，每个新会话都甩不掉），启动脚本、IDE 运行配置或容器里继承了别人的配置。逐个翻一遍，十有八九能抓到。
3. 照着查完三层还是 False，还有什么可能？
概率很低但确实存在。老显卡撞上新轮子（算力没编进去，会报 no kernel image，第 5 篇专门讲），双显卡笔记本的调度策略问题，以及个别 DLL 加载失败的玄学场景。到这一步，把 cuda_doctor 的完整输出发我评论区，我帮你一起看。
七、本篇小结
- is_available 是 False，先定位断点，别上来就重装。
- 三层定位顺序按概率排，框架层最常见，配置层最隐蔽，驱动层放最后。
- 断点 B 一个报错都不给，必须主动查环境变量。
本篇坑卡片
| 字段 | 内容 |
|---|---|
| 坑名 | CUDA_VISIBLE_DEVICES=-1 让 GPU 完全失踪且无任何报错 |
| 现象原文 | is_available 为 False，device_count 为 0，无报错 |
| 环境 | Win11，GTX 1660 Ti，驱动 580.88，torch 2.9.1+cu126，Python 3.12 |
| 复现步骤 | 会话内设置 CUDA_VISIBLE_DEVICES 为 -1 → 跑验证 → False → 清除后恢复 True |
| 根因 | 环境变量对进程屏蔽了全部 CUDA 设备，驱动与框架均正常 |
| 解法 | 清除该变量，顺藤摸瓜查设置来源（会话、系统面板、启动脚本） |
| 避坑建议 | GPU 失踪先查配置层，重装驱动放在最后 |
| 可信度 | 本机验证 |
| 版本时间戳 | 2026-11-04，torch 2.9.1+cu126 |
| 关联坑 | 第 1 篇 nvidia-smi 的 CUDA 版本 |
专栏导航
| 篇次 | 主题 | 状态 |
|---|---|---|
| 1 | nvidia-smi 显示的 CUDA 版本到底是不是你装的那个 | ✅ |
| 2 | torch.cuda.is_available() 一直是 False，一条命令定位断点 | ✅（本篇） |
| 3 | 标签和图像没对齐，模型一直在学噪声 | 排期中 |
| 4 | loss 变 NaN，用 hook 逐层定位 | 排期中 |
| 5 | DataLoader 卡死在第一个 batch，Windows 多进程的坑 | 排期中 |
| 6 | 装了两套 CUDA 还在串，PATH 与优先级的真相 | 排期中 |
| 7 | 数据泄漏：预处理做在了划分之前 | 排期中 |
| 8 | RAG 答一半开始编，检索阈值与拒答机制实操 | 排期中 |
| 9 | 随机种子都设了，结果还是不可复现 | 排期中 |
| 10 | 相似度全是 0.9：向量没归一化 | 排期中 |
| 11 | 开了混合精度就 NaN，GradScaler 到底在做什么 | 排期中 |
| 12 | loss 不降反升，先别怀疑模型结构 | 排期中 |
| 13 | 训练降验证不降：先查数据再谈正则 | 排期中 |
说明：no kernel image（需新架构显卡）、WSL2 装驱动、docker --gpus 三题本机暂不支持真实复现，按「跑不出来就换题」原则暂缓，后续具备条件再补番外篇。第二季余下选题（top-k 拐点、Tokenizer 截断、ONNX 对不上等）陆续更新。
说明：no kernel image（需新架构显卡）、WSL2 装驱动、docker --gpus 三题本机暂不支持真实复现，按「跑不出来就换题」原则暂缓，后续具备条件再补番外篇。
下一篇预告，《标签和图像没对齐，模型一直在学噪声》。代码一行没写错，模型就是学不会？可能它从头到尾在背错误答案。真机实测给你看错位 10% 会发生什么。
版权说明，本文输出与截图均来自本人真机复现，读者可学习使用，禁止转售或整篇搬运。
