📝 作者：berryyan | 最后更新：2026-03-31
💡 适用人群：使用 ComfyUI 桌面版、想用 SageAttention 加速注意力计算的 Windows 用户
⚠️ 本文基于真实踩坑经历，建议收藏备用
📋 使用前必读：路径替换指南
本手册使用 占位符 表示路径，使用前请替换为你的实际路径：
| 占位符 | 含义 | 你的实际路径示例 |
|---|---|---|
<COMFYUI_ROOT> | ComfyUI 桌面版主目录 | C:\Users\你的用户名\Documents\Comfyui |
<VENV_PYTHON> | 虚拟环境 Python 解释器 | <COMFYUI_ROOT>\.venv\Scripts\python.exe |
<MODELS_ROOT> | 模型文件根目录 | E:\AI\models 或 <COMFYUI_ROOT>\models |
<CUSTOM_NODES> | 自定义节点目录 | <COMFYUI_ROOT>\custom_nodes |
🔧 快速定位你的路径
# 1. 找到 ComfyUI 桌面版主目录
# 通常在你创建项目时的位置，或查看桌面快捷方式属性
# 2. 确认虚拟环境 Python 路径（关键！）
dir <COMFYUI_ROOT>\.venv\Scripts\python.exe
# ✅ 应显示文件存在
# 3. 确认模型目录（根据 extra_models_config.yaml 配置）
type %APPDATA%\ComfyUI\extra_models_config.yaml
💡 重要：所有命令中的
<COMFYUI_ROOT>等占位符，必须替换为你的实际路径，否则命令将无法执行！
🎯 一、我的环境与目标（供参考）
🔧 硬件/软件配置
| 组件 | 版本/型号 | 备注 |
|---|---|---|
| 🖥️ 系统 | Windows 10/11 64 位 | - |
| 🐍 Python | 3.12.11 | ComfyUI 桌面版虚拟环境 |
| 🔥 PyTorch | 2.11.0+cu130 | 关键：带 +cu130 后缀 |
| 🖥️ 系统 CUDA | 12.8 | nvcc --version 查看 |
| 🎮 显卡 | NVIDIA RTX 5090 32GB | - |
| 📦 ComfyUI | 桌面版 0.18.2 | 安装路径：<COMFYUI_ROOT> |
| 🌐 虚拟环境 | .venv | <COMFYUI_ROOT>\.venv |
🎯 安装目标
✅ 安装 triton-windows 3.6.0.post26（Windows 专用构建）
✅ 安装 SageAttention 1.0.6（稳定版，2.x 兼容性不佳）
✅ 让 kjnodes 的 "Model Optimization" 节点能启用 "sage" 后端加速
✅ 不影响现有 PyTorch/CUDA 环境稳定性
⚠️ 二、踩坑总结（血泪教训）
❌ 坑 1：(base) Conda 环境干扰
现象：命令行显示 (base)，pip 安装到 Conda 环境而非 .venv
后果：ComfyUI 找不到包，报 ModuleNotFoundError
✅ 解决：始终执行 conda deactivate，或直接用完整路径调用 .venv 的 python
❌ 坑 2：uv 处理 .dist-info 元数据问题
现象：uv pip install 报 "failed to read metadata" 或 "拒绝访问"
后果：核心包损坏，环境崩溃
✅ 解决：核心包（torch/numpy/triton）用标准 pip 安装，不用 uv
❌ 坑 3：Windows CMD 多行命令/通配符限制
现象：-c "多行 Python 代码" 执行失败；if exist numpy-*.dist-info 不匹配
后果：验证脚本无法运行，清理文件失败
✅ 解决：验证用单行命令；清理用具体文件名；复杂脚本用 .py 文件
❌ 坑 4：第三方自动安装器可能损坏环境
现象：安装器自动卸载了 PyTorch，导致环境崩溃
后果：前功尽弃，需紧急恢复
✅ 解决：手动分步安装，每步验证，不依赖自动化脚本
❌ 坑 5：文件被进程锁定
现象：安装时报 "拒绝访问 (os error 5)"
后果：包安装失败
✅ 解决：安装前 taskkill 终止 python/uv 进程，临时关闭 Windows Defender
❌ 坑 6：SageAttention 2.x 在 Windows+Python3.12 兼容性不佳
现象：安装器提示 "No pre-built wheel available"
后果：无法安装 2.x 版本
✅ 解决：降级使用 1.0.6 稳定版，功能足够且兼容性好
🛠️ 三、安装步骤（复制即用，记得替换路径！）
💡 所有命令均在 管理员身份命令提示符 中执行
💡 始终使用 完整路径 调用.venv的 Python，避免环境混淆
🔹 步骤 0：准备工作
# 1. 退出 Conda base 环境（关键！）
conda deactivate
# 确认命令行前缀 (base) 消失
# 2. 确认当前 Python 指向 .venv（替换为你的实际路径）
where python
# ✅ 预期输出应包含：
# <COMFYUI_ROOT>\.venv\Scripts\python.exe
🔹 步骤 1：安装 triton-windows
# 使用标准 pip（非 uv）安装 triton-windows
# ⚠️ 请将 <VENV_PYTHON> 替换为你的实际路径
<COMFYUI_ROOT>\.venv\Scripts\python.exe -m pip install ^
triton-windows==3.6.0.post26 ^
--no-cache-dir
✅ 验证：
<COMFYUI_ROOT>\.venv\Scripts\python.exe -c "import triton; print('✅ Triton:', triton.__version__)"
✅ 预期输出：✅ Triton: 3.6.0
🔹 步骤 2：安装 SageAttention 1.0.6
# 安装稳定版 SageAttention（指定 PyTorch CUDA 源）
<COMFYUI_ROOT>\.venv\Scripts\python.exe -m pip install ^
sageattention==1.0.6 ^
--extra-index-url https://download.pytorch.org/whl/cu130 ^
--no-cache-dir
✅ 验证：
<COMFYUI_ROOT>\.venv\Scripts\python.exe -c "from sageattention import sageattn; print('✅ SageAttention: OK')"
✅ 预期输出：✅ SageAttention: OK
🔹 步骤 3：完整环境验证
# 单行命令验证三组件
<COMFYUI_ROOT>\.venv\Scripts\python.exe -c "import torch, triton; from sageattention import sageattn; print('🔥 PyTorch:', torch.__version__); print('🚀 Triton:', triton.__version__); print('✅ All OK')"
✅ 预期输出：
🔥 PyTorch: 2.11.0+cu130
🚀 Triton: 3.6.0
✅ All OK
🔹 步骤 4：重启并测试 ComfyUI
# 1. 清理残留进程
taskkill /F /IM python.exe 2>nul
# 2. 重启 ComfyUI 桌面版
# 3. 检查启动日志关键行：
✅ pytorch version: 2.11.0+cu130
✅ Device: cuda:0 NVIDIA GeForce RTX 5090
✅ SeedVR2 optimizations check: SageAttention ✅ | Triton ✅
🔹 步骤 5：网页界面启用加速
1. 打开 ComfyUI: http://0.0.0.0:8001
2. 找到 "Patch Model" 或 "Model Optimization" 节点（来自 kjnodes）
3. 将参数设置为：
- Attention Backend: sage
- Sage Attention Mode: auto
4. 运行工作流，观察日志
✅ 预期成功日志：
✅ Using sage attention mode: auto
✅ Prompt executed in XX.XX seconds (无 Exception)
✅ 四、成功标志速查表
| 检查项 | 成功标志 | 验证命令/位置 | |
|---|---|---|---|
| 🔹 Triton 安装 | import triton 无报错 | <VENV_PYTHON> -c "import triton" | |
| 🔹 SageAttention 安装 | from sageattention import sageattn 无报错 | 同上 | |
| 🔹 PyTorch CUDA | 版本带 +cu130，cuda.is_available() 返回 True | <VENV_PYTHON> -c "import torch; print(torch.__version__, torch.cuda.is_available())" | |
| 🔹 ComfyUI 启动日志 | 显示 `SageAttention ✅ | Triton ✅` | <COMFYUI_ROOT>\user\comfyui.log 启动阶段 |
| 🔹 节点启用 | 工作流执行无 ModuleNotFoundError，日志显示 Using sage attention mode: auto | ComfyUI 执行日志 |
💡 五、最简洁建议（黄金法则）
🔧 1. 始终用完整路径调用 .venv Python：
<COMFYUI_ROOT>\.venv\Scripts\python.exe -m pip install xxx
🔧 2. 核心包用标准 pip，不用 uv（避免元数据问题）
🔧 3. 每步安装后立即单行验证，不要连续执行多条命令
🔧 4. 安装前终止进程 + 临时关闭杀毒软件（防文件锁定）
🔧 5. 重要操作前备份环境：
<VENV_PYTHON> -m pip freeze > <COMFYUI_ROOT>\backup.txt
🔧 6. SageAttention 选 1.0.6 稳定版，2.x 在 Windows+Py3.12 兼容性不佳
🔧 7. 避免第三方自动安装器，手动分步更可控
🆘 六、常见问题速查
❓ 验证时仍报 No module named 'xxx'
# 确认包安装到了正确环境（替换路径）
<COMFYUI_ROOT>\.venv\Scripts\python.exe -m pip list | findstr xxx
# 如未显示，强制重装
<VENV_PYTHON> -m pip install xxx --force-reinstall --no-cache-dir
❓ 安装时报 "拒绝访问 (os error 5)"
# 1. 终止相关进程
taskkill /F /IM python.exe
taskkill /F /IM uv.exe
# 2. 临时关闭 Windows Defender 实时保护
# 3. 重试安装
❓ ComfyUI 日志仍显示 SageAttention ❌
→ 确认工作流中优化节点的 "Attention Backend" 设为 "sage"
→ 检查是否使用了支持 SageAttention 的模型（DiT 架构如 Wan2.2/Flux）
→ 首次运行需编译 kernel，第二次应更快
❓ 加速效果不明显
→ 尝试更高分辨率（≥1024×1024）或更长序列
→ 对比测试：相同工作流分别用 "pytorch" 和 "sage" 后端运行
→ 确认节点配置正确，插件版本最新
🎉 七、写在最后
这份手册基于我真实的踩坑经历整理，希望能帮你少走弯路。
SageAttention 在 Windows 上的支持仍在完善中，稳定优先于极致速度是明智选择。
如果你的环境与我类似，按本文步骤操作，99% 可一次成功。
如遇新问题，欢迎反馈交流！
🔧 环境稳定是高效创作的基础
✅ 先跑通，再优化
🚀 祝你生成愉快！
📌 附录：一键复制命令模板（替换占位符后使用）
:: ===== 使用前请替换所有 <COMFYUI_ROOT> 为你的实际路径 =====
:: 1. 退出 Conda 环境
conda deactivate
:: 2. 安装 triton-windows
<COMFYUI_ROOT>\.venv\Scripts\python.exe -m pip install triton-windows==3.6.0.post26 --no-cache-dir
:: 3. 验证 triton
<COMFYUI_ROOT>\.venv\Scripts\python.exe -c "import triton; print('✅ Triton:', triton.__version__)"
:: 4. 安装 SageAttention 1.0.6
<COMFYUI_ROOT>\.venv\Scripts\python.exe -m pip install sageattention==1.0.6 --extra-index-url https://download.pytorch.org/whl/cu130 --no-cache-dir
:: 5. 验证 SageAttention
<COMFYUI_ROOT>\.venv\Scripts\python.exe -c "from sageattention import sageattn; print('✅ SageAttention: OK')"
:: 6. 完整环境验证
<COMFYUI_ROOT>\.venv\Scripts\python.exe -c "import torch, triton; from sageattention import sageattn; print('🔥 PyTorch:', torch.__version__); print('🚀 Triton:', triton.__version__); print('✅ All OK')"
:: 7. 清理进程并重启
taskkill /F /IM python.exe 2>nul
:: 然后手动重启 ComfyUI 桌面版
✨ 使用提示：
- 复制上方命令到记事本
- 按
Ctrl+H批量替换<COMFYUI_ROOT>为你的实际路径（如C:\Users\你的用户名\Documents\Comfyui）- 保存为
.bat文件或逐行粘贴到命令提示符执行- 每执行一步，确认输出正常再继续下一步
✨ 收藏备用，祝你一次成功！🔧🚀
