2nd/10_Wiki/Comfyui/위키 Lifecycle - ComfyUI 2026-05-20.md

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

id	title	category	status	verification_status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	created_at	updated_at	review_reason	merge_history	tags	raw_sources	applied_in	github_commit
lifecycle---comfyui	Lifecycle - ComfyUI	10_Wiki/Topics	draft	conceptual				B	1.0	2026-05-20	2026-05-20			web wikify	https://docs.comfy.org/custom-nodes/backend/lifecycle

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 예시:

  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 본문에서 초안 생성.