Windows 11 源码编译 vLLM 0.16 完全指南（CUDA 12.6 / PyTorch 2.7.1+cu126）

Windows 11 源码编译 vLLM 0.16 完全指南（CUDA 12.6 / PyTorch 2.7.1+cu126）【再次实战检验】

本文是上篇 vLLM Windows cu128 编译指南的复盘版本。上篇使用 CUDA 12.8 编译，本篇使用 CUDA 12.6 重新编译，与 PyTorch 2.7.1+cu126 完全匹配。同时修正了上篇中 subst 映射用途的描述，并给出更清晰的一键恢复脚本。
Windows 多版本 CUDA + cuDNN 环境配置完全指南
 Windows 本地编译 CUDA Extension Wheel 完全指南
 Windows 11 源码编译 vLLM 0.16 完全指南（RTX 3090 / CUDA 12.8 / PyTorch 2.7.1）

环境信息

项目	版本
操作系统	Windows 11
GPU	NVIDIA GeForce RTX 3090 (sm_86)
驱动	595.02
CUDA Toolkit	12.6（编译用）
Python	3.12.11
PyTorch	2.7.1+cu126
Visual Studio	2022 Professional v17.12.17
vLLM 分支	SystemPanic/vllm-windows（vllm-for-windows 分支）
编译产物版本	0.16.0rc2.dev243+gc8e1f5abe.d20260309.cu126

一、为什么要重新编译 cu126 版本？

Windows 11 源码编译 vLLM 0.16 完全指南（RTX 3090 / CUDA 12.8 / PyTorch 2.7.1）

上篇用系统上的 CUDA 12.8 编译，但实际虚拟环境中使用的 PyTorch 是 2.7.1+cu126，即 torch 内部绑定的是 CUDA 12.6 的运行时。虽然 cu128 wheel 在多数场景下也能向前兼容运行，但为了避免潜在的版本不匹配问题，用与 torch 完全一致的 CUDA 版本重新编译更为稳妥。

Windows 多版本 CUDA + cuDNN 环境配置完全指南

复制代码

# 快捷切换CUDA+cuDNN编译链
# 启动脚本
. "D:\Program\switch-cuda.ps1"
# 切换到 CUDA 12.6
Switch-CUDA 12.6

验证当前 torch 的 CUDA 版本：

复制代码

python -c "import torch; print(torch.__version__, '| CUDA:', torch.version.cuda)"
# 输出：2.7.1+cu126 | CUDA: 12.6

二、关键概念：subst 映射的正确用途

这是本次编译最容易出错的地方，必须先理解清楚。

CUDA 默认安装在 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6，路径含空格。MSVC 的 cl.exe 在处理 -I 参数时不会自动加引号，空格会导致路径被截断，出现编译错误。

解决方案：用 subst 把 CUDA 目录映射到无空格的盘符。

复制代码

Z:  →  C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6

⚠️ Z: 映射的是 CUDA 目录，不是 vLLM 源码目录。 这两者不能混淆。vLLM 源码始终在 J:\PythonProjects4\vllm-windows，编译命令里也用完整的 J: 路径指定源码位置。

映射命令：

复制代码

# 映射：Z: → CUDA 12.6 目录（让torch找到正确版本的nvcc）
subst Z: "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6"

# 验证映射
subst | findstr Z

如需取消映射：

复制代码

 # 取消当前Z:映射
subst Z: /D

三、编译前准备

3.1 确认环境

在 VS 2022 Developer Command Prompt（x64） 中操作，确认以下工具可用：

复制代码

cl        # 输出：用于 x64 的 Microsoft (R) C/C++ 优化编译器 19.42.xxxxx 版
python --version  # Python 3.12.11

激活 vLLM 专用 venv：

复制代码

cd J:\PythonProjects4\vllm-windows
.\.venv\Scripts\Activate.ps1
python -c "import torch; print(torch.__version__, torch.version.cuda)"
# 确认输出：2.7.1+cu126  12.6

3.2 清理 CMake 缓存（重要）

如果之前有过失败的编译尝试，必须先清理缓存，否则旧的 CMake 变量会干扰新的编译：

复制代码

Remove-Item -Recurse -Force "J:\PythonProjects4\vllm-windows\build" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "J:\PythonProjects4\vllm-windows\.deps" -ErrorAction SilentlyContinue

💡 .deps 目录包含 CMake 自动下载的 CUTLASS、triton-windows、FlashMLA 等外部依赖，清理后编译时会重新下载，需要网络连接。

四、设置编译环境

以下所有命令在同一个终端会话中顺序执行：

复制代码

# 1. 映射 CUDA 12.6 到 Z: 盘（解决路径含空格问题）
subst Z: "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6"

# 验证映射正确
dir Z:\bin\nvcc.exe   # 必须能找到

# 2. 设置 CUDA 路径变量（全部指向 Z:）
$env:CUDA_HOME      = "Z:"
$env:CUDA_PATH      = "Z:"
$env:CUDA_ROOT      = "Z:"
$env:CudaToolkitDir = "Z:\"
$env:PATH           = "Z:\bin;" + $env:PATH

# 验证：第一行必须是 Z:\bin\nvcc.exe
where.exe nvcc

# 3. 设置编译参数
$env:DISTUTILS_USE_SDK    = "1"
$env:VLLM_TARGET_DEVICE   = "cuda"
$env:MAX_JOBS             = "10"       # 根据 CPU 核心数调整
$env:TORCH_CUDA_ARCH_LIST = "8.6"     # RTX 3090 对应 sm_86
$env:USE_LIBUV            = "0"

