如果你最近开始折腾 ComfyUI，大概率体会过什么叫做“环境比模型更难搞”。Python 版本要卡、CUDA 要对号、PyTorch 还得和显卡驱动匹配，装错一版就能让你白折腾好几天。我一度在 Windows 裸机环境下跟各种 DLL 报错斗智斗勇，后来果断切到 WSL2 + Docker，把整套 ComfyUI 环境装进容器里，终于不用再担心系统被我玩坏了。这篇不是官方文档，是我自己踩坑后的实机笔记，适合刚接触 ComfyUI、想在 Windows 上稳定跑起来、又不想被环境问题劝退的朋友参考。
1. 为什么是 WSL2 + Docker，而不是直接在 Windows 里装
1.1 ComfyUI 的依赖到底复杂在哪
ComfyUI 本质是一个 Python 应用，但它对运行环境的敏感程度远超普通脚本。比如 PyTorch 需要和 CUDA 版本对应，而 CUDA 又要跟显卡驱动匹配，再加上 cuDNN、TensorRT 之类的加速库，稍微错一个版本号，很可能在导入模型时报出一堆看不懂的堆栈错误。
更麻烦的是自定义节点。ComfyUI 社区非常活跃，各种自定义节点库几乎是“装了就离不开”的节奏。可这些节点库经常各自指定依赖版本，有的要torch>=2.1，有的却在torch==2.0.1下跑得最稳。直接在 Windows 的全局 Python 环境里装，运气好能压住冲突，运气不好就是一个包升级连带另一个包崩溃。我甚至遇到过装一个节点库，把整个 PyTorch 都替换掉，最后连启动界面都进不去的尴尬情况。
所以需要一个隔离环境，把 ComfyUI 和它的所有依赖封装起来，和宿主系统彻底分开。Docker 容器正好是干这个的。镜像里是什么版本，跑起来就是什么版本，不会因为 Windows 补丁更新、别的软件安装而突然变卦。
1.2 WSL2 给 Docker 补上了 Linux 兼容层
很多人问，Windows 上不是也能装 Docker 吗？没错，但如果用 Hyper-V 后端，和某些软件的虚拟化功能容易冲突，而且性能表现在某些机器上并不理想。WSL2 则提供了一个轻量的 Linux 内核，文件系统性能和兼容性都比早期 WSL 好很多。
重点是 WSL2 支持 GPU 透传，也就是可以把 Windows 侧安装好的显卡驱动能力直接暴露给 Linux 环境。这样一来，容器里运行 ComfyUI，也能调用 NVIDIA 显卡做推理加速，而不需要真的在容器里再装一遍驱动。整体体验有点像“在 Windows 里藏了一个 Linux 开发机，但用起来又不需要切换系统”。
Docker Desktop 开启 WSL2 引擎后，容器就直接跑在这个 Linux 发行版上，和 WSL2 共享同一套内核。对于我这种需要随时切换工作内容、又不想双系统重启的人来说，这个组合几乎是当前 Windows 上最顺滑的 AI 绘画环境方案。
2. 环境底座是第一道坎：WSL2 配置与避坑
2.1 从零开启 WSL2
这里先假设你已经拥有一台主流 Windows 系统。开启 WSL2 最省事的方式是在管理员身份的 PowerShell 里执行：
wsl --install系统会自动启用的必要的 Windows 组件，并默认安装一个 Linux 发行版。命令跑完以后一般会提示重启。重启后输入：
wsl --set-default-version 2把默认版本固定成 WSL2。如果你不想用默认发行版，也可以先安装一个 Ubuntu，或者你习惯的其他发行版。我选择 Ubuntu 是因为社区资料多，遇到任何问题搜索引擎里基本都有答案。
这里有一个很容易踩的坑：BIOS 里没有开启虚拟化。如果执行wsl --install后安装失败，或者启动后一直卡住，先去 BIOS 确认 CPU 虚拟化技术是否打开。Intel 平台对应的是 VT-x，AMD 平台对应 SVM，不同主板叫法不太一样，但肯定会有类似字样。
2.2 内存、CPU 与 swap 配置
WSL2 默认会占用相当比例的物理内存，而且有时候明明没有跑大程序，却看到内存占用一直很高。这个不是 bug，而是 WSL2 的内存回收机制和 Windows 侧不一样。如果你只是偶尔用它跑 ComfyUI，建议主动控制资源上限。
在 Windows 用户目录下新建一个文件叫.wslconfig，内容可以参考我目前的配置：
[wsl2] memory=8GB processors=4 swap=8GB localhostForwarding=truememory是 WSL2 可用的最大内存，processors是可用 CPU 核数，swap是虚拟交换分区大小。如果你的机器只有 16GB 内存，设置成 8GB 通常够用，除非你要同时跑大型数据集或并发生成多个工作流。设置完成后在 PowerShell 里执行wsl --shutdown让配置生效。
2.3 我踩过的 WSL2 配置坑
第一个坑是wsl: 检测到 localhost 代理配置，但未镜像到 WSL。这个提示看着吓人，其实它只是说 Windows 的本地代理设置没有被转发到 WSL2，对局域网内的正常访问没有影响。我在使用过程中只要不涉及外部网络代理，就完全不需要管它。
第二个坑是wsl --set-version 2转换卡死，进度一直停在 99%。这时候别急着关窗口，去任务管理器里看看有没有 WSL 进程卡住。如果实在等不到结果，可以检查一下当前发行版的文件系统是否放在机械硬盘上，转换过程扫描大文件会非常慢。解决办法是把发行版移动到系统盘或者性能更好的固态盘，重新执行转换。
第三个坑是常驻内存不释放。WSL2 里跑过一些任务以后，就算退出终端，Vmmem 进程的内存占用也不一定立刻降下来。这个很大程度上是 Linux 的文件缓存特性导致的。真正有效的做法就是配置.wslconfig，并且定期wsl --shutdown重置整个环境。
3. Docker Desktop 接入 WSL2 与 ComfyUI 容器
3.1 Docker 引擎和 WSL2 怎么接
在 Windows 安装 Docker Desktop 后，默认会提供两种后端。要让容器跑在 WSL2 里，需要在 Docker Desktop 的 Settings 中选择General选项卡，勾选Use the WSL 2 based engine，然后在Resources > WSL Integration里勾选你准备使用的 Linux 发行版。这一步很多人会漏掉，导致 Docker 虽然启动了，但容器却跑在 Hyper-V 虚拟机里，和 WSL2 的文件互通没那么顺畅。
我自己习惯把发行版限定在一个固定的 Ubuntu 里，避免 Docker 容器资源分布太分散。勾选完成以后，在 WSL2 终端里执行docker version能看到客户端和服务端版本都正常显示，说明已经打通。
3.2 拉取或构建 ComfyUI 镜像
ComfyUI 官方仓库里提供了 Dockerfile，自己构建最稳妥，因为能够确保和你想要的组件版本匹配。构建步骤如下：
git clone https://github.com/comfyanonymous/ComfyUI.git cd ComfyUI docker build -t comfyui:local .这个过程会拉取基础镜像并安装大量 Python 依赖，时间取决于网络和机器性能。我第一次构建时等了几十分钟，还以为卡住了。实际上只要看到日志逐条刷新增安装包，就没有问题。
如果你想更快上手，也可以直接拉取社区预构建的镜像。不过我个人更推荐自己构建，至少你知道里面装了什么，后续出现问题也好排查。如果拉取镜像很慢，可以先检查一下当前 Docker 环境的基础网络配置，但阶段性问题通常换个时间段就能缓解，不必盲目调整系统设置。
3.3 启动容器的参数详解
构建完成后，启动容器不要直接双击镜像图标，而是用一个能清晰看到所有参数的命令。我常用的命令是：
docker run --gpus all \ -p 8188:8188 \ -v /mnt/d/ComfyUI/models:/workspace/models \ -v /mnt/d/ComfyUI/output:/workspace/output \ -v /mnt/d/ComfyUI/custom_nodes:/workspace/custom_nodes \ --name comfyui \ comfyui:local--gpus all代表把宿主机可用的 GPU 全部透传给容器。-p 8188:8188是端口映射，ComfyUI 默认跑在 8188 端口。-v参数是我最看重的部分，它把 Windows 下的模型目录、输出目录和自定义节点目录挂载进容器。
这么做的原因很简单：容器本身是无状态的，把它删掉重建都很正常，但模型和工作流不能丢。如果把模型直接塞进容器内部，以后镜像体积会越来越大，升级容器时还得折腾迁移。挂载出来之后，下载模型、整理文件都直接在 Windows 文件管理器里操作，非常顺手。
3.4 用 Docker Compose 固化配置
手敲docker run只是临时方案。为了以后重装环境不抓瞎，我把整套参数整理成了docker-compose.yml，放在一个固定的项目目录里。给出一个精简版本：
services: comfyui: image: comfyui:local container_name: comfyui ports: - "8188:8188" volumes: - /mnt/d/ComfyUI/models:/workspace/models - /mnt/d/ComfyUI/output:/workspace/output - /mnt/d/ComfyUI/custom_nodes:/workspace/custom_nodes environment: - NVIDIA_VISIBLE_DEVICES=all restart: unless-stopped实际使用中，我只需在项目目录里执行docker compose up -d，就可以一键启动整个环境。Compose 文件里还配置了restart: unless-stopped，系统重启后容器会自动拉起，省掉手动敲命令的麻烦。
4. 容器里的 ComfyUI 跑起来之后
4.1 首次启动与浏览器访问
容器启动成功后，会看到终端刷出类似 “Starting server” 的日志。首次启动可能要等一段时间，因为要初始化缓存和临时文件。随后打开浏览器输入http://127.0.0.1:8188，就能看到 ComfyUI 的工作台界面。
这里有个细节：如果你是通过 WSL2 终端启动的容器，并且在 Windows 浏览器访问，一般 localhost 已经能够自动转发。但如果你关闭了.wslconfig里的localhostForwarding=true，就需要手动访问 WSL2 的 IP 地址，麻烦不少。
4.2 模型文件放哪、工作流怎么导入
ComfyUI 的模型目录结构是有讲究的。models/checkpoints放主模型，models/loras放 LoRA，models/vae放 VAE，models/controlnet放 ControlNet 相关文件。如果放错位置，前端即便能看到对应文件名，也可能在加载时报路径错误。
导入工作流最简单的方式是直接把 JSON 文件拖到 ComfyUI 浏览器窗口里，它会自动还原节点连线。如果某个节点是红色，说明对应的自定义节点没装或依赖缺失。这时候需要看节点名称，去自定义节点库里补装。
4.3 自定义节点怎么装
ComfyUI 的自定义节点通常放在custom_nodes目录下。由于我们启动容器时已经把 Windows 下的目录挂载进去了，所以直接在 Windows 文件管理器里把克隆下来的节点文件夹放在custom_nodes下就行。
不过很多自定义节点不只是把代码放进去即可，它们还需要额外安装 Python 依赖。这时需要进入容器执行安装命令：
docker exec -it comfyui /bin/bash pip install -r /workspace/custom_nodes/某个节点/requirements.txt装完以后，建议重启容器再刷新页面，避免运行时依赖没加载完全导致节点报错。
5. 重点避坑汇总
5.1 GPU 不生效
最典型的症状是容器能启动，但生成图片时一直走 CPU，速度极慢。在容器内执行nvidia-smi如果显示“command not found”，先别急着安装驱动。WSL2 环境下，容器里的显卡驱动其实是透传宿主机的，只要 Windows 侧驱动正确，容器里往往不需要再装。
如果nvidia-smi看不到显卡，检查 Windows 侧是否安装了较新的 NVIDIA 驱动。旧版 WSL 驱动可能有兼容性问题，建议到驱动官网更新到较新版本。另外一个常见原因是 Docker Desktop 没有正确识别 WSL2 的 GPU 能力。确认 Docker Desktop 版本较新，并且容器启动参数里包含了--gpus all。
5.2 端口访问不了
有时候容器启动正常，但浏览器就是打不开 8188 端口。先从宿主机看端口监听情况：
docker ps确认端口映射启动了。如果映射存在，但仍然访问不了，那么大概率是 Windows 防火墙拦截了 Docker 子网的入站连接。这通常发生在你尝试用局域网内其他设备访问该机器的 8188 端口时。如果只是在同一台电脑上用浏览器访问，一般不会遇到。
解决思路是给 Windows 防火墙添加入站规则，放行 Docker 使用的网络接口，或者将访问范围限制在本地子网。我个人的建议是默认情况下不要开放到公网，ComfyUI 没有复杂的鉴权机制，暴露出去很容易被陌生人直接调用你的显卡资源。
5.3 模型下载慢或者中断
在容器内或者 Windows 里直接调用 Python 脚本去下载大模型，经常会出现下载中断的情况。我后来的做法是先用下载工具把模型文件完整下载到 Windows 本地，再放到挂载目录里。这样做的好处是下载中断可以续传，文件大小校验也更方便。
放模型时还要留意路径里不要有空格和中文。虽然现代工具大多能兼容，但某些节点库会去解析路径字符串，遇到中文缩写或空格时偶尔会出错。最省心的做法就是在 D 盘建一个全英文无空格的目录，比如D:\ComfyUI\models。
5.4 中文路径和权限问题
如果你把模型挂载目录设置在系统盘的某个深层目录，尤其是带中文用户名的路径，Docker Desktop 的文件共享可能出现权限拒绝。解决方法是把模型根目录放到一个独立、全英文的顶层目录，并且在 Windows 用户组里确保你的账号对该目录有完全控制权限。
还有一种情况是，在容器里往挂载目录写入文件时没有权限，表现为Permission denied。这是因为容器内的用户 ID 和主机目录的所有者不一致。最简单的做法是给目录设置更宽松的权限，或者调整容器内用户，确保对/workspace有写权限。
5.5 内存满载导致 WSL2 崩溃
ComfyUI 跑大图或批量出图时，内存占用会突然升高。如果物理内存不足，WSL2 可能被系统直接杀掉，表现为 Windows 的事件日志记录 WSL2 进程异常退出，容器全部消失。
要避免这个问题，一方面把.wslconfig里的 swap 调大，另一方面在 ComfyUI 里注意批量生成的数量不要一次拉太多。我通常限制单个任务最高分辨率，并且用多进程并发的方式控制在 2~3 个任务以内，既保证显卡利用率，又不至于把内存顶爆。
5.6 容器版本升级导致环境失效
这一问题比较隐蔽。升级容器镜像时如果不注意挂载目录，新的镜像可能覆盖了旧镜像里已安装的自定义节点依赖，导致工作流全部变红。由于我们特意把custom_nodes挂载出来了，多数情况下能保留代码，但 Python 环境是镜像内的，升级后可能和节点依赖版本不兼容。
解决方法是给镜像固定标签，不要总用latest。每次升级前，先把当前工作流导出一份备份，然后记录容器内安装过哪些额外依赖。升级后先跑一个最简单的文生图工作流，确认基础链路正常，再逐步恢复自定义节点。
6. 我后来还会用到的几个小技巧
6.1 用 docker exec 进入容器调试 Python 包
容器运行过程中，需要查看某个 Python 包版本或测试某个脚本，直接进去是最快的路径。比如：
docker exec -it comfyui python -c "import torch; print(torch.__version__, torch.cuda.is_available())"这样可以在不改动外部环境的前提下快速确认 GPU 是否可用。遇到节点报错时，也能直接在容器里跑一段 Python 来复现，比盲猜可靠得多。
6.2 清理悬空镜像和残留容器
每次构建新镜像后，旧的镜像就会变成悬空镜像，堆积多了会占不少磁盘空间。我的清理习惯是：
docker system df docker image prune -a docker container pruneimage prune会把不再被任何容器引用的悬空镜像清掉，速度很快。定期清理后，磁盘空间会舒服很多。
6.3 备份 Compose 文件和工作流
我最深的感受是：环境是可重建的，但工作流和模型是难备份的。现在我每周会做一次轻量备份，把docker-compose.yml和全部模型清单、工作流 JSON 压缩存档。这样一旦电脑出现问题，我只需要在新机器上安装 WSL2 和 Docker，再执行docker compose up -d，然后导入工作流，整个环境就回来了。
6.4 不要忽略容器日志
ComfyUI 启动失败时，别急着更换镜像，先看日志。用docker logs comfyui能输出容器内的标准输出和标准错误，往往能直接定位到缺少的是哪个依赖、哪个模型文件路径不存在。这个操作免费且高效，比我之前靠猜错误原因强太多。
7. 个人体会和后续建议
整套 WSL2 + Docker 方案配置下来，最大的收获并不是“能跑”而已，而是终于把环境问题变成了一件可以复现、可迁移、不怕折腾的事情。以前我在 Windows 上装 ComfyUI，三天不敢乱动系统，生怕某个库更新又把环境弄崩。现在只要容器挂了，直接删掉再起一个也就是几分钟的事情，模型和工作流都稳稳地挂在宿主机目录里，完全不怕容器丢失。
如果你也是被环境折磨过的人，我建议从这套方案入手，先把基础环境跑通，再考虑优化性能和多节点调度。刚开始可能会觉得 WSL2、Docker、端口映射这些概念有点多，但只需要跟着跑一遍，后面的收益是实打实的。至少以后换机器、迁移工作环境时，你不用再跪求当年的自己保佑“记住当时是怎么装的了”。
