---
id: v3-migration---comfyui
title: "V3 Migration - ComfyUI"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: []
duplicate_of: ""
source_radix: "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/v3_migration"]
applied_in: []
github_commit: ""
---

# [[V3 Migration - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
기존 V1(Legacy) 방식의 노드 정의 구조를 객체 중심의 새로운 V3 스키마로 전환하여, 더 체계적이고 확장 가능한 방식으로 마이그레이션하는 가이드.

## 🧠 핵심 개념 (Core concepts)
*   **V3 Schema Architecture**: 기존의 딕셔너리 기반 정의에서 벗어나 [[io.Schema]] 객체를 사용하여 입력(Inputs)과 출력(Outputs)을 객체 단위로 정의함.
*   **Class-based Execution**: 실행 메서드가 `execute`라는 이름의 클래 메서드로 고정되며, `comfy_entrypoint`를 통해 확장을 정의함.
*   **Type Safety & Modernization**: `io.Int.Input`, `io.Image.Input` 등 클래스 기반의 타입 정의를 통해 강력한 타입 힌트와 구조화된 스키마 관리를 지원함.
*   **API-driven Extension**: `ComfyExtension` 및 `ComfyAPI`를 사용하여 노드 교체, 진행률 보고, 확장 생명주기를 관리함.

## 🧩 추출된 패턴 (Extracted patterns)
*   **V1 to V3 Transformation Pattern**: `INPUT_TYPES` 딕셔너리를 `define_schema` 메서드의 `io.Schema` 객체로 변환하고, `FUNCTION`을 `execute` 클래 메서드로 변경하는 일련의 문법적 전환 패턴.
*   **Inheritance Pattern**: 모든 V3 노드는 반드시 `io.ComfyNode`를 상속받아야 하며, 상위 체인에 이 클래스가 포함되어야 함.
*   **Schema-driven Configuration**: 노드의 ID, 표시 이름, 카테고리, 입출력 정의 등 모든 메타데이터가 하나의 스키마 객체 내로 통합되는 구조.

## 📖 세부 내용 (Details)

### 1. V3 Migration: 주요 변경 사항 비교
| 특징 | V1 (Legacy) | V3 (Modern) |
| :--- | :--- | :--- |
| **입력/출력 정의** | 딕셔니리(Dictionary) 방식 | 객체(Object) 기반 방식 |
| **실행 메서드** | `FUNCTION`에 지정된 이름 사용 | `execute`로 고정 (클래 메서드) |
| **노드 등록** | `NODE_CLASS_MAPPINGS` 사용 | `comfy_entrypoint` 및 `ComfyExtension` 사용 |
| **상태 관리** | `__init__` 등을 통한 상태 유지 가능성 | 클래 메서드 중심, `state` 노출 없음 |

### 2. Migration Steps (마이그레이션 단계)
*   **Step 1: Base Class 변경**: 모든 V3 스키마 노드는 `io.ComfyNode`를 상속받아야 함.
*   **Step 2: INPUT_TYPES를 define_schema로 전환**: `io.Schema` 객체를 반환하도록 구현하며, 입출력을 클래스 기반으로 정의함.
*   **Step 3: Execute 메서드 업데이트**: 실행 함수 이름을 `execute`로 변경하고 클래 메서드로 선언함.
*   **Step 4: 노드 속성 변환**: `RETURN_TYPES`, `CATEGORY`, `FUNCTION` 등의 기존 속성을 `io.Schema` 내의 필드로 재배치함.
*   **Step 5: 특수 메서드 처리**: `validate_inputs` (기존 `VALIDATE_INPUTS`), `fingerprint_inputs` (기존 `IS_CHANGED`) 등 변경된 명칭 적용.
*   **Step 6: Extension 및 Entry Point 생성**: `ComfyExtension` 클래스를 정의하고 `comfy_entrypoint`를 구현함.

