ComfyUI 桌面版

用户指南

请阅读用户指南

下载

Windows (NVIDIA) NSIS x64：下载

macOS ARM：下载

概述

这款桌面应用是以打包形式使用ComfyUI的便捷方式，并附带以下内容：

• 来自发布页面的稳定版 ComfyUI
• ComfyUI_frontend
• ComfyUI-Manager（当设置 --enable-manager 时通过 pip 安装；旧版自定义节点仅针对较旧的 ComfyUI 版本进行克隆）
• uv

启动时，它将使用 uv 安装所有必要的 Python 依赖项，并启动 ComfyUI 服务器。该应用还会自动更新至 ComfyUI、ComfyUI-Manager（pip）和 uv 可执行文件的稳定版本，以及一些桌面专用功能。

开发者请继续阅读。

已安装文件

Electron

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

• ComfyUI 源代码
• ComfyUI-Manager（pip 包或旧版自定义节点，取决于所捆绑的 ComfyUI 版本）
• Electron、Chromium 二进制文件以及 Node.js 模块

Windows

我们使用 NSIS 安装程序 进行 Windows 安装，文件将被安装到以下位置：

捆绑资源：%LOCALAPPDATA%\Programs\ComfyUI

用户文件存储于此：%APPDATA%\ComfyUI

自动更新：%LOCALAPPDATA%\comfyui-electron-updater 或 %LOCALAPPDATA%\@comfyorgcomfyui-electron-updater

macOS

macOS 应用程序以 DMG 格式分发，文件将被安装到：

~/Library/Application Support/ComfyUI

应用程序将被拖放到 /Applications 目录下。

Linux

~/.config/ComfyUI

ComfyUI

系统还会要求您选择一个用于存储 ComfyUI 文件的位置，例如模型、输入、输出、custom_nodes 和已保存的工作流。此目录存储在 config.json 的 basePath 键中。

Windows：%APPDATA%\ComfyUI\config.json

macOS：~/Library/Application Support/ComfyUI\config.json

Linux：~/.config/ComfyUI\config.json

模型路径

此目录也会写入 extra_models_config.yaml 中的 base_path。桌面应用默认会在此处查找模型检查点，但您可以通过编辑此文件来添加额外的模型搜索路径。

Windows：%APPDATA%\ComfyUI\extra_models_config.yaml

macOS：~/Library/Application Support/ComfyUI\extra_models_config.yaml

Linux：~/.config/ComfyUI\extra_models_config.yaml

日志

我们使用 electron-log 记录所有内容。Electron 主进程日志位于 main.log，ComfyUI 服务器日志则位于 comfyui_<date>.log。

Linux：~/.config/{应用名}/logs
macOS：~/Library/Logs/{应用名}
Windows：%AppData%/{应用名}/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

运行 node-gyp 需要 Visual Studio 2019 或更高版本，并安装“桌面 C++”工作负载。请参阅 node-gyp 的Windows 安装说明。此外还需要“缓解幽灵漏洞”的库，可在 VS 安装程序的“单个组件”部分找到。

确认可用的版本：

• Visual Studio Community 2022 - 17.12.1
• 桌面开发与 C++ 工作负载
• MSVC v143 x64 缓解幽灵漏洞的库（最新 / v14.42-17.12）
  • 打开 Visual Studio 安装程序
  • 点击您的 Visual Studio 2022 Community 安装中的“修改”
  • 转到“单个组件”选项卡
  • 搜索“幽灵”
  • 勾选与您项目架构匹配的缓解幽灵漏洞的库（x86 和/或 x64）
  • 

寻找“MSVC v143 - VS 2022 C++ x64/x86 缓解幽灵漏洞的库”。如果您使用其他工具集，可能还需要相应的缓解幽灵漏洞的库。

NPM 依赖

Node

我们建议使用 nvm 来管理 Node.js 版本。本项目使用 Node v20.x。

Windows

微软在其Node.js on Windows 页面上推荐使用 nvm-windows。

nvm install 20
nvm use 20

Yarn

本项目使用 yarn 作为包管理器。如果您尚未在 PATH 中拥有 yarn 可执行文件，请运行：

# corepack 是包含在所有最新 Node.js 发行版中的实用工具集
corepack enable
yarn set version 4.5.0 # 请查看 package.json 中的 packageManager 键以获取确切版本。

这将安装一个可用的 yarn 可执行文件。然后，在本仓库的根目录下（即顶级 package.json 文件旁边），运行：

yarn install

ComfyUI 资源

