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

系列背景 ：本文是"Windows 本地部署 AI 推理环境"系列的一部分，为的是本地 ComfyUI 环境编译适配的 vLLM 包。前序文章已完成 ComfyUI-3D-Pack 六大依赖的编译，本文记录在同一台机器上从零编译 vLLM Windows 分支的完整过程，包含所有踩坑和解决方案。
ComfyUI-3D-Pack Windows 11 安装完全指南ComfyUI-3D-Pack: Complete Installation Guide for Windows 11

环境信息

项目	版本
操作系统	Windows 11
GPU	NVIDIA GeForce RTX 3090 (sm_86)
驱动	595.02
CUDA Toolkit	12.8（编译用），系统另装有 12.9 / 13.0 / 13.1
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.d20260308

一、为什么不用官方 vLLM？

官方 vLLM 不支持 Windows。PR #14891 曾尝试添加 Windows 支持，但已被关闭，官方团队明确表示暂无计划。

SystemPanic/vllm-windows 是目前最活跃的 Windows 移植分支，维护者持续跟进上游版本，vllm-for-windows 分支对应最新代码。

https://github.com/vllm-project/vllm
https://docs.vllm.ai/en/latest/getting_started/installation/gpu/#create-a-new-python-environment
https://github.com/vllm-project/vllm/issues/669
https://github.com/vllm-project/vllm/pull/14891
https://github.com/SystemPanic/vllm-windows

二、前置准备

2.1 必须安装的工具

Visual Studio 2022（含 C++ 桌面开发工作负载）
CUDA Toolkit 12.8（与 PyTorch 2.7.1+cu126 的内置 nvcc 版本匹配）
Git

2.2 克隆仓库

复制代码

cd J:\PythonProjects4
git clone --single-branch --branch vllm-for-windows https://github.com/SystemPanic/vllm-windows.git
cd vllm-windows

如果是用的 GitHub Desktop:

克隆仓库

选择：For my own purposes

切换分支到：origin/vllm-for-windows

切换后界面如下：

2.3 创建独立虚拟环境

必须为 vLLM 创建独立的 venv，不要复用 ComfyUI 的环境。

复制代码

python -m venv .venv
.\.venv\Scripts\Activate.ps1

用 PyCharm:

2.4 在 VS Developer Shell 中操作

所有编译操作必须在 VS 2022 Developer Command Prompt（x64）中进行，确保 cl.exe 可用：

复制代码

cl
# 输出：用于 x64 的 Microsoft (R) C/C++ 优化编译器 19.42.34444 版

三、安装依赖

3.1 安装 PyTorch

复制代码

pip install torch==2.7.1 torchvision==0.22.1 torchaudio==2.7.1 `
    --index-url https://download.pytorch.org/whl/cu126

验证：

复制代码

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
# 输出：2.7.1+cu126 / True

3.2 移除 requirements 中的 torch 版本锁定

仓库当前代码对应 torch 2.11 nightly，需要先用脚本移除版本约束：

复制代码

python use_existing_torch.py

脚本会输出所有被删除的 torch 相关行，确认 build.txt 中的 torch==2.11.0.dev... 被移除即可。

3.3 安装编译依赖

复制代码

pip install -r requirements/build.txt
pip install -r requirements/windows.txt

⚠️ 注意 ：requirements/windows.txt 中的 xformers==0.0.35.dev1121 会把 torch 降级到 2.10.0，需要立即修复：

复制代码

pip install torch==2.7.1+cu126 torchvision==0.22.1+cu126 torchaudio==2.7.1+cu126 `
    --index-url https://download.pytorch.org/whl/cu126 --force-reinstall

再次验证 torch 版本为 2.7.1+cu126。

3.4 安装运行时依赖

复制代码

pip install -r requirements/cuda.txt

此步骤会下载 flashinfer、ray、cupy 等大量依赖，耗时较长。

四、设置编译环境变量

4.1 关键问题：CUDA 路径含空格

Windows 下 CUDA 默认安装在 C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8，路径含空格。MSVC 的 cl.exe 在处理 -I 参数时不会自动加引号，导致路径被拆分，出现：

复制代码

c1xx: fatal error C1083: "Files/NVIDIA": No such file or directory
c1xx: fatal error C1083: "GPU": No such file or directory

4.2 解决方案：用 subst 映射无空格盘符

复制代码

