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

# [[Lifecycle - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI가 시작될 때 `custom_nodes` 디렉토리를 스캔하여 Python 모듈을 로드하고 커스텀 노드를 정의하는 라이프사이클 프로세스.

## 🧠 핵심 개념 (Core concepts)
*   **[[custom_nodes]] 로딩**: ComfyUI 시작 시 `custom_nodes` 폴ের더를 스캔하여 Python 모듈을 찾아 로드함.
*   **[[NODE_CLASS_MAPPINGS]]**: 모듈이 커스텀 노드로 인식되기 위해 반드시 내보내야(export) 하는 딕셔너리 매핑 정보.
*   **[[__init__.py]] 역할**: 커스텀 노드 모듈의 진입점으로, 실행 시 `NODE_CLASS_MAPPINGS`를 포함하여 노드 정의를 ComfyUI에 가용하게 함.
*   **[[WEB_DIRECTORY]] 설정**: 클라이언트 측 JavaScript 파일을 제공하기 위해 모듈 내 상대 경로를 지정하는 기능.

## 🧩 추출된 패턴 (Extracted patterns)
*   **모듈 인식 조건**: Python 모듈은 `__init__.py`를 포함하는 디렉토리 형태이며, `__all__` 속성에 정의된 내용을 내보냄.
*   **에러 처리 패턴**: 코드에 에러가 발생하더라도 ComfyUI는 계속 진행하지만, 해당 모듈이 로드에 실패했음을 Python 콘솔을 통해 보고함.
*   **표준화된 구조**: 커스텀 노드의 JavaScript 파일은 관례적으로 `js`라는 하위 디렉토리에 배치함.

## 📖 세부 내용 (Details)
### 1. How Comfy loads custom nodes
ComfyUI는 시작 시 `custom_nodes` 디렉토리를 스캔하여 Python 모듈을 로드하려고 시도합니다. 해당 모듈이 `NODE_CLASS_MAPPINGS`를 내보내면 커스텀 노드로 취급됩니다.

### 2. init.py 구성 요소
커스텀 노드 정의를 위해 `__init__.py`에서 관리해야 하는 주요 매핑 정보는 다음과 같습니다.

| 필드 | 타입 | 필수/선택 | 제약·설명 |
| :--- | :--- | :--- | :--- |
| [[NODE_CLASS_MAPPINGS]] | dict | 필수 | 커스텀 노드 이름(고유값)을 해당 노드 클래스에 매핑함. |
| [[NODE_DISPLAY_NAME_MAPPINGS]] | dict | 선택 | 고유 이름을 사용자에게 보여줄 표시용 이름으로 매핑함. 미제공 시 고유 이름을 사용함. |
| [[WEB_DIRECTORY]] | string | 선택 | JavaScript 파일이 위치한 모듈 내 상대 경로를 지정함 (예: `js` 디렉토리). |

### 3. JavaScript 배포 및 주의사항
*   **파일 제한**: `.js` 파일만 제공 가능하며, `.css`나 기타 타입은 이 방식으로 배포할 수 없음.
*   **구 버전 방식 지양**: 과거에는 JavaScript 파일을 Comfy 웹 하위 디렉토리로 복사하는 코드가 필요했으나, 현재는 이를 권장하지 않음.

## ⚖️ 모모순 및 업데이트 (Contradictions & updates)
*   **업데이트 사항**: 이전 버전의 Comfy에서는 `__init__.py`가 JavaScript 파일을 메인 웹 디렉토리로 복사하는 작업이 필요했으나, 현재는 이를 수행하는 코드를 사용하지 말라고 명시되어 있음.

## 🛠️ 적용 사례 (Applied in summary)
*   **단순한 `__init__.py` 예시**:
    ```python
    from .python_file import MyCustomNode
    NODE_CLASS_MAPPINGS = { "My Custom Node" : MyCustomNode }
    __all__ = ["NODE_CLASS_MAPPINGS"]
    ```

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

## 🔗 관련 문서 링크 (Related document links)
*   [[custom_nodes]] - 커스텀 노드가 로드되는 물리적 경로와 메커니즘 설명.
*   [[NODE_CLASS_MAPPINGS]] - 노드 클래스를 식별하기 위한 핵심 매핑 구조.
*   [[WEB_DIRECTORY]] - 클라이언트 사이드 JS 파일 배포를 위한 경로 설정법.
*   [[__init__.py]] - Python 모듈의 초기화 및 커스텀 노드 로직 실행 지점.

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