diff --git a/images/troubleshooting/custom_node_type.jpg b/images/troubleshooting/custom_node_type.jpg
new file mode 100644
index 00000000..34afec2f
Binary files /dev/null and b/images/troubleshooting/custom_node_type.jpg differ
diff --git a/images/troubleshooting/disable_3rd_party.jpg b/images/troubleshooting/disable_3rd_party.jpg
new file mode 100644
index 00000000..da4b1c87
Binary files /dev/null and b/images/troubleshooting/disable_3rd_party.jpg differ
diff --git a/images/troubleshooting/enable_extensions.jpg b/images/troubleshooting/enable_extensions.jpg
new file mode 100644
index 00000000..1406a9d2
Binary files /dev/null and b/images/troubleshooting/enable_extensions.jpg differ
diff --git a/images/zh/troubleshooting/custom_node_type.jpg b/images/zh/troubleshooting/custom_node_type.jpg
new file mode 100644
index 00000000..6c9eb55d
Binary files /dev/null and b/images/zh/troubleshooting/custom_node_type.jpg differ
diff --git a/images/zh/troubleshooting/disable_3rd_party.jpg b/images/zh/troubleshooting/disable_3rd_party.jpg
new file mode 100644
index 00000000..24d9c43a
Binary files /dev/null and b/images/zh/troubleshooting/disable_3rd_party.jpg differ
diff --git a/troubleshooting/custom-node-issues.mdx b/troubleshooting/custom-node-issues.mdx
index f7e78cba..a8d75131 100644
--- a/troubleshooting/custom-node-issues.mdx
+++ b/troubleshooting/custom-node-issues.mdx
@@ -5,275 +5,356 @@ icon: "puzzle-piece"
sidebarTitle: "Custom Node Issues"
---
-## Quick Issue Diagnosis
-
-If you're experiencing any of these issues, there is a high likelihood that it is caused by custom nodes:
-- ComfyUI crashes or won't start
-- "Failed to import" errors in console/logs
-- UI completely breaks or shows blank screen
-- "Prompt execution failed" errors not related to memory issues
-- Missing nodes that should be available/installed
-
-## Is It a Custom Node Problem?
-
-Most ComfyUI issues are caused by custom nodes (extensions). Let's check if this is the case.
-
-### Step 1: Test with all custom nodes disabled
-
-Run ComfyUI with all custom nodes disabled:
-
-
-
-Start ComfyUI Desktop with custom nodes disabled from the settings menu
-
-
-
-or run the server manually:
-
-```bash
-cd path/to/your/comfyui
-python main.py --disable-all-custom-nodes
-```
-
-
-```bash
-cd ComfyUI
-python main.py --disable-all-custom-nodes
-```
-
-
-
-
- Open the folder where the portable version is located, and find the `run_nvidia_gpu.bat` or `run_cpu.bat` file
-
- 
- 1. Copy `run_nvidia_gpu.bat` or `run_cpu.bat` file and rename it to `run_nvidia_gpu_disable_custom_nodes.bat`
- 2. Open the copied file with Notepad
- 3. Add the `--disable-all-custom-nodes` parameter to the file, or copy the parameters below into a `.txt` file and rename the file to `run_nvidia_gpu_disable_custom_nodes.bat`
-
- ```bash
- .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes --windows-standalone-build
- pause
- ```
- 4. Save the file and close it
- 5. Double-click the file to run it. If everything is normal, you should see ComfyUI start and custom nodes disabled
-
-
- 
- 1. Enter the folder where the portable version is located
- 2. Open the terminal by right-clicking the menu → Open terminal
-
- 
-
- 3. Ensure that the folder name is the current directory of the portable version
- 4. Enter the following command to start ComfyUI through the portable python and disable custom nodes
- ```
- .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
- ```
-
-
-
-
-
-**Results:**
-- ✅ **Issue disappears**: A custom node is causing the problem → Continue to Step 2
-- ❌ **Issue persists**: Not a custom node issue → [Report the issue](#reporting-issues)
-
-### Step 2: Find the Problematic Custom Node
-
-We'll use **binary search** to quickly find which custom node is causing issues. This is much faster than testing nodes one by one.
-
-#### Option A: Using Comfy CLI (Recommended)
-
-If you have [Comfy CLI](/comfy-cli/getting-started) installed, you can use the automated bisect tool to find the problematic node:
-
-```bash
-# Start a bisect session
-comfy-cli node bisect start
-
-# Follow the prompts:
-# - Test ComfyUI with the current set of enabled nodes
-# - Mark as 'good' if the issue is gone: comfy-cli node bisect good
-# - Mark as 'bad' if the issue persists: comfy-cli node bisect bad
-# - Repeat until the problematic node is identified
-
-# Reset when done
-comfy-cli node bisect reset
-```
-
-The bisect tool will automatically enable/disable nodes and guide you through the process.
-
-#### Option B: Manual Binary Search
-
-If you prefer to do the process manually or don't have Comfy CLI installed, follow the steps below:
-
-#### How Binary Search Works
-
-Instead of testing each node individually (which could take hours), we split the nodes in half repeatedly:
+Here is the overall approach for troubleshooting custom node issues:
+
+ ```mermaid
+ flowchart TD
+ A[Issue Encountered] --> B{Does the issue disappear after disabling all custom nodes?}
+ B -- Yes --> C[Issue caused by custom nodes]
+ B -- No --> D[Issue not caused by custom nodes, refer to other troubleshooting docs]
+ C --> E{Check frontend extensions first?}
+ E -- Yes --> F[Troubleshoot in ComfyUI frontend]
+ E -- No --> G[Use general binary search method]
+ F --> H[Use binary search to locate problematic node]
+ G --> H
+ H --> I[Fix, replace, report or remove problematic node]
+ I --> J[Issue solved]
```
-8 nodes → Test 4 nodes → Test 2 nodes → Test 1 node ✓
-
-Example with 8 nodes:
-1. Test nodes 1-4: Issue persists ✓ → Problem in remaining nodes 5-8
-2. Test nodes 5-6: Issue gone ✓ → Problem in nodes 7-8
-3. Test node 7: Issue persists ✓ → Node 7 is the problem!
-This takes only 3 tests instead of testing all 8 nodes individually.
+## How to determine if custom nodes are causing the issue?
+
+If the problem disappears after disabling all custom nodes, we can determine that the issue is caused by custom nodes.
+
+### Binary search troubleshooting approach
+
+In this document, we will introduce the binary search approach for troubleshooting custom node issues, which involves checking half of the custom nodes at a time until we locate the problematic node.
+
+Please refer to the flowchart below for the specific approach - enable half of the currently disabled nodes each time and check if the issue appears, until we identify which custom node is causing the issue
+
+```mermaid
+flowchart TD
+ A[Start] --> B{Split all custom nodes in half}
+ B --> C[Enable first half of custom nodes]
+ C --> D[Restart ComfyUI and test]
+ D --> E{Does the issue appear?}
+ E --> |Yes| F[Issue is in enabled custom nodes]
+ E --> |No| G[Issue is in disabled custom nodes]
+ F --> H{Enabled custom nodes > 1?}
+ G --> I{Disabled custom nodes > 1?}
+ H --> |Yes| J[Continue binary search on enabled nodes]
+ I --> |Yes| K[Continue binary search on disabled nodes]
+ H --> |No| L[Found problematic custom node]
+ I --> |No| L
+ J --> B
+ K --> B
+ L --> M[End]
```
+## Different Troubleshooting Methods for Different Types of Custom Node Issues
-#### Binary Search Process
+In this document, we categorize custom nodes into two types for troubleshooting:
-
-Before starting, **create a backup** of your custom_nodes folder in case something goes wrong.
-
+
+- A: Custom nodes with frontend extensions
+- B: Regular custom nodes
-##### Create Temporary Folders
+Let's first understand the potential issues and causes for different types of custom nodes:
-
-```bash
-# Create backup and temporary folder
-mkdir "%USERPROFILE%\custom_nodes_backup"
-mkdir "%USERPROFILE%\custom_nodes_temp"
-
-# Backup everything first
-xcopy "custom_nodes\*" "%USERPROFILE%\custom_nodes_backup\" /E /H /Y
-```
-
-
-```bash
-# Create backup and temporary folder
-mkdir ~/custom_nodes_backup
-mkdir ~/custom_nodes_temp
-
-# Backup everything first
-cp -r custom_nodes/* ~/custom_nodes_backup/
-```
-
-
-```bash
-# Create backup and temporary folder
-mkdir /content/custom_nodes_backup
-mkdir /content/custom_nodes_temp
-
-# Backup everything first
-cp -r /content/ComfyUI/custom_nodes/* /content/custom_nodes_backup/
-```
-
-
-
-##### Find the Problematic Node
-
-1. **List your custom nodes:**
-
-
- ```bash
- dir custom_nodes
- ```
-
-
- ```bash
- ls custom_nodes/
- ```
-
-
- ```bash
- ls /content/ComfyUI/custom_nodes/
- ```
-
-
-
-2. **Split nodes in half:**
+
+ For custom nodes, we need to prioritize troubleshooting those with frontend extensions, as they cause the most issues. Their main conflicts arise from incompatibilities with ComfyUI frontend version updates.
- Let's say you have 8 custom nodes. Move the first half to temporary storage:
-
-
-
- ```bash
- # Move first half (nodes 1-4) to temp
- move "custom_nodes\node1" "%USERPROFILE%\custom_nodes_temp\"
- move "custom_nodes\node2" "%USERPROFILE%\custom_nodes_temp\"
- move "custom_nodes\node3" "%USERPROFILE%\custom_nodes_temp\"
- move "custom_nodes\node4" "%USERPROFILE%\custom_nodes_temp\"
- ```
-
-
- ```bash
- # Move first half (nodes 1-4) to temp
- mv custom_nodes/node1 ~/custom_nodes_temp/
- mv custom_nodes/node2 ~/custom_nodes_temp/
- mv custom_nodes/node3 ~/custom_nodes_temp/
- mv custom_nodes/node4 ~/custom_nodes_temp/
- ```
+ Common issues include:
+ - Workflows not executing
+ - Some nodes can't show preview images(such as save image node)
+ - Misaligned UI elements
+ - Unable to access ComfyUI frontend
+ - Completely broken UI or blank screen
+ - Unable to communicate normally with ComfyUI backend
+ - Node connections not working properly
+ - And more
+
+ Common causes for these issues:
+ - Frontend modifications during updates that custom nodes haven't adapted to yet
+ - Users updating ComfyUI without synchronously upgrading custom nodes, even though authors have released compatible versions
+ - Authors stopping maintenance, leading to incompatibility between custom node extensions and the ComfyUI frontend
+
-
- ```bash
- # Move first half (nodes 1-4) to temp
- mv /content/ComfyUI/custom_nodes/node1 /content/custom_nodes_temp/
- mv /content/ComfyUI/custom_nodes/node2 /content/custom_nodes_temp/
- mv /content/ComfyUI/custom_nodes/node3 /content/custom_nodes_temp/
- mv /content/ComfyUI/custom_nodes/node4 /content/custom_nodes_temp/
- ```
+
+ If the problem isn't caused by frontend extensions, issues often relate to dependencies. Common problems include:
+ - "Failed to import" errors in console/logs
+ - Missing nodes still showing as missing after installation and restart
+ - ComfyUI crashes or fails to start
+ - And more
+
+ Common causes for these errors:
+ - Custom nodes requiring additional wheels like ComfyUI-Nunchaku
+ - Custom nodes using strict dependency versions (e.g., `torch==2.4.1`) while other plugins use different versions (e.g., `torch>=2.4.2`), causing conflicts after installation
+ - Network issues preventing successful dependency installation
+
+ When problems involve Python environment interdependencies and versions, troubleshooting becomes more complex and requires knowledge of Python environment management, including how to install and uninstall dependencies
-
-
-3. **Test ComfyUI:**
- ```bash
- python main.py
- ```
-
-4. **Interpret results:**
- - **Issue persists**: Problem is in the remaining nodes (5-8)
- - **Issue gone**: Problem was in the moved nodes (1-4)
-
-5. **Narrow it down:**
- - If issue persists: Move half of remaining nodes (e.g., nodes 7-8) to temp
- - If issue gone: Move half of temp nodes (e.g., nodes 3-4) back to custom_nodes
-
-6. **Repeat until you find the single problematic node**
-
-#### Visual Example
-
-Let's walk through a complete example with 8 custom nodes:
-
-```
-📁 custom_nodes/
-├── 🔧 ComfyUI-Manager
-├── 🎨 ComfyUI-Custom-Scripts
-├── 🖼️ ComfyUI-Impact-Pack
-├── 🔄 ComfyUI-Workflow-Component
-├── 📊 ComfyUI-AnimateDiff-Evolved
-├── 🎭 ComfyUI-FaceRestore
-├── ⚡ ComfyUI-Advanced-ControlNet
-└── 🛠️ ComfyUI-Inspire-Pack
-```
-
-**Round 1:** Move first 4 to temp
-- Test → Issue persists ✓
-- Problem is in: ComfyUI-AnimateDiff-Evolved, ComfyUI-FaceRestore, ComfyUI-Advanced-ControlNet, ComfyUI-Inspire-Pack
-
-**Round 2:** Move 2 of the remaining 4 to temp
-- Test → Issue gone ✓
-- Problem is in: ComfyUI-Advanced-ControlNet, ComfyUI-Inspire-Pack
-
-**Round 3:** Move 1 of the remaining 2 to temp
-- Test → Issue persists ✓
-- **Found it!** ComfyUI-Inspire-Pack is the problematic node
+
-### Step 3: Fix the Issue
+## Using Binary Search for Troubleshooting
+
+Among these two different types of custom node issues, conflicts between custom node frontend extensions and ComfyUI are more common. We'll prioritize troubleshooting these nodes first. Here's the overall troubleshooting approach:
+
+### 1. Troubleshooting Custom Nodes with Frontend Extensions
+
+
+
+ 
+ After starting ComfyUI, find the `Extensions` menu in settings and follow the steps shown in the image to disable all third-party extensions
+
+ If you can't enter ComfyUI frontend, just skip the frontend extensions troubleshooting section and continue to [General Custom Node Troubleshooting Approach](#2-general-custom-node-troubleshooting-approach)
+
+
+
+ After disabling frontend extensions for the first time, it's recommended to restart ComfyUI to ensure all frontend extensions are properly disabled
+ - If the problem disappears, then it was caused by custom node frontend extensions, and we can proceed with binary search troubleshooting
+ - If the problem persists, then it's not caused by frontend extensions - please refer to the other troubleshooting approaches in this document
+
+
+ Use the method mentioned at the beginning of this document to troubleshoot, enabling half of the custom nodes at a time until you find the problematic node
+ 
+ Refer to the image to enable half of the frontend extensions. Note that if extension names are similar, they likely come from the same custom node's frontend extensions
+
+
+ If you find the problematic custom node, please refer to the problem fixing section of this document to resolve the custom node issues
+
+
+
+Using this method, you don't need to restart ComfyUI multiple times - just reload ComfyUI after enabling/disabling custom node frontend extensions. Plus, your troubleshooting scope is limited to nodes with frontend extensions, which greatly narrows down the search range.
+
+### 2. General Custom Node Troubleshooting Approach
+
+
+
+
+
+
+ Start ComfyUI Desktop with custom nodes disabled from the settings menu
+
+ 
+
+ or run the server manually:
+
+ ```bash
+ cd path/to/your/comfyui
+ python main.py --disable-all-custom-nodes
+ ```
+
+
+ ```bash
+ cd ComfyUI
+ python main.py --disable-all-custom-nodes
+ ```
+
+
+
+
+ Open the folder where the portable version is located, and find the `run_nvidia_gpu.bat` or `run_cpu.bat` file
+
+ 
+ 1. Copy `run_nvidia_gpu.bat` or `run_cpu.bat` file and rename it to `run_nvidia_gpu_disable_custom_nodes.bat`
+ 2. Open the copied file with Notepad
+ 3. Add the `--disable-all-custom-nodes` parameter to the file, or copy the parameters below into a `.txt` file and rename the file to `run_nvidia_gpu_disable_custom_nodes.bat`
+
+ ```bash
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes --windows-standalone-build
+ pause
+ ```
+ 4. Save the file and close it
+ 5. Double-click the file to run it. If everything is normal, you should see ComfyUI start and custom nodes disabled
+
+
+ 
+ 1. Enter the folder where the portable version is located
+ 2. Open the terminal by right-clicking the menu → Open terminal
+
+ 
+
+ 3. Ensure that the folder name is the current directory of the portable version
+ 4. Enter the following command to start ComfyUI through the portable python and disable custom nodes
+ ```
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
+ ```
+
+
+
+
+
+
+ **Results:**
+ - ✅ **Issue disappears**: A custom node is causing the problem → Continue to Step 2
+ - ❌ **Issue persists**: Not a custom node issue → [Report the issue](#reporting-issues)
+
+
+
+ For the binary search localization method, in addition to manual search, we also have automated binary search using comfy-cli, as detailed below:
+
+
+
+ Using Comfy CLI requires some command line experience. If you're not comfortable with it, use manual binary search instead.
+
+ If you have [Comfy CLI](/comfy-cli/getting-started) installed, you can use the automated bisect tool to find the problematic node:
+
+ ```bash
+ # Start a bisect session
+ comfy-cli node bisect start
+
+ # Follow the prompts:
+ # - Test ComfyUI with the current set of enabled nodes
+ # - Mark as 'good' if the issue is gone: comfy-cli node bisect good
+ # - Mark as 'bad' if the issue persists: comfy-cli node bisect bad
+ # - Repeat until the problematic node is identified
+
+ # Reset when done
+ comfy-cli node bisect reset
+ ```
+
+ The bisect tool will automatically enable/disable nodes and guide you through the process.
+
+
+
+
+ Before starting, please **create a backup** of your custom_nodes folder in case something goes wrong.
+
+
+ If you prefer to do the process manually or don't have Comfy CLI installed, follow the steps below:
+
+
+
+ Before starting, enter the `\ComfyUI\` folder
+
+
+ - **Backup all custom nodes**: Copy and rename `custom_nodes` to `custom_nodes_backup`
+ - **Create a temporary folder**: Create a folder named `custom_nodes_temp`
+
+ Or use the following command line to backup:
+
+ ```bash
+ # Create backup and temporary folder
+ mkdir "%USERPROFILE%\custom_nodes_backup"
+ mkdir "%USERPROFILE%\custom_nodes_temp"
+
+ # Backup all content
+ xcopy "custom_nodes\*" "%USERPROFILE%\custom_nodes_backup\" /E /H /Y
+ ```
+
+
+ Manually backup custom_nodes folder
+ Or use the following command line to backup:
+ ```bash
+ # Create backup and temporary folder
+ mkdir ~/custom_nodes_backup
+ mkdir ~/custom_nodes_temp
+
+ # Backup all content
+ cp -r custom_nodes/* ~/custom_nodes_backup/
+ ```
+
+
+ ```bash
+ # Create backup and temporary folder
+ mkdir /content/custom_nodes_backup
+ mkdir /content/custom_nodes_temp
+
+ # Backup all content
+ cp -r /content/ComfyUI/custom_nodes/* /content/custom_nodes_backup/
+ ```
+
+
+
+
+
+
+ Since Windows has a visual interface, you can skip this step unless you're only using the command line
+ ```bash
+ dir custom_nodes
+ ```
+
+
+ ```bash
+ ls custom_nodes/
+ ```
+
+
+ ```bash
+ ls /content/ComfyUI/custom_nodes/
+ ```
+
+
+
+
+ Let's assume that you have 8 custom nodes. Move the first half to temporary storage:
+
+
+ ```bash
+ # Move first half (nodes 1-4) to temp
+ move "custom_nodes\node1" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node2" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node3" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node4" "%USERPROFILE%\custom_nodes_temp\"
+ ```
+
+
+ ```bash
+ # Move first half (nodes 1-4) to temp
+ mv custom_nodes/node1 ~/custom_nodes_temp/
+ mv custom_nodes/node2 ~/custom_nodes_temp/
+ mv custom_nodes/node3 ~/custom_nodes_temp/
+ mv custom_nodes/node4 ~/custom_nodes_temp/
+ ```
+
+
+ ```bash
+ # Move first half (nodes 1-4) to temp
+ mv /content/ComfyUI/custom_nodes/node1 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node2 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node3 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node4 /content/custom_nodes_temp/
+ ```
+
+
+
+
+ Start ComfyUI normally
+ ```bash
+ python main.py
+ ```
+
+
+ - **Issue persists**: Problem is in the remaining nodes (5-8)
+ - **Issue disappears**: Problem was in the moved nodes (1-4)
+
+
+ - If issue persists: Move half of remaining nodes (e.g., nodes 7-8) to temp
+ - If issue gone: Move half of temp nodes (e.g., nodes 3-4) back to custom_nodes
+
+
+ - Repeat until you find the single problematic node
+
+
+
+
+
+
+
+## How to Fix the Issue
Once you've identified the problematic custom node:
-#### Option 1: Update the Node
+### Option 1: Update the Node
1. Check if there's an update available in ComfyUI Manager
2. Update the node and test again
-#### Option 2: Replace the Node
+### Option 2: Replace the Node
1. Look for alternative custom nodes with similar functionality
2. Check the [ComfyUI Registry](https://registry.comfy.org) for alternatives
-#### Option 3: Report the Issue
+### Option 3: Report the Issue
Contact the custom node developer:
1. Find the node's GitHub repository
2. Create an issue with:
@@ -282,7 +363,7 @@ Contact the custom node developer:
- Steps to reproduce
- Your operating system
-#### Option 4: Remove or Disable the Node
+### Option 4: Remove or Disable the Node
If no fix is available and you don't need the functionality:
1. Remove the problematic node from `custom_nodes/` or disable it in the ComfyUI Manager interface
2. Restart ComfyUI
diff --git a/zh-CN/troubleshooting/custom-node-issues.mdx b/zh-CN/troubleshooting/custom-node-issues.mdx
index 70e65d7f..417503f8 100644
--- a/zh-CN/troubleshooting/custom-node-issues.mdx
+++ b/zh-CN/troubleshooting/custom-node-issues.mdx
@@ -5,276 +5,349 @@ icon: "puzzle-piece"
sidebarTitle: "自定义节点问题"
---
-## 快速问题诊断
-
-如果你遇到以下任何问题，很可能是由自定义节点引起的：
-- ComfyUI 崩溃或无法启动
-- 控制台/日志中出现"Failed to import"（导入失败）错误
-- UI 完全损坏或显示空白屏幕
-- "Prompt execution failed"（提示执行失败）错误
-- 应该可用的节点丢失
-
-## 这是自定义节点问题吗？
-
-大多数 ComfyUI 问题都是由自定义节点（扩展）引起的。让我们检查是否是这种情况。
-
-### 步骤 1：禁用所有自定义节点后测试
-
-在禁用所有自定义节点的情况下运行 ComfyUI：
-
-
-
-从设置菜单中启动禁用自定义节点的 ComfyUI 桌面版
-
-
-
-或手动运行服务器：
-
-```bash
-cd path/to/your/comfyui
-python main.py --disable-all-custom-nodes
-```
-
-
-```bash
-cd ComfyUI
-python main.py --disable-all-custom-nodes
+关于自定义节点问题排查，本篇文档的总体思路如下：
+
+ ```mermaid
+ flowchart TD
+ A[遇到问题] --> B{禁用所有自定义节点后问题是否消失？}
+ B -- 是 --> C[问题由自定义节点引起]
+ B -- 否 --> D[问题不是自定义节点引起，参考其他排查文档]
+ C --> E{是否先排查前端扩展？}
+ E -- 是 --> F[在ComfyUI前端进行排查]
+ E -- 否 --> G[使用通用的二分法进行排查]
+ F --> H[使用二分法定位有问题的节点]
+ G --> H
+ H --> I[修复、替换、报告或移除有问题的节点]
+ I --> J[问题解决]
```
-
-
-
-
-
- 打开便携版所在的文件夹，找到 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件
-
- 
- 1. 复制 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件并重命名为 `run_nvidia_gpu_disable_custom_nodes.bat`
- 2. 使用记事本打开复制后的文件
- 3. 在文件中添加 `--disable-all-custom-nodes` 参数，或者复制下面的参数保存到 txt 文件中后将文件后缀名改为 `.bat`
-
- ```bash
- .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes --windows-standalone-build
- pause
- ```
- 4. 保存文件并关闭
- 5. 双击运行文件，如果一切正常，你应该会看到 ComfyUI 启动，并且自定义节点被禁用
-
-
- 
- 1. 进入便携版所在的文件夹
- 2. 通过右键菜单 → 打开终端 来打开命令行
-
- 
-
- 3. 确保在命令行中文件夹名称是当前便携版所在的文件目录
- 4. 输入以下命令,来通过便携版的 python 来启动 ComfyUI 并禁用自定义节点
- ```
- .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
- ```
-
-
-
-
-**结果：**
-- ✅ **问题消失**：自定义节点导致问题 → 继续步骤 2
-- ❌ **问题仍然存在**：不是自定义节点问题 → [报告问题](#报告问题)
-
-### 步骤 2：找到有问题的自定义节点
-
-我们将使用**二分搜索**快速找到哪个自定义节点导致问题。这比逐个测试节点要快得多。
-
-#### 选项 A：使用 Comfy CLI（推荐）
-
-如果你已安装 [Comfy CLI](/zh-CN/comfy-cli/getting-started)，可以使用自动化的二分工具来找到有问题的节点：
-
-```bash
-# 开始二分会话
-comfy-cli node bisect start
-
-# 按照提示操作：
-# - 使用当前启用的节点集测试 ComfyUI
-# - 如果问题消失，标记为 'good'：comfy-cli node bisect good
-# - 如果问题仍然存在，标记为 'bad'：comfy-cli node bisect bad
-# - 重复直到识别出有问题的节点
-
-# 完成后重置
-comfy-cli node bisect reset
+## 如何确定是不是自定义节点导致的问题？
+
+如果禁用所有自定义节点后问题消失，那么我们可以定位这个问题是由自定义节点引起的。
+
+### 二分法排查思路
+
+在本篇中我们将会介绍使用二分搜索来进行自定义节点问题排查的思路，也就是一次排查一半的自定义节点，直到定位到导致问题的自定义节点
+
+具体思路清参考下面的流程图，即每次启用所有未启用节点的一半，看看对应的问题是否出现，直到定位到对应的自定义节点是哪个
+
+```mermaid
+flowchart TD
+ A[开始] --> B{将所有自定义节点分成两半}
+ B --> C[启用前半部分自定义节点]
+ C --> D[重启ComfyUI测试]
+ D --> E{问题是否出现?}
+ E --> |是| F[问题在已启用自定义节点中]
+ E --> |否| G[问题在未启用自定义节点中]
+ F --> H{已启用自定义节点>1个?}
+ G --> I{未启用自定义节点>1个?}
+ H --> |是| J[继续二分已启用自定义节点]
+ I --> |是| K[继续二分未启用自定义节点]
+ H --> |否| L[找到问题自定义节点]
+ I --> |否| L
+ J --> B
+ K --> B
+ L --> M[结束]
```
-二分工具将自动启用/禁用节点并引导你完成整个过程。
+## 根据不同的自定义节点问题类型使用不同的排查方法
-#### 选项 B：手动二分搜索
+在本篇文档中，我们将排查的自定义节点分为两类
-如果你更喜欢手动操作或没有安装 Comfy CLI，请按照以下步骤操作：
-
-#### 二分搜索的工作原理
-
-我们不是逐个测试每个节点（可能需要几个小时），而是反复将节点分成两半：
-
-```
-8 个节点 → 测试 4 个节点 → 测试 2 个节点 → 测试 1 个节点 ✓
-
-8 个节点的示例：
-1. 测试节点 1-4：问题仍然存在 ✓ → 问题在剩余节点 5-8 中
-2. 测试节点 5-6：问题消失 ✓ → 问题在节点 7-8 中
-3. 测试节点 7：问题仍然存在 ✓ → 节点 7 是问题所在！
-
-这只需要 3 次测试，而不是测试所有 8 个节点。
-```
+
+- A:包含前端扩展的自定义节点
+- B: 常规节点
-#### 二分搜索过程
-
-
-开始之前，请**创建备份**你的 custom_nodes 文件夹，以防出现问题。
-
-
-##### 创建临时文件夹
+首先让我们先了解不同类型的自定义节点可能导致的问题和原因
-
-```bash
-# 创建备份和临时文件夹
-mkdir "%USERPROFILE%\custom_nodes_backup"
-mkdir "%USERPROFILE%\custom_nodes_temp"
-
-# 首先备份所有内容
-xcopy "custom_nodes\*" "%USERPROFILE%\custom_nodes_backup\" /E /H /Y
-```
-
-
-```bash
-# 创建备份和临时文件夹
-mkdir ~/custom_nodes_backup
-mkdir ~/custom_nodes_temp
-
-# 首先备份所有内容
-cp -r custom_nodes/* ~/custom_nodes_backup/
-```
-
-
-```bash
-# 创建备份和临时文件夹
-mkdir /content/custom_nodes_backup
-mkdir /content/custom_nodes_temp
-
-# 首先备份所有内容
-cp -r /content/ComfyUI/custom_nodes/* /content/custom_nodes_backup/
-```
-
-
-
-##### 找到有问题的节点
-
-1. **列出你的自定义节点：**
-
-
- ```bash
- dir custom_nodes
- ```
-
-
- ```bash
- ls custom_nodes/
- ```
-
-
- ```bash
- ls /content/ComfyUI/custom_nodes/
- ```
-
-
-
-2. **将节点分成两半：**
+
+ 对于自定义节点我们又特别需要对包含前端扩展的自定义节点进行优先排查，这类节点导致的问题是最多的, 他们主要的冲突是与 ComfyUI 前端版本更新产生的冲突。
- 假设你有 8 个自定义节点。将前一半移动到临时存储：
-
-
-
- ```bash
- # 将前一半（节点 1-4）移动到临时文件夹
- move "custom_nodes\node1" "%USERPROFILE%\custom_nodes_temp\"
- move "custom_nodes\node2" "%USERPROFILE%\custom_nodes_temp\"
- move "custom_nodes\node3" "%USERPROFILE%\custom_nodes_temp\"
- move "custom_nodes\node4" "%USERPROFILE%\custom_nodes_temp\"
- ```
-
-
- ```bash
- # 将前一半（节点 1-4）移动到临时文件夹
- mv custom_nodes/node1 ~/custom_nodes_temp/
- mv custom_nodes/node2 ~/custom_nodes_temp/
- mv custom_nodes/node3 ~/custom_nodes_temp/
- mv custom_nodes/node4 ~/custom_nodes_temp/
- ```
+ 常见的一些问题有:
+ - 工作流无法执行
+ - 节点预览图丢失
+ - UI元素错位
+ - 无法进入 ComfyUI 前端
+ - UI 完全损坏或显示空白屏幕
+ - 无法和 ComfyUI 后端正常通信
+ - 节点之间的连线无法正常工作
+ - 等等
+
+ 常见这类节点导致的原因是因为：
+ - 我们在对前端进行更新过程中进行了一些修改调整，这些自定义节点没有及时更新
+ - 用户常常在更新过程中只是更新了 ComfyUI 并没有对自定义节点进行同步升级，虽然作者进行了更新，但是用户并没有在使用最新的兼容版本
+ - 作者停止了维护，导致对应的自定义节点扩展无法和前端相互兼容
+
-
- ```bash
- # 将前一半（节点 1-4）移动到临时文件夹
- mv /content/ComfyUI/custom_nodes/node1 /content/custom_nodes_temp/
- mv /content/ComfyUI/custom_nodes/node2 /content/custom_nodes_temp/
- mv /content/ComfyUI/custom_nodes/node3 /content/custom_nodes_temp/
- mv /content/ComfyUI/custom_nodes/node4 /content/custom_nodes_temp/
- ```
+
+ 如果问题不是由于自定义节点的前端扩展导致，那么更多会出现在依赖问题上，这类常见的问题会有：
+ - 控制台/日志中出现"Failed to import"（导入失败）错误
+ - 安装工作流缺失的节点后重启后任然显示丢失
+ - ComfyUI 崩溃或无法启动
+ - 等
+
+ 常见的这类错误导致的原因有：
+ - 自定义节点还需要安装额外的 wheel 比如 ComfyUI-Nunchaku
+ - 自定义使用了严格的依赖版本比如 `torch==2.4.1` 但是其它插件使用的是 `torch>=2.4.2` 在安装对应自定义节点以后后另外一个节点的依赖就冲突了
+ - 网络问题导致的对应依赖没有安装成功
+
+ 如果问题发生在 python 环境的相互依赖上，版本等，这类问题处理起来需要一定的 python 环境知识，需要懂得如何在 python 环境中进行依赖的安装和卸载，这类问题处理起来会相对复杂一些
-
-
-3. **测试 ComfyUI：**
- ```bash
- python main.py
- ```
-
-4. **解释结果：**
- - **问题仍然存在**：问题在剩余节点（5-8）中
- - **问题消失**：问题在移动的节点（1-4）中
-
-5. **缩小范围：**
- - 如果问题仍然存在：将剩余节点的一半（例如节点 7-8）移动到临时文件夹
- - 如果问题消失：将临时节点的一半（例如节点 3-4）移回 custom_nodes
-
-6. **重复直到找到单个有问题的节点**
-
-#### 视觉示例
-
-让我们通过一个包含 8 个自定义节点的完整示例：
-
-```
-📁 custom_nodes/
-├── 🔧 ComfyUI-Manager
-├── 🎨 ComfyUI-Custom-Scripts
-├── 🖼️ ComfyUI-Impact-Pack
-├── 🔄 ComfyUI-Workflow-Component
-├── 📊 ComfyUI-AnimateDiff-Evolved
-├── 🎭 ComfyUI-FaceRestore
-├── ⚡ ComfyUI-Advanced-ControlNet
-└── 🛠️ ComfyUI-Inspire-Pack
-```
-
-**第 1 轮：** 将前 4 个移动到临时文件夹
-- 测试 → 问题仍然存在 ✓
-- 问题在：ComfyUI-AnimateDiff-Evolved、ComfyUI-FaceRestore、ComfyUI-Advanced-ControlNet、ComfyUI-Inspire-Pack
-
-**第 2 轮：** 将剩余 4 个中的 2 个移动到临时文件夹
-- 测试 → 问题消失 ✓
-- 问题在：ComfyUI-Advanced-ControlNet、ComfyUI-Inspire-Pack
-
-**第 3 轮：** 将剩余 2 个中的 1 个移动到临时文件夹
-- 测试 → 问题仍然存在 ✓
-- **找到了！** ComfyUI-Inspire-Pack 是有问题的节点
+
-### 步骤 3：修复问题
+## 使用二分法进行排查
+
+这两种上面两种不同的自定义节点问题里，自定义节点前端扩展和 ComfyUI 的冲突较为常见，我们会优先排查这类节点，后续的整体的问题排查思路如下
+
+### 1.排查带有前端扩展的自定义节点
+
+
+
+ 
+ 在启动 ComfyUI 后，在设置菜单中找到 `扩展` 菜单，并参考上图步骤禁用所有第三方扩展
+
+
+ 在首次禁用前端扩展后，建议重启一次 ComfyUI 来保证能够顺利地禁用所有的前端扩展加载
+ - 如果问题消失，那么问题就是由自定义节点的前端扩展引起的，我们可以继续进行下一步进行二分法进行排查
+ - 如果问题仍然存在，那么问题就不是由自定义节点的前端扩展引起的，请参考本文另外一部分自定义节点扩展问题排查的思路
+
+
+ 使用本文开头提到的方法来进行问题排查，一次启用一半的自定义节点，直到找到导致问题的自定义节点
+ 
+ 参考图片，对一半的前端扩展进行启用，另外如果对应的扩展名称都相似，那么说明他们是来自同一个自定义节点的前端扩展
+
+
+ 如果找到问题自定义节点请参考本文的问题修复部分来进行自定义节点的问题修复
+
+
+
+使用这种方法，你不用多次重启 ComfyUI 仅需要在每次启用 / 禁用自定义节点的前端扩展后重载 ComfyUI 即可, 而且你的排查范围也只是在有前端扩展的节点里，会大大缩小节点排查范围
+
+### 2. 通用的自定义节点排查方法
+
+
+
+
+
+ 从设置菜单中启动禁用自定义节点的 ComfyUI 桌面版
+
+ 
+
+ 或手动运行服务器：
+
+ ```bash
+ cd path/to/your/comfyui
+ python main.py --disable-all-custom-nodes
+ ```
+
+
+ ```bash
+ cd ComfyUI
+ python main.py --disable-all-custom-nodes
+ ```
+
+
+
+
+
+ 打开便携版所在的文件夹，找到 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件
+
+ 
+ 1. 复制 `run_nvidia_gpu.bat` 或者 `run_cpu.bat` 文件并重命名为 `run_nvidia_gpu_disable_custom_nodes.bat`
+ 2. 使用记事本打开复制后的文件
+ 3. 在文件中添加 `--disable-all-custom-nodes` 参数，或者复制下面的参数保存到 txt 文件中后将文件后缀名改为 `.bat`
+
+ ```bash
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes --windows-standalone-build
+ pause
+ ```
+ 4. 保存文件并关闭
+ 5. 双击运行文件，如果一切正常，你应该会看到 ComfyUI 启动，并且自定义节点被禁用
+
+
+ 
+ 1. 进入便携版所在的文件夹
+ 2. 通过右键菜单 → 打开终端 来打开命令行
+
+ 
+
+ 3. 确保在命令行中文件夹名称是当前便携版所在的文件目录
+ 4. 输入以下命令,来通过便携版的 python 来启动 ComfyUI 并禁用自定义节点
+ ```
+ .\python_embeded\python.exe -s ComfyUI\main.py --disable-all-custom-nodes
+ ```
+
+
+
+
+
+ **结果：**
+ - ✅ **问题消失**：自定义节点导致问题 → 继续步骤 2
+ - ❌ **问题仍然存在**：不是自定义节点问题 → [报告问题](#报告问题)
+
+
+ 对于二分搜索定位的方法，除了手动之外我们也有使用 comfy-cli 来进行自动化的二分搜索，具体方法如下：
+
+
+
+ 使用 Comfy CLI 需要你具有一定的命令行使用经验，如果你对此不擅长，请使用手动二分搜索
+
+ 如果你已安装 [Comfy CLI](/zh-CN/comfy-cli/getting-started)，那么 Comfy CLI 可以允许你使用自动化的二分工具来找到有问题的节点：
+
+ ```bash
+ # 开始二分会话
+ comfy-cli node bisect start
+
+ # 按照提示操作：
+ # - 使用当前启用的节点集测试 ComfyUI
+ # - 如果问题消失，标记为 'good'：comfy-cli node bisect good
+ # - 如果问题仍然存在，标记为 'bad'：comfy-cli node bisect bad
+ # - 重复直到识别出有问题的节点
+
+ # 完成后重置
+ comfy-cli node bisect reset
+ ```
+
+ 二分工具将自动启用/禁用节点并引导你完成整个过程。
+
+
+
+ 开始之前，请**创建备份**你的 custom_nodes 文件夹，以防出现问题。
+
+
+ 如果你更喜欢手动操作或没有安装 Comfy CLI，请按照以下步骤操作：
+
+
+ 在开始前先进入 `<你的安装位置>\ComfyUI\` 文件夹
+
+
+ - **备份所有自定义节点**: 将 `custom_nodes` 复制并重命名为 `custom_nodes_backup`
+ - **创建临时文件夹**: 创建一个名为 `custom_nodes_temp` 的文件夹
+
+ 或者使用下面的命令行来进行备份
+
+ ```bash
+ # 创建备份和临时文件夹
+ mkdir "%USERPROFILE%\custom_nodes_backup"
+ mkdir "%USERPROFILE%\custom_nodes_temp"
+
+ # 首先备份所有内容
+ xcopy "custom_nodes\*" "%USERPROFILE%\custom_nodes_backup\" /E /H /Y
+ ```
+
+
+ 手动备份 custom_nodes 文件夹
+ 或使用下面的命令行来进行备份
+ ```bash
+ # 创建备份和临时文件夹
+ mkdir ~/custom_nodes_backup
+ mkdir ~/custom_nodes_temp
+
+ # 备份所有内容
+ cp -r custom_nodes/* ~/custom_nodes_backup/
+ ```
+
+
+ ```bash
+ # 创建备份和临时文件夹
+ mkdir /content/custom_nodes_backup
+ mkdir /content/custom_nodes_temp
+
+ # 首先备份所有内容
+ cp -r /content/ComfyUI/custom_nodes/* /content/custom_nodes_backup/
+ ```
+
+
+
+
+
+
+ 由于 Windows 有可视化界面你可以忽略这一步，除非你只是使用命令行
+ ```bash
+ dir custom_nodes
+ ```
+
+
+ ```bash
+ ls custom_nodes/
+ ```
+
+
+ ```bash
+ ls /content/ComfyUI/custom_nodes/
+ ```
+
+
+
+
+ 假设你有 8 个自定义节点。将前一半移动到临时存储：
+
+
+ ```bash
+ # 将前一半（节点 1-4）移动到临时文件夹
+ move "custom_nodes\node1" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node2" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node3" "%USERPROFILE%\custom_nodes_temp\"
+ move "custom_nodes\node4" "%USERPROFILE%\custom_nodes_temp\"
+ ```
+
+
+ ```bash
+ # 将前一半（节点 1-4）移动到临时文件夹
+ mv custom_nodes/node1 ~/custom_nodes_temp/
+ mv custom_nodes/node2 ~/custom_nodes_temp/
+ mv custom_nodes/node3 ~/custom_nodes_temp/
+ mv custom_nodes/node4 ~/custom_nodes_temp/
+ ```
+
+
+ ```bash
+ # 将前一半（节点 1-4）移动到临时文件夹
+ mv /content/ComfyUI/custom_nodes/node1 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node2 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node3 /content/custom_nodes_temp/
+ mv /content/ComfyUI/custom_nodes/node4 /content/custom_nodes_temp/
+ ```
+
+
+
+
+ 正常启动 ComfyUI
+ ```bash
+ python main.py
+ ```
+
+
+ - **问题仍然存在**：问题在剩余节点（5-8）中
+ - **问题消失**：问题在移动的节点（1-4）中
+
+
+ - 如果问题仍然存在：将剩余节点的一半（例如节点 7-8）移动到临时文件夹
+ - 如果问题消失：将临时节点的一半（例如节点 3-4）移回 custom_nodes
+
+
+ - 重复直到找到单个有问题的节点
+
+
+
+
+
+
+
+## 修复自定义节点问题
一旦你识别出有问题的自定义节点：
-#### 选项 1：更新节点
+### 选项 1:更新节点
1. 检查 ComfyUI 管理器中是否有可用更新
2. 更新节点并再次测试
-#### 选项 2：替换节点
+### 选项 2:替换节点
1. 寻找具有类似功能的替代自定义节点
2. 查看 [ComfyUI 注册表](https://registry.comfy.org) 寻找替代方案
-#### 选项 3：报告问题
+### 选项 3:报告问题
联系自定义节点开发者：
1. 找到节点的 GitHub 仓库
2. 创建问题并包含：
@@ -283,14 +356,14 @@ cp -r /content/ComfyUI/custom_nodes/* /content/custom_nodes_backup/
- 重现步骤
- 你的操作系统
-#### 选项 4：移除节点
+### 选项 4:移除节点
如果没有修复可用且你不需要该功能：
1. 从 `custom_nodes/` 中移除有问题的节点
2. 重启 ComfyUI
-## 报告问题
+## 报告非自定义节点导致的问题
-如果问题不是由自定义节点引起的，请参考通用[故障排除概述](/zh-CN/troubleshooting/overview)了解其他常见问题。
+如果问题不是由自定义节点引起的，请参考通过[故障排除概述](/zh-CN/troubleshooting/overview)了解其他常见问题。
### 自定义节点特定问题
联系自定义节点开发者：