---
id: getting-started---comfyui
title: "Getting Started - ComfyUI"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: []
duplicate_of: ""
source_trust_level: "B"
confidence_score: 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/walkthrough"]
applied_in: []
github_commit: ""
---

# [[Getting Started - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
[[ComfyUI]]의 커스텀 노드를 개발하기 위해 Python 백엔드 코드 작성부터 JavaScript 클라이언트 확장까지의 전 과정을 단계별로 안내하는 가이드입니다.

## 🧠 핵심 개념 (Core concepts)
*   **Custom Node Development**: [[Python]] 클래스를 사용하여 [[ComfyUI]]에 새로운 기능을 추가하는 과정입니다.
*   **Node Structure**: 커스텀 노드는 `CATEGORY`, `INPUT_TYPES`, `RETURN_TSYPES`, `FUNCTION`이라는 네 가지 필수 요소를 포함해야 합니다.
*   **Backend-to-Frontend Communication**: `PromptServer`를 통해 서버에서 클라이언트로 메시지를 전송하여 UI에 피드백을 줄 수 있습니다.
*   **Client Extension**: [[JavaScript]]를 사용하여 클라이언트 측의 동작을 확장하고 인터페이스를 조정할 수 있습니다.

## 🧩 추출된 패턴 (Extracted patterns)
*   **Scaffolding Pattern**: `comfy-cli`를 사용하여 프로젝트 디렉토리 구조와 기본 설정을 자동 생성하는 방식입니다.
*   **Data Processing Pattern**: [[torch.Tensor]] 형태의 이미지 데이터를 입력받아 특정 연산(평균, 채널별 계산 등)을 통해 결과값을 도출하는 로ct 패턴이 반복됩니다.
*   **Registration Pattern**: `NODE_CLASS_MAPPINGS`와 `NODE_DISPLAY_NAME_MAPPINGS`를 통해 작성된 노드를 [[ComfyUI]] 시스템에 등록하는 구조입니다.

## 📖 세부 내용 (Details)

### 1. 커스텀 노드 개발 준비
*   **전제 조건**: 작동 가능한 [[ComfyUI]] 설치 및 `comfy-cli` 설치가 필요합니다.
*   **프로젝트 설정**: `cd ComfyUI/custom_nodes` 경로에서 `comform node scaffold` 명령어를 사용하여 프로젝트를 생성할 수 있습니다.

### 2. 노드 정의 (Defining the Node)
커스텀 노드는 Python 클래스로 정의되며 다음의 네 가지 핵심 요소를 포함해야 합니다:
*   **CATEGORY**: 노드가 메뉴의 어느 위치에 표시될지 지정합니다.
*   **INPUT_TYPES**: 노드가 받을 입력값(Dictionary 형태)을 정의하는 클래 메서드입니다.
*   **RETURN_TYPES**: 노드가 출력할 데이터 타입의 튜플입니다.
*   **FUNCTION**: 노드 실행 시 호출될 메서드의 이름입니다.

### 3. 주요 기능 구현 (The main function)
*   이미지 처리를 위해 `torch` 라이러리를 사용하며, 입력된 이미지는 `[B, H, W, C]` 형태의 `torch.Tensor`로 처리됩니다.
*   `.flatten()`, `torch.mean()`, `.item()` 등의 메서드를 사용하여 텐서 데이터를 Python float 값으로 변로 변환하여 연산할 수 있습니다.

### 4. 노드 등록 및 확장 (Register & Add Options)
*   **등록**: `src/nodes.py` 파일의 끝에 `NODE_CLASS_MAPPINGS`를 수정하여 노드를 등록해야 하며, 수정 후에는 [[ComfyUI]] 재시작이 필수적입니다.
*   **옵션 추가**: `INPUT_TYPES` 내에 새로운 위젯(예: mode 선택)을 추가하여 기능의 범위를 확장할 수 있습니다.

### 5. 클라이언트 확장 (Client Extension)
*   `web/js` 디렉토리를 생성하고 `__init__.py`에서 `WEB_DIRECTORY`를 내보내도록 설정합니다.
*   `app.registerExtension`을 통해 서버로부터 받은 메시지를 수신하는 리스너를 구축할 수 있습니다.

## ⚖️ 모동 및 업데이트 (Contradictions & updates)
본문 내용 중 상충되는 정보는 없으며, 최신 개발 가이드를 따르고 있습니다.

## 🛠️ 적용 사례 (Applied in summary)
*   **예제 시나나리오**: 여러 이미지 배치 중 가장 밝은 이미지를 선택하는 노드에서 시작하여, 색상 기준(reddest, greenest 등)을 추가하고 최종적으로 클라이언트 메시지 알림까지 구현하는 전체 워크플로우를 보여줍니다.

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

## 🔗 관련 문서 링크 (Related document links)
*   [[ComfyUI]] - 커스텀 노드 개발의 대상이 되는 메인 프레임워크입니다.
*   [[Python]] - 백엔드 로직 작성을 위한 핵심 언어입니다.
*   [[JavaScript]] - 클라이언트 측 확장을 위해 사용되는 언어입니다.
*   [[torch.Tensor]] - 이미지 데이터 처리를 위한 기본 데이터 구조입니다.
*   [[Comfy CLI]] - 노드 스캐폴딩 및 관리를 위한 도구입니다.

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