兰台羲和Lab 文章库
mac mini ComfyUI 实战

01 · ComfyUI 源码版安装与 9 坑实录

约 14 分钟驭光者首发于微信公众号「羲和Lab」

系列:mac mini ComfyUI 实战(01/07)· 教程型 · 阅读时长约 18 分钟 读者定位:想在 Mac(M 系列)上装 ComfyUI 跑视频模型的用户;已装桌面版遇到崩溃的用户。全程终端操作,需命令行基础,无需 ComfyUI 经验。 实测环境:Mac mini M5 Pro / 64GB 统一内存 / macOS 27.0 · 实测时间 2026-09-24~26(版本锁定表见第二章)

开篇:第一次崩溃

2026-09-24 19:07,我在桌面版 ComfyUI 里第一次提交 H3 视频生成任务。采样第 0 步,直接崩:

NotImplementedError: The operator 'aten::_int_mm' is not currently implemented
for the MPS device

整单 44.21 秒,失败。这个报错最迷惑的地方在于:前一天(9-23)同一个模型还能跑,115 秒一步。代码没改,模型没换,怎么就崩了?

后来查明白了:前一天跑成的是另一套程序。9-23 的旧环境无视模型的量化元数据,把 int8 权重当普通权重跑(bf16 路径);9-24 桌面版首次启动(日志里 Database upgraded from None 可佐证,此为推断),新版量化栈检测到 H3 的 int8 权重,走了原生 int8 路径,调用 torch._int_mm——而桌面版捆绑的 torch 版本在 MPS 后端上没有这个算子。「昨天好好的」是因为昨天是另一套程序。

这一崩,牵出后面 9 个坑,也牵出一套可复现的环境配方。本文先把环境装对——环境装不对,后面的实测数字和操作步骤都无从谈起(00 篇语)。

一、为什么放弃桌面版,选源码版

桌面版的问题:栈不可控。 桌面版捆绑 ComfyUI 0.34.0 + torch 2.12.1,你不能选版本。坑 1 的崩溃链是:量化栈(comfy-kitchen)检测到 H3 的 int8 权重 → 走 Native 路径 → 调用 torch._int_mm → 该版本 torch 的 MPS 后端无此算子 → 崩。桌面版里你既换不了 torch,也看不到这条链,只能干瞪眼。

源码版的收益:版本自选、nightly 可用、坑可修。 9 个坑里有 7 个的解法都以源码版为前提——换 torch 版本(坑 3)、锁 requirements 版本(坑 2)、删环境重建(坑 4)、控制启动参数(坑 8),桌面版一个都做不到。

Mac 生态位先给结论(事实卡片详见第四章):

  • torch 2.14.0 正式版实测无 MPS _int_mm(has_mps_kernel: False,2026-09-25 实测凭证)
  • pytorch 仓库 issue #190337("[MPS] Add aten::_int_mm support",2026-07-17 closed)的实现未进入 2.14.0 正式包(2026-09-25 查询)
  • nightly 2.15.0.dev20260924 是否包含,待验证——本文不写成结论,见第四章待验证清单

这一节只讲「为什么」。怎么装,下一节。

二、源码版安装全流程

可复现配方,五步。每步先说为什么,再给命令。

第 1 步:取源码,锁 v0.36.0 tag

为什么不跟 master:master 的 requirements 要求 comfyui-workflow-templates==0.11.69,它有个依赖死锁(坑 2);v0.36.0 tag 要求 0.11.62,没有这个问题。

git clone https://github.com/comfyanonymous/ComfyUI.git ~/ComfyUI
cd ~/ComfyUI
git checkout v0.36.0

预期输出:HEAD is now at ... v0.36.0。失败回退:若网络拉不动 GitHub,可用镜像加速;若 tag 不存在(git tag -l 查),说明仓库版本演进,回到 releases 页面对照最新稳定 tag,再核对 requirements 里 workflow-templates 的版本号是否安全。

第 2 步:建全新 conda 环境,只装 Python