在启动 Electron 应用程序之前，您需要下载 ComfyUI 源代码以及其他通常随应用捆绑的内容。

ComfyUI 和其他依赖项

首先，通过运行 yarn make:assets 初始化应用资源：

此命令会将 ComfyUI 安装到 assets/ 目录下。如果所捆绑的 ComfyUI 版本包含 manager_requirements.txt，ComfyUI-Manager 将在运行时通过 pip 安装；否则将克隆旧版自定义节点以保持兼容性。每个包的具体版本在 package.json 中定义。

随后您可以运行 start 来构建并启动应用。同时会启动一个监视器，当源文件发生更改时，它会自动重新构建应用：

deactivate # 关闭现有 Python 环境，以免影响
yarn start

您还可以使用 make 命令构建软件包和/或可分发文件：

# 构建平台特定的软件包及任何可分发文件
yarn make
# 构建跨平台版本，例如从 Linux 构建 Windows 版本
yarn make --windows

编译后的依赖项

关于如何生成编译后依赖项的权威信息，位于 .compiled 文件的头部注释中。请参阅 assets/requirements/*.compiled，了解实际使用的具体命令和覆盖设置。

故障排除

如果你遇到类似以下的错误：

模块 '/electron/node_modules/node-pty/build/Release/pty.node' 是使用 NODE_MODULE_VERSION 115 编译的，而当前 Node.js 版本需要 NODE_MODULE_VERSION 125。请尝试重新编译或重新安装该模块（例如使用 `npm rebuild` 或 `npm install`）。

你需要使用 electron-rebuild 重新构建 node-pty，例如：

npx electron-rebuild

如果上述方法失败，可以尝试：

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

缺少库文件

如果你的发行版未包含 Electron 的先决条件，可能会出现无法找到 libnss3.so 等库文件的错误。请查找适合你发行版的正确软件包并进行安装。

以 apt 为例：

apt-get install libnss3

调试器

在 .vscode/launch.json 中提供了适用于 VSCode 和 Cursor 的调试启动脚本。默认的启动脚本会运行项目根目录下的 Electron 启动脚本，并附加调试器。默认情况下，使用此脚本时不会构建应用。

在 VSCode 或其衍生编辑器中按下 F5 键即可运行默认的启动脚本。按 Ctrl + Shift + F5 可以在附加调试器的情况下重启应用。按 Shift + F5 则会终止调试器及其所附加的进程树。

为了在修改代码时保持应用始终处于最新状态并持续构建，可以运行定义在 .vscode/tasks.json 中的 Start Vite Build Watchers 构建任务。该任务会启动两个监视任务：一个用于主应用，另一个用于预加载脚本。当源文件发生更改时，这些监视器将自动重新构建应用。

启动环境可以自定义，例如，在 Linux 环境下调试时，添加 "linux" 部分以加载 ~/.profile（以及其他交互式配置）：

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

打包后应用的故障排除

当应用被打包为生产版本时，它会忽略用于配置开发环境的环境变量。若希望在打包状态下强制读取环境变量，可以在启动应用时使用 --dev-mode 命令行参数。

发布

我们使用 Todesktop 来构建和对分发包进行代码签名。要发布新版本，请按照以下步骤操作：

1. 创建一个 PR，将 package.json 更新到下一个版本。
2. 在 GitHub 上创建一个语义版本标签的发布，例如 “v1.0.0”。
3. 确保将其标记为预发布版本。
4. 检查名为 “Publish All” 的 GitHub Actions 是否已成功运行。完成后，该动作应更新发布说明中的下载链接。
5. 测试构建结果，确认无误后在 Todesktop 上正式发布，并将该版本标记为 “Latest”。

如果构建因故失败，可以通过手动触发 “Publish All” GH Action，并传入发布标签来重试。

使用 Claude Code 进行发布

Claude Code 提供了一个名为 “bump-stable” 的命令，可用于自动化发布流程。

更新已编译依赖项

向开放的 PR 添加 “Update Compiled Requirements” 标签，即可自动更新已编译的依赖项。如果有更改，该动作会将更新后的文件提交到 PR 中。

工具脚本

package.json 的 scripts 字段中定义了许多实用脚本。例如，清理构建产物时可以运行以下命令：

yarn clean

# 移除由 yarn make:assets 创建的文件
yarn clean:assets

# clean:slate 还会移除 node_modules 目录
yarn clean:slate

崩溃报告与指标

在首次使用时，你可以选择加入使用情况数据收集计划。这有助于我们更好地优先处理问题，并合理分配有限的开发资源。有关隐私政策的详细信息，请参阅 此处。

你也可以随时通过设置菜单退出数据收集，退出后将不再发送任何数据。

无论是否参与数据收集，都不会发送任何个人数据、工作流或日志信息。

ComfyUI Desktop 快速上手指南

ComfyUI Desktop 是 ComfyUI 的官方桌面客户端，集成了稳定的 ComfyUI 核心、前端界面、管理器（Manager）以及依赖管理工具 uv。它支持自动更新，并简化了环境配置流程。

1. 环境准备

系统要求

• 操作系统：
  • Windows (x64, 推荐 NVIDIA 显卡)
  • macOS (ARM 架构，如 M1/M2/M3)
  • Linux (主流发行版)
• 硬件建议：具备独立显卡（GPU）以获得最佳生成速度。

前置依赖（仅开发者模式需要）

如果您仅使用打包好的应用程序，无需安装以下依赖。仅在需要修改源码或二次开发时准备：

• Python: 3.12 或更高版本
• Node.js: v20.x (推荐使用 nvm 管理)
• Yarn: v4.5.0+
• Windows 额外要求: Visual Studio 2019+ (需安装 "Desktop C++" 工作负载及 Spectre-mitigated 库)

2. 安装步骤

方式一：直接使用安装包（推荐普通用户）

访问官方下载页面或直接使用以下链接下载安装包：

• Windows (NVIDIA): 下载 NSIS x64 安装包
• macOS (ARM): 下载 DMG 安装包
• Linux: 请参考 GitHub Releases 页面获取对应构建版本。

安装流程：

1. 运行下载的安装程序。
2. Windows: 默认安装资源至 %LOCALAPPDATA%\Programs\ComfyUI，用户数据（模型、工作流等）将存储在 %APPDATA%\ComfyUI。
3. macOS: 将应用拖入 /Applications 文件夹，用户数据存储在 ~/Library/Application Support/ComfyUI。
4. 启动应用，首次运行时会自动通过 uv 安装必要的 Python 依赖并启动服务。

方式二：源码开发与构建（仅限开发者）

如果您需要定制功能或贡献代码，请按以下步骤操作：

1. 设置 Python 虚拟环境

# Linux/MacOS
python -m venv venv
source venv/bin/activate

# Windows (PowerShell)
py -3.12 -m venv venv
.\venv\Scripts\Activate.ps1

2. 安装 Node 依赖

建议使用 nvm 切换至 Node v20：

nvm install 20
nvm use 20

# 启用 corepack 并设置 Yarn 版本
corepack enable
yarn set version 4.5.0

# 安装项目依赖
yarn install

3. 初始化 ComfyUI 资源

下载 ComfyUI 源码及相关资产：

yarn make:assets

4. 启动开发服务器

此命令会构建应用并启动监听器，源码变动时自动重载：

# 建议先退出当前的 python 虚拟环境以避免干扰，或者确保环境干净
deactivate 
yarn start

5. 构建发布包（可选）

# 构建当前平台包
yarn make

# 跨平台构建 (例如在 Linux 上构建 Windows 版)
yarn make --windows

3. 基本使用

1. 启动应用：

   • 安装版：直接点击桌面快捷方式或应用程序图标。
   • 开发版：运行 yarn start 后自动弹出窗口。

2. 配置模型路径：

   • 首次启动时，系统会提示您选择一个目录用于存储模型（Checkpoints）、输入/输出文件、自定义节点和工作流。
   • 该路径被记录在配置文件中：
     • Windows: %APPDATA%\ComfyUI\config.json
     • macOS: ~/Library/Application Support/ComfyUI/config.json
     • Linux: ~/.config/ComfyUI/config.json
   • 如需添加额外的模型搜索路径，可编辑同目录下的 extra_models_config.yaml 文件。

3. 开始创作：

   • 应用启动后会自动打开浏览器窗口（或内置 WebView）加载 ComfyUI 前端界面。
   • 您可以直接加载默认工作流，或通过 ComfyUI Manager 安装新的自定义节点。
   • 所有生成的图片和日志默认保存在您设定的用户数据目录中。

4. 查看日志：

   • 如遇问题，可查看日志文件定位原因：
     • 主进程日志：main.log
     • ComfyUI 服务日志：comfyui_<日期>.log
   • 日志存放位置：
     • Windows: %AppData%\{app name}\logs
     • macOS: ~/Library/Logs/{app name}
     • Linux: ~/.config/{app name}/logs