Windows 多版本 CUDA + cuDNN 环境配置完全指南
适用平台:Windows 11 Pro · GPU:RTX 3090 · Visual Studio 2022 关键词:CUDA 多版本共存、cuDNN 配置、环境变量、Switch-CUDA、编译环境切换
Windows 系统环境变量深度分析:原理、用户变量与系统变量及优先级机制
Windows 多 Git 环境冲突:一个环境变量优先级引发的血案
一、背景与目标
在 Windows 上进行深度学习项目编译时,不同框架对 CUDA 版本的要求往往不同:
- vLLM 0.16 推荐 CUDA 12.8 + cuDNN 9.8
- PyTorch3D 常用 CUDA 12.6
- TensorRT 10.x 支持 CUDA 13.x
- 新兴框架逐渐迁移到 CUDA 13.0 / 13.1
因此,一台开发机上同时安装多个 CUDA 版本是常态(主要解决跨大版本编译难题)。本文以实机环境为例,详细说明:
二、实机环境说明
| 操作系统 | Windows 11 Pro for Workstations |
| GPU | NVIDIA RTX 3090(sm_86) |
| 驱动版本 | 595.02 |
| Python | 3.12.11(EPGF 架构 管理) |
| PyTorch | 2.7.1+cu126 |
| Visual Studio | 2022 Professional v17.12.17 |
| PowerShell | 7.6.0-rc.1 / 7.5.4 / 5.1(多种终端并用) |

三、已安装的 CUDA 版本
CUDA Toolkit – Free Tools and Training | NVIDIA Developer
CUDA Toolkit Archive
本机同时安装了以下五个 CUDA Toolkit 版本:
| v12.6 | V12.6.85 | C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.6 |
| v12.8 | V12.8.93 | C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8 |
| v12.9 | V12.9.41 | C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.9 |
| v13.0 | V13.0.88 | C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.0 |
| v13.1(默认) | V13.1.80 | C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1 |

验证所有版本的 nvcc 是否正常:
@("v12.6","v12.8","v12.9","v13.0","v13.1") | ForEach-Object {
$nvcc = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\$_\\bin\\nvcc.exe"
if (Test-Path $nvcc) {
$out = & $nvcc –version 2>&1 | Select-String "release"
Write-Host "✅ CUDA $_ : $out" -ForegroundColor Green
} else {
Write-Host "❌ CUDA $_ : nvcc 不存在" -ForegroundColor Red
}
}
四、已安装的 cuDNN 版本
CUDA Deep Neural Network (cuDNN) | NVIDIA Developer
cuDNN Archive
4.1 安装方式说明
cuDNN 有两种安装方式,本机两种均有使用:
| 内嵌式(旧) | dll 直接放在 CUDA\\vxx\\bin\\ 目录下 | cuDNN 8.x 及以前 |
| 独立安装(新) | 单独目录,按 CUDA 版本分子文件夹 | cuDNN 9.x 及以后 |
独立安装的 cuDNN 目录结构如下:
C:\\Program Files\\NVIDIA\\CUDNN\\
├── v9.8\\
│ ├── bin\\
│ │ ├── 11.8\\ ← 8个dll
│ │ └── 12.8\\ ← 8个dll
│ └── include\\
│ ├── 11.8\\ ← 7个.h
│ └── 12.8\\ ← 7个.h
├── v9.9\\
│ ├── bin\\
│ │ ├── 11.8\\ ← 8个dll
│ │ └── 12.9\\ ← 8个dll
│ └── include\\
│ ├── 11.8\\ ← 7个.h
│ └── 12.9\\ ← 7个.h
├── v9.14\\
│ ├── bin\\
│ │ ├── 12.9\\ ← 8个dll
│ │ └── 13.0\\ ← 8个dll ✅ CUDA 13.0 官方对应版本
│ └── include\\
│ ├── 12.9\\ ← 7个.h
│ └── 13.0\\ ← 7个.h
└── v9.17\\
├── bin\\
│ ├── 12.9\\ ← 8个dll
│ └── 13.1\\ ← 8个dll
└── include\\
├── 12.9\\ ← 7个.h
└── 13.1\\ ← 7个.h
4.2 cuDNN 与 CUDA 对应关系
| v12.6 | 8.9.7(内嵌) | …\\CUDA\\v12.6\\bin\\ | …\\CUDA\\v12.6\\include\\ |
| v12.8 | v9.8 | …\\CUDNN\\v9.8\\bin\\12.8\\ | …\\CUDNN\\v9.8\\include\\12.8\\ |
| v12.9 | v9.17 | …\\CUDNN\\v9.17\\bin\\12.9\\ | …\\CUDNN\\v9.17\\include\\12.9\\ |
| v13.0 | v9.14 | …\\CUDNN\\v9.14\\bin\\13.0\\ | …\\CUDNN\\v9.14\\include\\13.0\\ |
| v13.1 | v9.17 | …\\CUDNN\\v9.17\\bin\\13.1\\ | …\\CUDNN\\v9.17\\include\\13.1\\ |
💡 每个 CUDA 版本安装时同步安装了对应的 cuDNN,系统中积累了 v9.8 / v9.9 / v9.11 / v9.14 / v9.17 五个独立版本。Switch-CUDA 脚本按上表为每个版本选择 bin 和 include 均完整的最匹配 cuDNN,避免跨版本编译问题。