关键在「全新」二字——坑 4 的幽灵版本就是新旧环境互相污染造成的。新环境除 Python 外什么都不装:

conda create -n comfyui python=3.11 -y
conda activate comfyui

预期输出:环境创建成功,python --version 显示 3.11.x(实测 3.11.16)。失败回退:若 conda 未安装,先装 miniconda;不要图省事用系统 Python 或复用旧环境。

第 3 步:pip 单一来源装依赖

纪律来源是坑 4:torch 全家一律 pip,永不 conda。conda 和 pip 写同一个 site-packages,后装者胜,元数据互相污染。

cd ~/ComfyUI
pip install -r requirements.txt

预期输出:依赖装完,其中含 comfy-kitchen 0.2.34。失败回退:若某个包版本冲突,优先核对是否在用 v0.36.0 tag(第 1 步);不要手动注释 requirements 里的核心依赖——唯一可注释的是 workflow-templates(它只是官方内置模板素材库,自建工作流零影响,见坑 2)。

第 4 步:装 nightly 三件套,同源同日

torch / torchvision / torchaudio 三件套必须同源同日,否则 .so 加载崩(坑 4 的症状之一)。--no-deps 防止 pip 顺手把已装好的 torch 换掉:

pip install --pre torch torchvision torchaudio \
  --index-url https://download.pytorch.org/whl/nightly/cpu --no-deps

预期输出:三件套均为 nightly 版(实测 2026-09-24 同日版,torch 2.15.0.dev20260924)。失败回退:若 nightly 装失败,可回退最近的稳定版三件套(具体版本对照 PyTorch 官网 stable 与 ComfyUI 官方 releases 的搭配要求)——回退后先用小图(544×960)测速验证再跑正片:若每步掉到 30 倍减速档(对照第四章),换回 nightly。

第 5 步:挂载模型库,启动

模型库单独放共享目录,用 extra_model_paths.yaml 挂载——文件放在 ~/ComfyUI 根目录,指定共享模型的 base_path 后,unet / text_encoders / vae / checkpoints 等模型目录自动映射(可只挂实际用到的几类;实测挂载结构:共享目录 ~/ComfyUI-Shared/models 全类映射)。最小结构示意(字段格式以 ComfyUI 官方文档 config 一节为准,示意不替代官方文档):

# ~/ComfyUI/extra_model_paths.yaml(最小示意)
my-models:
    base_path: ~/ComfyUI-Shared/models
    is_default: true

启动命令:

conda activate comfyui && cd ~/ComfyUI
PYTORCH_ENABLE_MPS_FALLBACK=1 python main.py --listen 0.0.0.0

预期输出:启动日志滚过后出现 Total VRAM = Total RAM(统一内存识别成功)与 To see the GUI go to: http://0.0.0.0:8188(端口监听成功)。

失败回退:①模型列表为空 → 检查 yaml 的 base_path 路径与缩进;②端口 8188 被占(Address already in use)→ 关掉旧实例或换 --port 8189;③远程访问不通 → 先去掉 --listen 本机验证,再查防火墙。

两个参数说明:

  • PYTORCH_ENABLE_MPS_FALLBACK=1:不支持的算子回退 CPU 执行,是防崩保险,正常路径零开销——坑 1 之后我的默认配置
  • --listen 0.0.0.0:允许局域网访问(我从另一台机器调 mini 上的实例)。安全提示:这意味着同一局域网内的设备都能访问你的 ComfyUI,家庭网络可用,公共网络慎用;只在本机用就去掉这个参数

不要加 --use-split-cross-attention——它和 H3 视频不兼容(坑 8)。

版本锁定表(可复现配方)

组件版本备注
ComfyUIv0.36.0(git tag)源码版,~/ComfyUI
Python3.11.16conda env comfyui,全新环境
torch2.15.0.dev20260924(nightly)官方 nightly 源
torchvision / torchaudionightly 同日版(=2026-09-24)三件套同源同日,实测环境无逐字版本号记录,以同日版标识
comfy-kitchen0.2.34随 requirements 安装
workflow-templates0.11.62v0.36.0 tag 的 requirements 所定(坑 2 相关)