### 3. Schema Reference (Schema 데이터클래스 필드)
| 필드 | 타입 | 필수/선택 | 제약·설명 |
| :--- | :--- | :--- | :--- |
| node_id | str | 필수 | 노드의 글로벌 고유 ID (충돌 방지를 위해 접두사/접미사 권장) |
| display_name | str | 선택 | UI에 표시될 이름. 미설정 시 `node_id` 사용 |
| category | str | 선택 | "Add Node" 메뉴 내 카테록 (예: "sd") |
| description | str | 선택 | 마우스 호버 시 표시되는 툴팁 |
| inputs | list[Input] | 선택 | 입력 정의 리스트 |
| outputs | list[Output] | 선택 | 출력 정의 리스트 |
| hidden | list[Hidden] | 선택 | 요청할 숨겨진 입력(Hidden Inputs) 리스트 |
| search_aliases | list[str] | 선택 | 검색을 위한 대체 이름 목록 |
| is_output_node | bool | 선택 | True일 경우 노드가 출력 노드로 표시됨 |
| is_input_list | bool | 선택 | True일 경우 모든 입력이 `list[type]`로 처리됨 |
| is_deprecated | bool | 선택 | 노드 폐기 여부 플래[Flag] |
| is_experimental | bool | 선택 | 실험적 기능 여부 표시 |
| is_dev_only | bool | 선택 | 개발 모드에서만 보이도록 설정 |
| is_api_node | bool | 선택 | Comfy API 서비스용 노드로 지정 |
| not_idempotent | bool | 선택 | True일 경우 캐싱된 출력을 재사용하지 않고 항상 재실행함 |
| enable_expand | bool | 선택 | NodeOutput에 확장 속성 포함 가능 여부 |
| accept_all_inputs | bool | 선택 | 스키마에 정의되지 않은 입력도 kwargs로 전달 허용 |

### 4. Advanced Features (고급 기능)
*   **Hidden Inputs**: `cls.hidden`을 통해 접근하며, `unique_id`, `prompt`, `extra_pnginfo` 등을 포함함.
*   **UI Helpers**: `ui.PreviewImage`, `ui.AudioSaveHelper` 등을 사용하여 노드 출력 시 UI 데이터를 반환할 수 있음.
*   **Custom Types**: `@io.comfytype` 데코레이터나 `io.Custom` 함수를 통해 사용자 정의 타입을 생성 가능함.
*   **Dynamic Inputs**: `Autogrow`(입력 자동 증가) 및 `DynamicCombo`(옵션에 따라 입력 변경) 기능을 지원함.

## ⚖️ 모래 및 업데이트 (Contradictions & updates)
*   **업데이트 사항**: V1의 `IS_CHANGED` 함수가 V3에서는 `fingerprint_inputs`로 명칭이 변경됨 (개발자의 혼동을 방지하기 위함).
*   **업데이트 사항**: 입력 검증 메서드가 `VALIDATE_INPUTS`에서 `validate_inputs`로 소문자화되어 변경됨.

## 🛠️ 적용 사례 (Applied in summary)
*   **노드 마이그레이션 프로젝트**: 기존에 운영 중인 V1 기반 커스텀 노드를 최신 ComfyUI 스키마 표준에 맞춰 업데이트할 때 이 가이드를 참조함.
*   **확장 프로그램 개발**: `ComfyExtension`을 사용하여 새로운 노드 세트를 등록하고, `comfy_entrypoint`를 통해 실행 환경을 구축하는 데 사용됨.

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

## 🔗 관련 문서 링크 (Related document links)
*   [[io.Schema]] - V3 노드의 핵심 정의 구조체.
*   [[ComfyExtension]] - 확장의 생명주기와 노드 등록을 관리하는 클래스.
*   [[io.NodeOutput]] - 실행 결과와 UI 데이터를 반환하기 위한 표준 객체.
*   [[comfy_api.latest]] - 최신 안정화된 API 참조를 위한 패키지.
*   [[V1 (Legacy)]] - 마이그레이션의 대상이 되는 이전 방식의 노드 구조.

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