# 将 CUDA 12.8 映射到 Z: 盘（选一个未使用的盘符）
cmd /c "subst Z: `"C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8`""

# 验证
dir Z:\bin\nvcc.exe

4.3 设置所有环境变量

复制代码

# CUDA 路径（全部使用无空格的 Z: 盘）
$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"              # 根据 CPU 核心数调整
$env:TORCH_CUDA_ARCH_LIST = "8.6" # RTX 3090 对应 sm_86

# 验证 nvcc 优先使用 Z: 盘
where.exe nvcc
# 第一行必须是：Z:\bin\nvcc.exe

五、执行编译

复制代码

python setup.py build_ext --inplace 2>&1 | Tee-Object "build.log"

编译过程说明：

CMake 配置阶段（约 5 分钟）：自动下载 CUTLASS、FlashMLA、triton-windows 等外部依赖
ninja 编译阶段（约 60 分钟）：共 145 个编译目标
大量 C4244/C4267 警告是正常的，是 MSVC 对 PyTorch 头文件的类型转换警告，不是错误

编译目标清单：

目标	说明
`cumem_allocator`	CUDA 显存分配器
`_C`	vLLM 主 CUDA 扩展
`_moe_C`	MoE 扩展
`triton_kernels`	Triton kernel 集合
`_vllm_fa2_C`	Flash Attention 2（含所有 head_dim 变体）

以下功能在 RTX 3090（sm_86）上自动跳过，无需担心：

复制代码

-- FlashMLA will not compile: unsupported CUDA architecture 8.6  （需要 sm_90）
-- [QUTLASS] Skipping build: no supported arch (12.0a / 10.0a)   （需要 Blackwell）
-- Not building scaled_mm_c3x_sm90                                （需要 sm_90）
-- Not building NVFP4                                             （需要 sm_100）

编译成功标志：

复制代码

[145/145] Linking CXX shared module vllm-flash-attn\_vllm_fa2_C.pyd
-- Installing: vllm/_moe_C.pyd
-- Installing: vllm/cumem_allocator.pyd
-- Installing: vllm/vllm_flash_attn/_vllm_fa2_C.pyd
-- Installing: vllm/_C.pyd

六、打包 wheel

复制代码

# 创建 wheels 目录
New-Item -ItemType Directory -Force "J:\PythonProjects4\vllm-windows\wheels"

# 打包（仅打包 vLLM 本体，不含依赖）
pip wheel . --no-build-isolation --no-deps -w J:\PythonProjects4\vllm-windows\wheels\

生成文件：

复制代码

vllm-0.16.0rc2.dev243+gc8e1f5abe.d20260308.cu128-cp312-cp312-win_amd64.whl  (257 MB)

保存全部依赖的 wheel 文件：

去掉保存命令的 --no-deps 参数即可

复制代码

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

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

文件名结构解析：

0.16.0rc2.dev243 --- 版本号
cu128 --- 编译时使用系统中的 CUDA 12.8
cp312 --- Python 3.12
win_amd64 --- Windows 64位

七、安装与验证

7.1 在当前 venv 中验证

复制代码

# 安装两个被 platform_machine marker 过滤掉的依赖
pip install llguidance xgrammar

# 验证
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）

复制代码

# 使用 --no-deps 避免依赖冲突
pip install vllm-0.16.0rc2.dev243+gc8e1f5abe.d20260308.cu128-cp312-cp312-win_amd64.whl --no-deps

# 补装两个必须的依赖
pip install llguidance xgrammar

验证（ComfyUI 环境）：

复制代码

python -c "
import os
os.environ['USE_LIBUV'] = '0'

# _C 模块直接导入，不是从里面取 ops
import vllm._C as _C
print('✅ _C 扩展加载成功')

from vllm.vllm_flash_attn import flash_attn_varlen_func
print('✅ Flash Attention 2 加载成功')

from vllm import LLM, SamplingParams
print('✅ vllm 完整导入成功')
print('✅ 版本:', __import__('vllm').__version__)
"

复制代码

✅ _C 扩展加载成功
✅ Flash Attention 2 加载成功
2026-03-08 15:05:41.840025: I tensorflow/core/util/port.cc:153] oneDNN custom operations are on. You may see slightly different numerical results due to floating-point round-off errors from different computation orders. To turn them off, set the environment variable `TF_ENABLE_ONEDNN_OPTS=0`.
✅ vllm 完整导入成功
✅ 版本: 0.16.0rc2.dev243+gc8e1f5abe.d20260308

7.3 重要：USE_LIBUV 环境变量

PyTorch 2.7.1 stable 版本编译时未启用 libuv，导入 vLLM 前必须设置：

复制代码

import os
os.environ['USE_LIBUV'] = '0'
import vllm

或在启动脚本中设置系统环境变量：

复制代码

$env:USE_LIBUV = "0"

八、完整踩坑记录

坑1：xformers 会踩掉 torch 版本

requirements/windows.txt 中的 xformers==0.0.35.dev1121 依赖 torch>=2.10，pip 会自动把你的 torch 2.7.1 降级到 2.10.0。

解决：装完 windows.txt 后立即用 --force-reinstall 把 torch 恢复到 2.7.1+cu126。

坑2：CUDA 路径含空格导致编译失败

症状：

复制代码

c1xx: fatal error C1083: "Files/NVIDIA": No such file or directory

根因：CMake 把 CUDA_PATH 传给 cl.exe 时 -I 参数未加引号，空格导致路径被截断。

解决：用 subst 把 CUDA 路径映射到无空格的盘符（如 Z:）。

坑3：fix_cutlass_msvc.py 需要在 .deps 目录存在后执行

该脚本需要传入 CUTLASS 源码路径，但 CUTLASS 是 CMake 在配置阶段才下载的。直接执行会报 IndexError: list index out of range。

实际影响：本次编译未执行该脚本，但编译仍然成功。CUTLASS 相关的 MSVC 兼容性问题在 vLLM Windows 分支的当前代码中已通过其他方式处理。

坑4：llguidance 和 xgrammar 被 platform_machine marker 过滤

这两个包在 requirements 中有 platform_machine == "x86_64" 的条件，而 Windows 下 platform.machine() 返回 AMD64（不是 x86_64），导致安装时被跳过，运行时报 ModuleNotFoundError。

解决：手动安装：

复制代码

pip install llguidance xgrammar

坑5：版本不匹配警告

复制代码

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

这是 CMakeLists.txt 中硬编码的版本检查，只是警告，不影响编译，可以忽略。

九、编译环境一键恢复脚本

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

复制代码

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

# 映射 CUDA 路径
cmd /c "subst Z: `"C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8`""

# 设置环境变量
$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"

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

# 编译
python setup.py build_ext --inplace 2>&1 | Tee-Object "build.log"

# 打包
pip wheel . --no-build-isolation --no-deps -w wheels\

十、参考资料

SystemPanic/vllm-windows --- Windows 移植仓库

vLLM 官方文档 --- API 参考

本系列前文：ComfyUI-3D-Pack 六大依赖安装总览

本系列前文：Windows CUDA Extension 编译完全指南