五、NVIDIA 相关环境变量详解
5.1 系统变量(Machine 级别)
| CUDA_PATH | …\\CUDA\\v13.1 | CMake 默认查找的 CUDA 路径,应与 PATH 中优先的 nvcc 版本一致 |
| CUDA_PATH_V12_6 | …\\CUDA\\v12.6 | 各版本的具名路径变量,由安装程序自动创建 |
| CUDA_PATH_V12_8 | …\\CUDA\\v12.8 | 同上,供脚本或 CMake 按名字精确引用 |
| CUDA_PATH_V12_9 | …\\CUDA\\v12.9 | 同上 |
| CUDA_PATH_V13_0 | …\\CUDA\\v13.0 | 同上 |
| CUDA_PATH_V13_1 | …\\CUDA\\v13.1 | 同上 |
| CUDA_VISIBLE_DEVICES | GPU-5d5b1da4-… | 限制程序可见的 GPU,可用 UUID 或数字索引(0,1,2) |
| CUTENSOR_ROOT | …\\cuTENSOR\\v2.4 | cuTENSOR 库根目录,供 CMake 查找 |
| TENSORRT_PATH | C:\\TensorRT-10.13.3.9 | TensorRT 安装根目录,必须是完整路径 |

5.2 CUDA_PATH 与 PATH 的关系
这两者作用不同,容易混淆:
| 作用 | 告诉 CMake/编译工具 CUDA 在哪里 | 让命令行能直接输入 nvcc 命令 |
| 格式 | 单个目录路径 | 多个 \\bin 路径,分号分隔 |
| 优先级 | 唯一值,CMake 优先读取 | 第一条优先,决定默认 nvcc 版本 |
| 修改方式 | 直接改变量值 | 调整条目顺序或用脚本临时覆盖 |

⚠️ 重要原则:CUDA_PATH 的版本应与 PATH 中第一个 nvcc 版本保持一致,否则 CMake 自动检测时可能使用错误的 CUDA 版本。
本机配置:CUDA_PATH → v13.1,PATH 中 v13.1\\bin 排第一 ✅
5.3 PATH 中的 CUDA 条目配置——使用变量引用节省字符
Windows PATH 长度上限为 32767 字符,但实际建议控制在 4096 以内。CUDA 路径较长,全部写完整路径会占用大量字符。
正确做法:在注册表中使用 %VAR% 变量引用形式,Windows 在合并展开 PATH 时会自动替换,实测有效。
系统 PATH(Machine)只放默认版本,NVIDIA 相关条目:
%CUDA_PATH%\\bin ← 展开为 v13.1\\bin,默认nvcc
C:\\Program Files\\NVIDIA Corporation\\NVIDIA App\\NvDLISR
C:\\Program Files (x86)\\NVIDIA Corporation\\PhysX\\Common
%CUTENSOR_ROOT%\\bin\\12 ← 展开为 cuTENSOR\\v2.4\\bin\\12
%CUTENSOR_ROOT%\\bin\\13
%CUTENSOR_ROOT%\\lib\\12
%CUTENSOR_ROOT%\\lib\\13
C:\\Program Files\\NVIDIA Corporation\\Nsight Compute 2024.3.2\\
请谨慎使用此类代码。


