ComfyUI Desktop 应用详解 (Beta)

本文档详细介绍了 ComfyUI 桌面应用程序 (Beta) 的使用、安装、开发和故障排除等相关内容。该应用旨在为用户提供一种便捷的方式来使用 ComfyUI，并捆绑了必要的依赖和工具。

什么是 ComfyUI Desktop?

ComfyUI Desktop 是一个将 ComfyUI 打包成桌面应用程序的解决方案，它包含了 ComfyUI 稳定版本、ComfyUI_frontend、ComfyUI-Manager 以及 uv 工具。启动时，它会自动安装 Python 依赖并启动 ComfyUI 服务器，并且会自动更新 ComfyUI、ComfyUI-Manager 和 uv 可执行文件，以及一些桌面专属功能。

用户指南

更详细的用户指南请参考：https://comfyorg.notion.site

如何下载 ComfyUI Desktop?

目前提供以下版本的下载：

• Windows (NVIDIA) NSIS x64: 下载
• macOS ARM: 下载

ComfyUI Desktop 概述

该桌面应用程序捆绑了以下内容：

• ComfyUI 源代码
• ComfyUI-Manager
• Electron、Chromium 二进制文件和 Node 模块

安装的文件位置

Windows

使用 NSIS 安装程序，文件安装位置如下：

• 捆绑资源： %APPDATA%\Local\Programs\comfyui-electron
• 用户文件： %APPDATA%\ComfyUI
• 自动更新： %APPDATA%\Local\comfyui-electron-updater

macOS

应用程序以 DMG 形式分发，文件安装位置如下：

• 用户文件： ~/Library/Application Support/ComfyUI
• 应用程序： /Applications

Linux

文件安装位置如下：

• 用户文件： ~/.config/ComfyUI

ComfyUI 文件存储

用户会被要求选择一个位置来存储 ComfyUI 文件，例如模型、输入、输出、自定义节点和保存的工作流程。这个目录存储在 config.json 的 basePath 键中。

• Windows: %APPDATA%\ComfyUI\config.json
• macOS: ~/Library/Application Support/ComfyUI/config.json
• Linux: ~/.config/ComfyUI/config.json

模型路径

模型路径也存储在 extra_model_config.yaml 文件中，默认情况下，应用程序会在此处查找模型检查点。用户可以通过编辑此文件添加其他模型到搜索路径。

• Windows: %APPDATA%\ComfyUI\extra_model_config.yaml
• macOS: ~/Library/Application Support/ComfyUI/extra_model_config.yaml
• Linux: ~/.config/ComfyUI/extra_model_config.yaml

日志

应用程序使用 electron-log 来记录所有信息。日志文件存储位置如下：

• Electron 主进程日志： main.log
• ComfyUI 服务器日志： comfyui_.log
• Linux: ~/.config/{app name}/logs
• macOS: ~/Library/Logs/{app name}
• Windows: %AppData%\{app name}\logs

开发环境设置

Python 环境

确保安装了 Python 3.12+ 版本，并建议设置虚拟环境。

Linux/macOS:

python -m venv venv
source venv/bin/activate

Windows:

py -3.12 -m venv venv
.\venv\Scripts\Activate.ps1

Windows 开发环境

需要 Visual Studio 2019 或更高版本，并安装 Desktop C++ 工作负载。同时需要 spectre-mitigated 库。

1. 打开 Visual Studio 安装程序。
2. 点击 Visual Studio 2022 Community 安装的 “Modify”（修改）。
3. 转到 “Individual Components”（单个组件）选项卡。
4. 搜索 “Spectre”。
5. 选中与项目架构匹配的 Spectre 缓解库复选框（x86 和/或 x64）。

例如，查找 “MSVC v143 – VS 2022 C++ x64/x86 Spectre-mitigated libs”。如果使用其他工具集，也需要相应的 Spectre 缓解库。

NPM 依赖

推荐使用 nvm 管理 Node 版本，该项目使用 Node v20.x。

Windows:

Microsoft 推荐使用 nvm-windows。

nvm install 20
nvm use 20

该项目使用 yarn 作为包管理器。如果 PATH 中没有 yarn，运行：

corepack enable
yarn set version v4.5.0 # 检查 package.json 中的 packageManager 字段

然后在项目根目录运行：

yarn install

ComfyUI 资源

在启动 Electron 应用前，需要下载 ComfyUI 源代码等资源。使用 comfy-cli 安装：

pip install -U comfy-cli

然后初始化应用资源：

yarn make:assets:[amd|cpu|nvidia|macos]

该命令会在 assets 目录下安装 ComfyUI、ComfyUI-Manager 和前端扩展。版本信息在 package.json 中定义。

还需要安装 uv：

yarn download:uv

启动应用

启动开发服务器：

deactivate # 停用当前的 Python 虚拟环境
yarn start

构建应用

构建平台相关的包和可分发文件：

yarn make

跨平台构建，例如在 Linux 上构建 Windows 版本：

yarn make --windows

故障排除

node-pty 编译错误

如果出现类似 node-pty 编译版本不匹配的错误，使用 electron-rebuild 重建：

npx electron-rebuild

如果失败，尝试：

yarn install -D @electron/rebuild
rm -rf node_modules
rm yarn.lock
yarn install
electron-rebuild

缺少库文件

如果出现缺少 libnss3.so 等库文件的错误，需要安装相应的依赖包。例如，在 Debian/Ubuntu 系统中：

apt-get install libnss3

调试器

.vscode/launch.json 中提供了 VSCode/Cursor 的调试启动脚本。按下 F5 即可启动调试器。

可以在启动环境中自定义设置，例如在 Linux 中调试时加载 ~/.profile：

{
  "version": "2.0.0",
  "tasks": [
    {
      "linux": { "options": { "shell": { "args": ["-ci"] } } }
    }
  ]
}

发布流程

使用 Todesktop 构建和签名发行版。

1. 创建 PR，更新 package.json 中的版本号。
2. 创建 Github Release，使用语义版本标签（例如 v1.0.0）。
3. 确保 Release 是预发布版本。
4. 检查 Github Action “Publish All” 是否运行成功。
5. 测试构建，并在 ToDesktop 上发布，标记为 “Latest”。
6. 如果构建失败，可以通过运行 “Publish All” GH action 并输入发布标签来手动重试。

本地发布

首先按照本地开发环境设置进行配置。

yarn publish # 需要身份验证

实用脚本

package.json 的 scripts 字段中定义了一些实用脚本，例如：

yarn clean # 清理构建工件
yarn:clean:assets # 删除 yarn make:assets 生成的文件
yarn clean:slate # 删除 node_modules

崩溃报告

在首次启动时，用户可以选择是否发送崩溃报告。报告仅包含未处理的异常和本地崩溃的堆栈跟踪。我们使用 Sentry 来发送崩溃报告，不会发送任何个人数据、工作流程或日志。

总结

ComfyUI Desktop 是一款方便用户使用 ComfyUI 的桌面应用程序，它简化了 ComfyUI 的安装和更新过程，并提供了跨平台的支持。该应用的目标用户是希望在桌面环境下使用 ComfyUI，并希望获得良好用户体验的 AI 爱好者和开发者。通过本文档，用户可以了解如何安装、使用和开发这款应用。开发者可以根据文档设置开发环境，并为该项目贡献代码。

#Todesktop