实测于 2026-09-25,Mac mini M5 Pro / 64GB 统一内存。锁定表锁定的是可用配方——它不等于「_int_mm 原生支持已验证」(见第四章待验证清单)。替代版本与降级路径见坑 2、坑 3。

三、9 坑逐条实录

结构纪律:每坑三段式——现象(报错原文)→ 根因 → 解法,结尾一句话记住。坑编号与测评数据总表 §四速查表一一对应。

坑 1:桌面版跑 H3 即崩

  • 现象:NotImplementedError: The operator 'aten::_int_mm' is not currently implemented for the MPS device,采样第 0 步崩,整单 44.21 秒失败(2026-09-24 19:07)。
  • 根因:桌面版捆绑 ComfyUI 0.34.0 + torch 2.12.1;新版量化栈(comfy-kitchen)检测到 H3 的 int8 权重,把 int8 算子走 Native 路径 → 调 torch._int_mm → 该 torch 的 MPS 后端无此算子。9-23 能跑的旧环境无视量化元数据,把 int8 当普通权重跑——「昨天好好的」是另一套程序。
  • 解法:卸载桌面版,源码安装(第二章);启动加 PYTORCH_ENABLE_MPS_FALLBACK=1 防崩保险。
  • 一句话记住:桌面版栈不可控,Mac 上跑量化视频模型,源码版是唯一可控路径。

坑 2:workflow-templates 0.11.69 依赖死锁

  • 现象:master 版 requirements 要求 comfyui-workflow-templates==0.11.69,其新增依赖 comfyui-workflow-templates-media-assets-02==0.1.5 在 Python 3.13 与 3.11 下均无可装版本(Requires-Python 全不匹配),pip 直接装不上。(对照说明:0.11.69 是 master 的要求,v0.36.0 tag 要求 0.11.62——两个版本号来自不同版本源,不是笔误。)
  • 根因:官方 master 的模板素材库依赖链在该时点没有发布匹配的包。
  • 解法:切 v0.36.0 tag(要求 0.11.62,无此依赖);或手动注释 requirements 中该行——这个包只是官方内置模板素材库,自建工作流零影响。
  • 一句话记住:装不动 master 先换 tag,稳定 tag 的 requirements 是干净的。

坑 3:torch 旧版拒绝 list[int] 注解

  • 现象:ValueError: infer_schema(func): Parameter stride has unsupported type list[int],comfy_kitchen 注册 fp16_conv3d 算子时 import 即崩。
  • 根因:comfy_kitchen 用了 Python 3.9+ 的内置泛型注解(list[int]),旧 torch 的 schema 推断只认 typing.List——版本代沟。
  • 解法:升级 torch(走第二章第 4 步的 nightly);或 sed 一行把注解改成 typing.List 兼容——治标,推荐升级。
  • 一句话记住:依赖库用新语法,你的 torch 就不能太旧,三件套跟着 ComfyUI 的要求走。

坑 4:conda/pip 混装 → 幽灵版本(最难缠)

  • 现象:按时间线,先后出现三重矛盾状态——①torch 报 "2.14.0 无 MPS int8";②再查变 "2.6.0.dev20241112"(2024 年的老 nightly);③torchaudio .so 加载崩。同一个环境,三个互相矛盾的版本状态。
  • 根因:conda install pytorch-nightly::pytorch -c pytorch-nightly 装到了陈旧 nightly;随后 pip install -U torch 又覆盖一遍。两者写同一个 site-packages,后装者胜,元数据互相污染——你看到的版本号和实际加载的 .so 可能对不上。
  • 解法(终极):conda remove -n comfyui --all 删干净 → 新环境只装 python → pip 单一来源装 requirements → pip 装 nightly 三件套(--no-deps 防 pip 动已装好的 torch)。即第二章完整流程。
  • 一句话记住:torch 全家一律 pip,永不 conda。