用户 PATH(User)放其余版本(优先级低于系统 PATH):
%CUDA_PATH_V12_6%\\bin
%CUDA_PATH_V12_8%\\bin
%CUDA_PATH_V12_9%\\bin
%CUDA_PATH_V13_0%\\bin
%CUDA_PATH_V13_1%\\bin
请谨慎使用此类代码。

这样 where.exe nvcc 的输出为(变量已正确展开):
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1\\bin\\nvcc.exe ← 默认
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.6\\bin\\nvcc.exe
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8\\bin\\nvcc.exe
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.9\\bin\\nvcc.exe
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.0\\bin\\nvcc.exe

节省字符效果(实测):
| 系统 PATH | 1602 | 1469 | 133 字符 |
| 用户 PATH | 703 | 547 | 156 字符 |
| 合计 | 2305 | 2016 | 289 字符 |
5.4 两个关键陷阱
陷阱一:必须直写注册表才能保留 %VAR% 引用
⚠️ 使用 [Environment]::SetEnvironmentVariable() 写入时会自动展开变量为完整路径,导致引用失效。必须用 Set-ItemProperty 直写注册表。
# ❌ 错误方式:会自动展开 %VAR%,写入后变成完整路径
[Environment]::SetEnvironmentVariable("PATH", $newPath, "Machine")
# ✅ 正确方式:直写注册表,%VAR% 引用原样保留
$regSys = "HKLM:\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"
$regUser = "HKCU:\\Environment"
Set-ItemProperty -Path $regSys -Name "Path" -Value $newSys # 需要管理员权限
Set-ItemProperty -Path $regUser -Name "Path" -Value $newUser
请谨慎使用此类代码。
陷阱二:PowerShell 不自动展开 PATH 中的 %VAR%
cmd 在进程启动时会自动展开 PATH 中的 %VAR% 引用,但 PowerShell 不会。如果 PATH 里有 %CUDA_PATH%\\bin 这样的条目,在 PowerShell 中 where.exe nvcc 会找不到任何结果。
解决方法是在 PowerShell Profile 中加入一行展开语句,让每次启动时自动处理:
# 找到 Profile 路径
$PROFILE # PS7: ~\\Documents\\PowerShell\\Microsoft.PowerShell_profile.ps1
# PS5: ~\\Documents\\WindowsPowerShell\\Microsoft.PowerShell_profile.ps1
# 写入展开语句(两个 Profile 都需要)
$line = '$env:PATH = [System.Environment]::ExpandEnvironmentVariables($env:PATH)'
Add-Content $PROFILE $line
请谨慎使用此类代码。
加入后新开终端即可正常使用 where.exe nvcc。
5.5 一键替换脚本(需管理员终端)
$regSys = "HKLM:\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"
$regUser = "HKCU:\\Environment"
$rawSys = (Get-ItemProperty $regSys).Path
$rawUser = (Get-ItemProperty $regUser).Path
# 定义替换规则(完整路径 → 变量引用)
$replacements = @(
# 系统PATH
@{ From = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1\\bin"; To = "%CUDA_PATH%\\bin" },
@{ From = "C:\\Program Files\\NVIDIA cuTENSOR\\v2.4\\bin\\12"; To = "%CUTENSOR_ROOT%\\bin\\12" },
@{ From = "C:\\Program Files\\NVIDIA cuTENSOR\\v2.4\\bin\\13"; To = "%CUTENSOR_ROOT%\\bin\\13" },
@{ From = "C:\\Program Files\\NVIDIA cuTENSOR\\v2.4\\lib\\12"; To = "%CUTENSOR_ROOT%\\lib\\12" },
@{ From = "C:\\Program Files\\NVIDIA cuTENSOR\\v2.4\\lib\\13"; To = "%CUTENSOR_ROOT%\\lib\\13" },
# 用户PATH
@{ From = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.6\\bin"; To = "%CUDA_PATH_V12_6%\\bin" },
@{ From = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8\\bin"; To = "%CUDA_PATH_V12_8%\\bin" },
@{ From = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.9\\bin"; To = "%CUDA_PATH_V12_9%\\bin" },
@{ From = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.0\\bin"; To = "%CUDA_PATH_V13_0%\\bin" },
@{ From = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1\\bin"; To = "%CUDA_PATH_V13_1%\\bin" }
)
$newSys = $rawSys
$newUser = $rawUser
foreach ($r in $replacements) {
$newSys = $newSys -replace [regex]::Escape($r.From), $r.To
$newUser = $newUser -replace [regex]::Escape($r.From), $r.To
}
# 写入注册表(保留 %VAR% 引用)
Set-ItemProperty -Path $regSys -Name "Path" -Value $newSys
Set-ItemProperty -Path $regUser -Name "Path" -Value $newUser
Write-Host "✅ 完成,系统PATH: $($rawSys.Length) → $($newSys.Length),用户PATH: $($rawUser.Length) → $($newUser.Length)" -ForegroundColor Green
请谨慎使用此类代码。

六、编译时切换 CUDA 版本
6.1 Switch-CUDA 脚本
将以下脚本保存为 D:\\Program\\switch-cuda.ps1,支持 PowerShell 5/7 及 VS 2022 Developer Shell:
function Switch-CUDA {
param(
[Parameter(Mandatory)]
[ValidateSet("12.6","12.8","12.9","13.0","13.1")]
[string]$Ver
)
$cudaBase = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v$Ver"
$cudnnBase = "C:\\Program Files\\NVIDIA\\CUDNN"
# 设置 CUDA 相关环境变量(仅当前终端会话有效)
$env:CUDA_HOME = $cudaBase
$env:CUDA_PATH = $cudaBase
$env:CUDA_ROOT = $cudaBase
$env:CudaToolkitDir = "$cudaBase\\"
# 根据 CUDA 版本选择对应的 cuDNN bin 路径
$cudnnPath = switch ($Ver) {
"12.6" { "$cudaBase\\bin" } # 内嵌 cuDNN 8.x
"12.8" { "$cudnnBase\\v9.8\\bin\\12.8" }
"12.9" { "$cudnnBase\\v9.17\\bin\\12.9" }
"13.0" { "$cudnnBase\\v9.14\\bin\\13.0" } # cuDNN v9.14 官方对应版本
"13.1" { "$cudnnBase\\v9.17\\bin\\13.1" }
}
$env:CUDNN_PATH = $cudnnPath
# 更新 PATH:将目标版本 bin 提到最前面,移除其他 CUDA/cuDNN 条目
$cudaBin = "$cudaBase\\bin"
$cleanPath = ($env:PATH -split ";") | Where-Object {
$_ -notmatch "NVIDIA GPU Computing Toolkit\\\\CUDA\\\\v\\d+\\.\\d+\\\\bin" -and
$_ -notmatch "NVIDIA\\\\CUDNN\\\\v\\d+\\.\\d+\\\\bin"
}
$env:PATH = "$cudaBin;$cudnnPath;" + ($cleanPath -join ";")
Write-Host "✅ 已切换到 CUDA $Ver" -ForegroundColor Green
Write-Host " CUDA : $cudaBase" -ForegroundColor Gray
Write-Host " cuDNN : $cudnnPath" -ForegroundColor Gray
nvcc –version | Select-String "release"
}
Write-Host "✅ Switch-CUDA 已加载,用法: Switch-CUDA 12.8" -ForegroundColor Cyan
请谨慎使用此类代码。

注意:请把脚本文件保存为 UTF-8 with BOM 格式,PowerShell 5.1 看到 BOM 标记后会正确识别 UTF-8。
如遇因 .ps1 脚本保存的编码问题导致的脚本报错,请运行以下重新保存为正确兼容编码方式的命令:
# 读取现有脚本内容,重新以 UTF-8 BOM 格式保存
$content = Get-Content "D:\\Program\\switch-cuda.ps1" -Raw -Encoding UTF8
$utf8Bom = New-Object System.Text.UTF8Encoding $true
[System.IO.File]::WriteAllText("D:\\Program\\switch-cuda.ps1", $content, $utf8Bom)
Write-Host "✅ 已重新保存为 UTF-8 BOM 格式"
请谨慎使用此类代码。

保存后,如在 Windows PowerShell 5.1 里重新加载:
. "D:\\Program\\switch-cuda.ps1"
Switch-CUDA 12.8
6.2 使用方法
每次打开新终端,编译前执行两步:
# 第一步:加载函数(每次新终端都需要执行一次)
. "D:\\Program\\switch-cuda.ps1"
# 第二步:切换到目标版本
Switch-CUDA 12.8 # 切换到 CUDA 12.8 + cuDNN 9.8
Switch-CUDA 13.1 # 切换到 CUDA 13.1 + cuDNN 9.17
切换后输出示例:
✅ 已切换到 CUDA 12.8
CUDA : C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8
cuDNN : C:\\Program Files\\NVIDIA\\CUDNN\\v9.8\\bin\\12.8
release 12.8, V12.8.93
运行 .ps1 脚本可以在不同的终端中实现切换和版本切换调用:



6.3 注意事项
- Switch-CUDA 只修改当前终端会话的环境变量,不影响注册表,关闭终端后自动恢复
- VS 2022 Developer Shell 同样支持,加载方式完全一致
- CMake 编译时建议同时通过 -DCUDA_TOOLKIT_ROOT_DIR 显式指定,避免读错 CUDA_PATH
- vLLM 等项目还需额外设置 TORCH_CUDA_ARCH_LIST=8.6(RTX 3090)和 MAX_JOBS 等变量
七、手动修改 CUDA_PATH 切换默认版本
除了脚本切换外,还可以通过永久修改 CUDA_PATH 系统变量,改变 CMake 的默认行为。

7.1 PowerShell 修改(需管理员权限)
# 永久修改系统变量 CUDA_PATH(影响所有新终端和 CMake)
# 修改为 v12.8
[Environment]::SetEnvironmentVariable(
"CUDA_PATH",
"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8",
"Machine"
)
# 验证
[Environment]::GetEnvironmentVariable("CUDA_PATH", "Machine")
请谨慎使用此类代码。
7.2 图形界面修改
系统属性 → 高级 → 环境变量 → 系统变量 → 找到 CUDA_PATH → 编辑,将值改为目标版本路径。
7.3 快速恢复默认(v13.1)
[Environment]::SetEnvironmentVariable(
"CUDA_PATH",
"C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1",
"Machine"
)
⚠️ 修改 CUDA_PATH 后,同步调整系统 PATH 中的 CUDA bin 顺序,确保两者版本一致。修改注册表后需要重新打开终端才能生效。
八、完整验证脚本
每次配置完成后,运行以下脚本一次性验证所有 CUDA/cuDNN 版本是否正常。
💡 建议将脚本保存为文件再运行,避免 PowerShell 交互模式下 if/else 分行的限制:
# 保存为 D:\\Program\\verify-cuda.ps1 后执行:
& "D:\\Program\\verify-cuda.ps1"
$cudaRoot = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA"
$cudnnRoot = "C:\\Program Files\\NVIDIA\\CUDNN"
# ===== 1. CUDA 版本验证 =====
Write-Host "===== CUDA 版本验证 =====" -ForegroundColor Cyan
@("v12.6","v12.8","v12.9","v13.0","v13.1") | ForEach-Object {
$nvcc = "$cudaRoot\\$_\\bin\\nvcc.exe"
if (Test-Path $nvcc) {
$out = & $nvcc –version 2>&1 | Select-String "release"
Write-Host " ✅ CUDA $_ : $out" -ForegroundColor Green
} else {
Write-Host " ❌ CUDA $_ : nvcc 不存在" -ForegroundColor Red
}
}
# ===== 2. cuDNN 完整性验证(bin + include 均存在才算完整)=====
Write-Host ""
Write-Host "===== cuDNN 完整性验证 =====" -ForegroundColor Cyan
# 内嵌式(v12.6)
$binOk = Test-Path "$cudaRoot\\v12.6\\bin\\cudnn64_8.dll"
$incOk = Test-Path "$cudaRoot\\v12.6\\include\\cudnn.h"
if ($binOk -and $incOk) { Write-Host "✅ cuDNN 8.x (v12.6 内嵌) : bin + include 完整" -ForegroundColor Green }
else { Write-Host "❌ cuDNN 8.x (v12.6 内嵌) : 不完整" -ForegroundColor Red }
# 独立安装:按 CUDA 版本对应关系检查
$cudnnMap = @{ "12.8" = "v9.8"; "12.9" = "v9.17"; "13.0" = "v9.14"; "13.1" = "v9.17" }
foreach ($cuda in @("12.8","12.9","13.0","13.1")) {
$cudnn = $cudnnMap[$cuda]
$binOk = Test-Path "$cudnnRoot\\$cudnn\\bin\\$cuda"
$incOk = Test-Path "$cudnnRoot\\$cudnn\\include\\$cuda"
$dllCount = (Get-ChildItem "$cudnnRoot\\$cudnn\\bin\\$cuda" -Filter "cudnn*.dll" -ErrorAction SilentlyContinue).Count
if ($binOk -and $incOk) {
Write-Host " ✅ CUDA $cuda → cuDNN $cudnn : bin($dllCount dll) + include 完整" -ForegroundColor Green
} else {
$msg = ""
if (-not $binOk) { $msg += "bin缺失 " }
if (-not $incOk) { $msg += "include缺失" }
Write-Host " ❌ CUDA $cuda → cuDNN $cudnn : $msg" -ForegroundColor Red
}
}
# ===== 3. 异常检测:bin有但include缺失 =====
Write-Host ""
Write-Host "===== 异常检测 =====" -ForegroundColor Cyan
$found = $false
Get-ChildItem $cudnnRoot -Directory | ForEach-Object {
$cudnnVer = $_.Name
Get-ChildItem "$cudnnRoot\\$cudnnVer\\bin" -Directory -ErrorAction SilentlyContinue | ForEach-Object {
$cudaVer = $_.Name
$binOk = Test-Path "$cudnnRoot\\$cudnnVer\\bin\\$cudaVer"
$incOk = Test-Path "$cudnnRoot\\$cudnnVer\\include\\$cudaVer"
if ($binOk -and -not $incOk) {
Write-Host " ⚠️ cuDNN $cudnnVer\\bin\\$cudaVer 存在,但 include\\$cudaVer 缺失" -ForegroundColor Yellow
$found = $true
}
}
}
if (-not $found) { Write-Host " ✅ 无异常" -ForegroundColor Green }
# ===== 4. 关键变量 =====
Write-Host ""
Write-Host "===== 关键环境变量 =====" -ForegroundColor Cyan
Write-Host " CUDA_PATH = $([Environment]::GetEnvironmentVariable('CUDA_PATH','Machine'))"
# ===== 5. PATH 中的 nvcc 顺序 =====
Write-Host ""
Write-Host "===== PATH 中的 nvcc 顺序 =====" -ForegroundColor Cyan
where.exe nvcc
预期输出:
===== CUDA 版本验证 =====
✅ CUDA v12.6 : Cuda compilation tools, release 12.6, V12.6.85
✅ CUDA v12.8 : Cuda compilation tools, release 12.8, V12.8.93
✅ CUDA v12.9 : Cuda compilation tools, release 12.9, V12.9.41
✅ CUDA v13.0 : Cuda compilation tools, release 13.0, V13.0.88
✅ CUDA v13.1 : Cuda compilation tools, release 13.1, V13.1.80
===== cuDNN 完整性验证 =====
✅ cuDNN 8.x (v12.6 内嵌) : bin + include 完整
✅ CUDA 12.8 → cuDNN v9.8 : bin(8 dll) + include 完整
✅ CUDA 12.9 → cuDNN v9.17 : bin(8 dll) + include 完整
✅ CUDA 13.0 → cuDNN v9.14 : bin(8 dll) + include 完整
✅ CUDA 13.1 → cuDNN v9.17 : bin(8 dll) + include 完整
===== 异常检测 =====
✅ 无异常
===== 关键环境变量 =====
CUDA_PATH = C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1
===== PATH 中的 nvcc 顺序 =====
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.1\\bin\\nvcc.exe
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.6\\bin\\nvcc.exe
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8\\bin\\nvcc.exe
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.9\\bin\\nvcc.exe
C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v13.0\\bin\\nvcc.exe

九、常见问题
Q:CMake 找到了错误的 CUDA 版本?
检查 CUDA_PATH 是否与 PATH 中第一个 nvcc 一致。或在 CMake 命令中显式指定:
cmake .. -DCUDA_TOOLKIT_ROOT_DIR="C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8"
Q:Switch-CUDA 切换后重新打开终端失效?
正常现象,脚本只修改当前会话。每次新终端需重新执行 . "D:\\Program\\switch-cuda.ps1"。
Q:编译报错找不到 cudnn.h?
检查 CUDNN_PATH 是否正确。部分项目还需额外设置:
$env:CUDNN_INCLUDE_DIR = "C:\\Program Files\\NVIDIA\\CUDNN\\v9.8\\include\\12.8"
$env:CUDNN_LIBRARY = "C:\\Program Files\\NVIDIA\\CUDNN\\v9.8\\lib\\12.8\\cudnn.lib"
Q:where.exe nvcc 只显示一个版本?
检查其他版本的 bin 路径是否已加入用户 PATH,需要重新打开终端后再验证。
Q:CUDA_PATH 改了但 CMake 还用旧版本?
需要重新打开终端,或在当前终端手动执行:
$env:CUDA_PATH = "C:\\Program Files\\NVIDIA GPU Computing Toolkit\\CUDA\\v12.8"
十、总结
| CUDA_PATH | 与 PATH 中第一个 nvcc 版本保持一致(本机:v13.1) |
| CUDA_PATH_Vxx_x | 由安装程序自动管理,无需手动维护 |
| 系统 PATH | 只放默认 CUDA 版本的 bin 路径 |
| 用户 PATH | 放其余版本的 bin 路径(优先级低,作为备用) |
| cuDNN | 按 CUDA 版本对应,路径在 Switch-CUDA 脚本中统一管理 |
| Switch-CUDA 脚本 | 保存在固定路径,编译前一键加载切换 |
用法速查:
. "D:\\Program\\switch-cuda.ps1" # 加载函数
Switch-CUDA 12.8 # 切换到 CUDA 12.8 编译环境
Switch-CUDA 13.1 # 切换回默认环境
本文基于实际编译 vLLM 0.16 Windows 版本的过程整理,相关编译过程请参考:Windows 11 源码编译 vLLM 0.16 完全指南
官方文档类:
- CUDA 下载:https://developer.nvidia.com/cuda-downloads
- cuDNN 下载:https://developer.nvidia.com/cudnn-downloads
- CUDA 与 cuDNN 兼容性表:https://docs.nvidia.com/deeplearning/cudnn/latest/reference/support-matrix.html
- CUDA Release Notes:https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/


