AI活用

ComfyUIカスタムノードをV3へ移す|既存workflowを壊さない変更順

ComfyUIカスタムノードのV1からV3への移行で、定義・登録・実行メソッドの変更と、既存workflowを保つ確認順を整理します。Nodes 2.0の画面変更とは区別します。

この記事の目次
  1. V3は開発用の仕様で、Nodes 2.0の表示とは別
  2. 移行前にID・入力名・出力順を控える
  3. 小さなノードで登録から出力までを通す
  4. selfに保存していた状態を見直す
  5. 新規workflowだけでなく、保存済みのものを開く

自作ノードをV3へ移すときは、まず入出力と処理結果を変えずに、定義と登録方法だけを置き換えます。V3化と機能追加を同時に進めると、古いworkflowが壊れた原因を追いにくくなります。既に動くV1ノードを持つ開発者向けに、変更する場所と比較する順番を整理します。

V3は開発用の仕様で、Nodes 2.0の表示とは別

現行の公式ガイドでは、従来のINPUT_TYPESを使うV1も引き続きサポートされています。V3ではio.ComfyNodeを継承し、define_schemaで入出力などをまとめます。画面上のノードの見た目を切り替えるNodes 2.0とは違う話です。

V1だから直ちに使えなくなる、と考えて一括変換する必要はありません。保守しているノードのうち、外部サービスやモデルを使わない小さな処理から移すと、登録の問題と計算の問題を分けられます。初めて作る場合は、先にPythonカスタムノードの基本でフォルダーと読み込みの関係を確認してください。

スポンサーリンク

移行前にID・入力名・出力順を控える

利用者が保存したworkflowは、見た目の表示名だけで処理を特定しているわけではありません。移行前のノードID、入力名、ウィジェットの並び、出力の順番を記録します。表示名を整える作業と、接続先を変える作業を分けましょう。

変更前 V3で確認する場所
登録辞書のキー Schemaのnode_id
入力の辞書 Schemaのinputs
戻り値の型と順番 SchemaのoutputsとNodeOutput
FUNCTIONで指定した処理 クラスメソッドexecute

たとえば「幅、高さ」を返していたノードを「高さ、幅」に変えても、両方が数値なら読み込み時には気づきにくい場合があります。型が一致することに加え、各接続の意味も比較します。

小さなノードで登録から出力までを通す

次は整数を二倍にする独立した例です。既存ノードの置換コードではありません。検証用パックの__init__.pyへ置き、整数入力を受け取る下流ノードへつないで確認する想定です。

from comfy_api.latest import ComfyExtension, io

class DoubleCount(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="DevsExampleDoubleCount",
            display_name="Double Count",
            category="devs_examples",
            inputs=[io.Int.Input("count", default=2, min=0, max=100)],
            outputs=[io.Int.Output()],
        )

    @classmethod
    def execute(cls, count):
        return io.NodeOutput(count * 2)

class ExampleExtension(ComfyExtension):
    async def get_node_list(self):
        return [DoubleCount]

async def comfy_entrypoint():
    return ExampleExtension()

起動ログに登録エラーがないこと、検索で見つかること、入力2に対して4を下流で受け取れることを順に見ます。latestを使う例なので、確認したComfyUIの版も記録してください。このコードの実機動作は本記事では検証していません。

selfに保存していた状態を見直す

V3の実行メソッドはクラスメソッドです。V1の__init__やselfへ保存した値を、そのまま使える前提で移さないでください。ユーザーごとの入力や前回の結果を共有変数へ移すと、別の実行が混ざる原因になります。

入力だけで計算できる値は引数から導きます。外部リソースの管理が必要なら、その寿命と利用範囲を別に設計します。まずは状態を持たない処理を移し、その後にキャッシュや非同期処理へ範囲を広げると差分を小さく保てます。

新規workflowだけでなく、保存済みのものを開く

移行後の画面で作り直したworkflowが動いても、利用者の保存済みファイルが開くとは限りません。移行前に保存したGUI用JSONとAPI用JSONを残し、移行後に同じ入力で読み込み・実行・保存を確認します。入力名の変更や出力の追加が必要なら、互換性を別の変更として扱います。

2026年11月9日に確認した公式のV3移行ガイドを基準に、まず一つのノードだけでこの往復を通しましょう。戻すための旧版と試験用workflowは、workflowのGit管理と一緒に残すと再検証に使えます。

スポンサーリンク