坑 5:H3 分辨率必须 32 的倍数

  • 现象:RuntimeError: shape '[1, 24, 1, 1, 60, 2, 33, 2]' is invalid for input of size 192960,patchify 的 reshape 崩。
  • 根因:1080 不能被 32 整除(1080÷32=33.75;等价地 1080÷16=67.5 非整数)——H3 VAE 做 16× 下采样,patch 再做 2×2 切分,合起来要求宽高各被 16×2=32 整除;1080 不满足,latent 网格对不齐,reshape 失败。1920=60×32 合规,所以只有宽炸。
  • 解法:宽 1080 → 1088(=34×32),成片裁 8px;分辨率选择器节点的「倍数」参数设为 32 的倍数(实测设 32;设 60 会得到 1080×1920,复现此崩)。文生图 Z-Image 无此限制——那是 8 像素 latent 对齐(00 篇首封实测:请求 900×383 实际输出 896×376)。
  • 一句话记住:H3 视频宽高对 32 取整,文生图对 8 取整,两套规则别混。

坑 6:全尺寸超线性减速(简版,详见 00 篇)

  • 现象:1088×1920 全尺寸每步 2010.68 秒,采样 2:20:24 后中断于解码段;而 768×1344 每步只要 416.82 秒。
  • 根因:实测层——64GB 内存用到 61.29GB(95%)(活动监视器凭证);机制层——大张量在内存层级间反复倒腾、而非计算变慢,此为推断(00 篇第五章的双层口径:机制解释属推断,不升格为实测)。
  • 解法:批量生产固定 768×1344 档(像素量为全尺寸的 49.4%,耗时仅 20.7%,比线性划算;劣化系数双口径见 00 篇)。详见 00 篇《本地 AIGC 实测》第五章。
  • 一句话记住:Mac 上批量视频选 768 档;1088 全尺寸实测采样 2 小时 20 分仍未产出成品,批量场景不要碰。

坑 7:Stable Audio 3 checkpoint 不含文本编码器

  • 现象:ERROR: clip input is invalid: None + [WARNING] no CLIP/text encoder weights in checkpoint。
  • 根因:stable_audio_3_medium.safetensors 是 diffusion-only 文件,CheckpointLoaderSimple 的 CLIP 输出为空——文本编码器根本不在这个包里。
  • 解法:CLIPLoader 单独加载 t5gemma_b_b_ul2.safetensors(type=stable_audio)接 CLIPTextEncode;CheckpointLoaderSimple 只取 MODEL+VAE。
  • 一句话记住:音频模型自带「半个工作流」,文本编码器永远单挂。

坑 8:--use-split-cross-attention 与 H3 视频不兼容

  • 现象:RuntimeError: Invalid buffer size: 210.34 GiB,崩在 attention_split 的 einsum(768×1344×125 帧任务,采样第一步)。
  • 根因:该参数把注意力切到 split 实现;H3 视频 token 序列超长,split 分块的中间缓冲要 210GB,被直接拒绝。
  • 解法:H3 视频任务不加该参数,保持默认 sub-quadratic 路径(实测 544 档快、1088 档慢但能跑)。它对文生图或有小收益,但对视频是负优化。
  • 一句话记住:优化参数分模态,split-attention 对视频是负优化,只给图片用。

坑 9:视频模型在留白区生成文字幻觉(简版,详见 03 篇)

  • 现象:大留白构图的镜头里,视频模型在画面中下部自发生成一行无语义字纹,与后期叠字打架。
  • 根因:H3 对大片纯净留白倾向用文字状纹理填充(文生图同理:Z-Image 去轨后仍有 1/3 候选惯性画环)。
  • 解法:分镜阶段给留白一个用途(下部渐变压暗),字纹埋进暗部;或构图上避免无功能的大留白。视频内容层的展开见 03 篇。
  • 一句话记住:留白不是免费的,构图时给它安排任务。

四、Mac 生态位事实卡片

comfy-kitchen 三行为对照(MPS + int8 权重,实测凭证)

