---
id: node-replacement---comfyui
title: "Node replacement - ComfyUI"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: []
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.8
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["web", "wikify"]
raw_sources: ["https://docs.comfy.org/custom-nodes/backend/node-replacement"]
applied_in: []
github_commit: ""
---

# [[Node replacement - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
[[Node Replacement API]]는 커스텀 노드 개발자가 구식(deprecated) 노드를 최신 노드로 자동 마이그레이션하여 워크플로우의 호환성을 유지할 수 있게 해주는 기능이다.

## 🧠 핵심 개념 (Core concepts)
- **Migration Path Definition**: [[Node Replacement API]]를 통해 구 버전 노드에서 신규 노드로의 전환 경로를 정의한다.
- **Automated Workflow Upgrade**: 노드 클래스 이름 변경, 노드 병합, 입력/출력 리팩토링 시 사용자의 워크플로우를 자동으로 업데이트한다.
- **Lifecycle Integration**: 커스텀 노드 확장의 `on_load` 생명주기 훅(lifecycle hook) 단계에서 교체 로직을 등록한다.
- **Data Mapping**: [[Input mapping]], [[Output mapping]], [[Widget ID binding]]을 통해 입력/출력 데이터와 위젯 값을 정밀하게 재연결한다.

## 🧩 추출된 패턴 (Extracted patterns)
- **Node Replacement Use Cases**: 노드 클래스 이름 변경, 노드 병합(Merging), 입력 리팩토링, 오타 수정(Typo fix) 등 특정 목적에 따라 API를 활용함.
- **Registration Strategy**: `node_replacements.py`와 같은 전용 파일을 생성하여 `on_load` 시점에 등록하는 구조를 가짐.
- **Mapping Logic**: 
    - [[Input mapping]]: 기존 입력을 새 입력으로 매핑하거나 고정값(`set_value`)을 설정함.
    - [[Output mapping]]: 인덱스 기반의 참조를 통해 출력 데이터를 재배치함.
- **Frontend Automation**: 프론트엔드에서 API를 호출하여 교체 정보를 가져온 후, 사용자에게 업그레이드를 제안하고 연결 및 위젯 값을 보존함.

## 📖 세부 내용 (Details

### 🛠 NodeReplace Parameters
| 필드 | 타입 | 필수/선택 | 제약·설명 |
| :--- | :--- | :--- | :--- |
| `new_node_id` | str | 필수 | 교체될 대상 노드의 클래스 이름 |
| `old_node_rypt_id` | str | 필수 | 기존의 구식(deprecated) 노드 클래스 이름 |
| `old_widget_ids` | list[str] \| None | 선택 | 상대적 인덱스에 바인딩할 위젯 ID의 정렬된 리스트 |
| `input_mapping` | list \| None | 선택 | 기존 노드에서 새 노드로 입력을 매핑하는 방법 |
| `output_mapping` | list \| None | 선택 | 기존 노드에서 새 노드로 출력을 매핑하는 방법 |

### 📥 Input Mapping Details
입력 매핑은 다음과 같은 방식으로 정의됩니다:
- **기존 입력 매핑**: `{"new_id": "model", "old_id": "model"}`
- **고정값 설정**: `{"new_id": "scheduler", "set_value": "normal"}`
- **동적/Autogrow 입력 (Dot notation 사용)**: `{"new_id": "images.image0", "old_id": "image1"}`

### 📤 Output Mapping Details
출력 매핑은 인덱스 기반 참조를 사용합니다:
- `{"new_idx": 0, "old_idx": 0}` (첫 번째 출력 매핑)
- `{"new_idx": 1, "old_idx": 0}` (기존 출력 0을 새 출력 1로 매핑)

### 🔗 Widget ID Binding
`old_widget_ids` 필드는 위젯 ID를 위치 인덱스에 매핑합니다. 워크플로우 JSON은 위젯 값을 ID가 아닌 위치로 저장하기 때문에 이 기능이 필요합니다.
- 예: `["steps", "cfg", "sampler"]` -> index 0은 "steps"를 의미함.

### 🌐 REST API (GET /api/node_replacements)
등록된 모든 교체 정보를 반환하며, 응답 구조는 다음과 같습니다:
```json
{
  "OldSamplerNode": [
    {
      "new_node_im_id": "NewSamplerNode",
      "old_node_id": "OldSamplerNode",
      "old_widget_ids": ["num_steps", "cfg_scale", "sampler_name"],
      "input_mapping": [...],
      "output_mapping": [...]
    }
  ]
}
```

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
본문에서 확인되지 않음.

## 🛠 적용 사례 (Applied in summary)
- **Simple Node Merge**: `Load3DAnimation` 노드를 `Load3D`로 병합.
- **Typo Fix**: `SDV_img2vid_Conditioning`의 오타를 `SVD_imgint2vid_Conditioning`으로 수정.
- **Input Renaming**: `ImageScaleBy`를 `ResizeImageMaskNode`로 교체하며 입력/출력 매핑 및 기본값(`set_value`) 적용.
- **Autogrow Mapping**: `BatchImagesNode`에서 도트 노테이션을 사용하여 `images.image0`과 같은 동적 입력 처리.

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual
- **출처 신뢰도:** B (Primary Source — 웹사이트 본문 직접 추출)
- **중복 검사 결과:** 신규 생성 (New discovery)

## 🔗 관련 문서 링크 (Related document links)
- [[Node Replacement API]]: 노드 교체 기능을 구현하기 위한 핵심 인터페이스.
- [[Input mapping]]: 입력 데이터를 새 노드로 전달하는 메커니즘.
- [[Output mapping]]: 출력 인덱스를 재정의하는 방법.
- [[Widget ID binding]]: 위젯 위치 기반 매핑을 위한 기술적 요구사항.
- [[on_load lifecycle hook]]: 교체 로직을 등록해야 하는 시점.

## 📝 변경 이력 (Change history)
- 2026-05-20: Astra /wikify 로 https://docs.comfy.org/custom-nodes/backend/node-replacement 본문에서 초안 생성.