⚠️ where.exe nvcc 的第一行必须是 Z:\bin\nvcc.exe ，而不是 C:\Program Files\...。如果不是，说明 PATH 设置有问题，检查 $env:PATH 开头是否有 Z:\bin。

五、执行编译

复制代码

pip wheel J:\PythonProjects4\vllm-windows `
    --no-build-isolation `
    --no-deps `
    -w J:\PythonProjects4\vllm-windows\wheels\ `
    2>&1 | Tee-Object -FilePath "J:\PythonProjects4\vllm-windows\wheels\build-cu126.log"

编译过程说明：

CMake 配置阶段（约 5-10 分钟）：自动下载 CUTLASS、FlashMLA、triton-windows 等外部依赖
ninja 编译阶段（约 60-90 分钟）：共 145 个编译目标

以下跳过信息是正常的，不是错误：

复制代码

-- FlashMLA will not compile: unsupported CUDA architecture 8.6    （需要 sm_90）
-- [QUTLASS] Skipping build: CUDA 12.8 or newer is required        （cu126 不支持）
-- Not building scaled_mm_c3x_sm90                                  （需要 sm_90）
-- Not building NVFP4                                               （需要 sm_100）

以下警告也可忽略：

复制代码

CMake Warning: Pytorch version 2.10.0 expected for CUDA build, saw 2.7.1 instead.

编译成功标志：

复制代码

[145/145] Linking CXX shared module vllm-flash-attn\_vllm_fa2_C.pyd
Successfully built vllm

六、验证 wheel

复制代码

cd J:\PythonProjects4\vllm-windows
Get-ChildItem "J:\PythonProjects4\vllm-windows\wheels\" | Select-Object Name, LastWriteTime, Length

应看到类似：

复制代码

vllm-0.16.0rc2.dev243+gc8e1f5abe.d20260309.cu126-cp312-cp312-win_amd64.whl   269MB

文件名结构：

cu126 --- 与 PyTorch 2.7.1+cu126 匹配 ✅
cp312 --- Python 3.12
d20260309 --- 编译日期

七、安装与验证

7.1 在 vLLM venv 中验证

复制代码

python -c "
import os
os.environ['USE_LIBUV'] = '0'
import vllm._C as _C
print('✅ _C 扩展加载成功')
from vllm import LLM, SamplingParams
import vllm
print('✅ vllm 导入成功，版本:', vllm.__version__)
"

7.2 安装到其他环境（如 ComfyUI）

复制代码

pip install vllm-0.16.0rc2.dev243+gc8e1f5abe.d20260309.cu126-cp312-cp312-win_amd64.whl --no-deps
pip install llguidance xgrammar

⚠️ USE_LIBUV=0 必须在 import vllm 之前设置，否则 PyTorch 2.7.1 stable 会报错：
复制代码
import os
os.environ['USE_LIBUV'] = '0'
import vllm

八、一键恢复脚本

下次需要重新编译时，在 VS 2022 Developer Shell 中执行：

复制代码

cd J:\PythonProjects4\vllm-windows
.\.venv\Scripts\Activate.ps1

# 清理旧缓存（如需要）
# Remove-Item -Recurse -Force build, .deps

# 映射 CUDA 路径（Z: → CUDA 12.6，每次重启后需重新执行）
subst Z: "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.6"

# 设置环境变量
$env:CUDA_HOME      = "Z:"
$env:CUDA_PATH      = "Z:"
$env:CUDA_ROOT      = "Z:"
$env:CudaToolkitDir = "Z:\"
$env:PATH           = "Z:\bin;" + $env:PATH
$env:DISTUTILS_USE_SDK    = "1"
$env:VLLM_TARGET_DEVICE   = "cuda"
$env:MAX_JOBS             = "10"
$env:TORCH_CUDA_ARCH_LIST = "8.6"
$env:USE_LIBUV            = "0"

# 确认 nvcc 第一行是 Z:\bin\nvcc.exe
where.exe nvcc

# 编译
pip wheel J:\PythonProjects4\vllm-windows `
    --no-build-isolation --no-deps `
    -w J:\PythonProjects4\vllm-windows\wheels\

保存所有编译依赖的 wheel 到指定目录：

假设保存到：

J:\PythonProjects4\vllm-windows

则保存 wheel 命令为：

复制代码

# 打包成 wheel 文件
pip wheel . --no-build-isolation -w J:\PythonProjects4\vllm-windows\vllmwhl_cu126\

复制代码

# 查看生成的 wheel
Get-ChildItem "J:\PythonProjects4\vllm-windows\vllmwhl_cu126\"

九、与上篇的对比

Windows 11 源码编译 vLLM 0.16 完全指南（RTX 3090 / CUDA 12.8 / PyTorch 2.7.1）

	上篇（cu128）	本篇（cu126）
CUDA 编译版本	12.8	12.6
torch 匹配度	部分匹配	完全匹配 ✅
subst Z: 指向	CUDA 12.8 目录	CUDA 12.6 目录
wheel 大小	269 MB	269 MB
编译日期	20260308	20260309

两个 wheel 可以同时保留，根据目标环境的 torch+cuda 版本选择安装。

Windows 11 源码编译 vLLM 0.16 完全指南（CUDA 12.6 / PyTorch 2.7.1+cu126）