栈组合行为实测日期
comfy-kitchen 0.2.31 + torch 2.12Native 路径 → 崩(_int_mm 缺失)2026-09-24
comfy-kitchen 0.2.31 + torch 2.14emulated fp32 → 3391 s/it,约 30 倍减速(对照基准:115 s/步,9-23 旧装;若对照 0.2.34+nightly 的 46 s/it 则约 74 倍——写明基准防歧义)2026-09-24 深夜
comfy-kitchen 0.2.34 + nightlyemulated 优化 → 46 s/it(小图),可用2026-09-25

同一块芯片,三种栈组合,从「崩」到「30 倍慢」到「可用」——版本组合决定一切,这是源码版的核心价值。

量化仿真本质

int8 在 MPS 上是仿真执行(emulated)而非原生加速——0.2.34+nightly 的「可用」是仿真被优化到可接受,不是原生 int8 落地。事实口径,不展开技术分析。

待验证清单(与锁定表分离,防「锁定=已验证」误读)

  • nightly 2.15.0.dev20260924 是否包含 MPS _int_mm(has_kernel 直测未做)——锁定表锁定的是可用配方,不等于 _int_mm 原生支持已验证
  • Stable Audio 3 成品质量与耗时的正式评估(00 篇已给量级:40 秒 BGM 冷启 10.86 秒)

社区佐证(时效敏感,标查询日期)

  • pytorch #190337("[MPS] Add aten::_int_mm support",2026-07-17 closed):实现未进 2.14.0 正式包——2026-09-25 查询
  • comfy-kitchen issue #92(eager backend 在 MPS 声明 int8 却调 CUDA-only _int_mm):2026-08-30 查询时仍 open,社区讨论 fp32 回退慢的修法——与我们实测一致

统一内存的日志级证据

启动日志里 Total VRAM = Total RAM:M 系列没有独立显存,64GB 统一内存全池可用——这是 00 篇内存墙故事的架构基础,也是 Mac 跑大模型的根本约束与根本优势。

五、验收自检:环境装对了的 5 个标志

装完环境,用五个量级锚点自检(均为本机实测,同硬件量级参考):

  1. 启动日志干净:无 _int_mm / infer_schema 类报错,Total VRAM = Total RAM 行出现
  2. 文生图单张 60 秒量级(1080×1920;实测口径:16 张连跑均值 60 秒,00 篇锚点)
  3. 小图视频 46 s/it 量级(544×960 档;00 篇三档表锚点)
  4. 内存水位正常:H3 全家驻留约 40.5GB(00 篇锚点),不爆 64GB
  5. BGM 10 秒量级出一段(40 秒成品;实测冷启 10.86 秒,00 篇锚点)

五条全过,环境就位。任何一条差出一个数量级,回第二章对锁定表,或回第三章对坑。

下一篇:《02 · 文生图工作流与配图批量实战》——环境装对之后,先把最成熟的模态跑成产线:Z-Image 工作流怎么接、结构化中文提示词怎么写、批量出图怎么管 seed。

参考资料

  • 本系列实测数据底座:测评数据总表与实验日志 03(作者实验日志留存,数据可复现;关键报错与日志片段已在正文逐字引用)
  • ComfyUI 官方仓库 comfyanonymous/ComfyUI(v0.36.0 tag,可搜索)
  • pytorch issue #190337:[MPS] Add aten::_int_mm support(2026-07-17 closed,2026-09-25 查询):pytorch 仓库 issue #190337(可搜索)
  • comfy-kitchen issue #92:MPS int8 eager backend 问题(2026-08-30 查询时 open):comfy-kitchen 仓库 issue #92(可搜索)
  • 00 篇《mac mini 本地 AIGC 实测:图、视频、音乐的真实水位》(已发布)

免责声明

本文内容仅供学习交流,所述方法需结合实际场景灵活运用。环境版本演进很快,本文实测于 2026-09-24~26,读者以此日期为参照核对版本;操作涉及删除环境与安装 nightly 软件包,请自行评估风险。

本文由 AI 辅助创作,经人工审核编辑后发布。

本文首发于微信公众号「羲和Lab」，公众号内可留言交流

阅读公众号原文