Code-Node in n8n: wenn Standard-Nodes nicht reichen

Das meiste in n8n baut man ohne eine Zeile Code zusammen: Daten holen, umformen, verzweigen, weiterreichen. Irgendwann kommt aber die Aufgabe, für die kein fertiger Knoten passt – eine Berechnung über alle Datensätze, eine verschachtelte Struktur auseinandernehmen, eine Logik, die in Ausdrücken nur noch unlesbar wird. Genau dafür gibt es den Code-Node. Dieser Artikel zeigt, wie er arbeitet, welche zwei Ausführungsmodi es gibt, was er zurückgeben muss und wo seine Grenzen liegen – für alle, die selbst an Workflows bauen oder verstehen wollen, was der Baustein eigentlich tut.

Wann der Code-Node das richtige Werkzeug ist

Die n8n-Dokumentation nennt den Code-Node einen „escape hatch“ – die Notluke des Baukastens. Der Zweck laut Doku: „eigenes JavaScript oder Python schreiben und als Schritt im Workflow ausführen“. Das ist bewusst als Ausnahme gedacht, nicht als Standard. Solange ein fertiger Knoten oder ein Ausdruck die Aufgabe löst, sind die die bessere Wahl, weil jeder im Team sofort sieht, was passiert.

In Gesprächen mit Betrieben sehe ich zwei typische Situationen, in denen der Code-Node berechtigt ist: Erstens, wenn eine Transformation zu fummelig für den Edit-Fields-Node wird – also sobald Sie dort anfangen, in Ausdrücken zu programmieren. Zweitens, wenn Sie über eine ganze Liste rechnen müssen: Summen bilden, Datensätze gruppieren, Werte über mehrere Einträge hinweg vergleichen. Für das simple Umbenennen eines Feldes greifen Sie dagegen nicht zum Code.

Der Code-Node in n8n ist der „escape hatch“ des Baukastens: ein Baustein, in dem Sie eigenes JavaScript – seit Version 2.0 auch nativ Python – ausführen, wenn die fertigen Knoten einen Fall nicht abdecken. Er läuft entweder einmal für alle Datensätze oder einmal pro Datensatz und muss die Daten im n8n-Format zurückgeben: eine Liste von Objekten, jeweils mit dem Schlüssel json.

Die zwei Ausführungsmodi

Ganz oben im Node steht die entscheidende Einstellung: der Modus. Er bestimmt, wie oft Ihr Code läuft – und das ändert, wie Sie an die Daten kommen.

• Run Once for All Items (die Voreinstellung): Laut Doku läuft der Code „einmal, unabhängig davon, wie viele Eingangsdatensätze es gibt“. Sie bekommen die komplette Liste und geben eine komplette Liste zurück. Das ist der Modus für alles, was über den einzelnen Datensatz hinausgeht – Summen, Durchschnitte, Sortieren, Zusammenfassen.
• Run Once for Each Item: „Wählen Sie das, wenn Ihr Code für jeden Eingangsdatensatz laufen soll.“ Der Code wird pro Datensatz einmal ausgeführt, Sie arbeiten immer nur mit dem aktuellen Eintrag. Das ist der Modus für gleichartige Umformungen, die jeden Datensatz einzeln betreffen.

Die Faustregel: Rechnen Sie über Datensätze hinweg, nehmen Sie „All Items“. Formen Sie jeden Datensatz gleich um, ist „Each Item“ übersichtlicher – und der Code bleibt frei von Schleifen.

Was der Code-Node zurückgeben muss

Hier scheitern die meisten Einsteiger, deshalb lohnt der genaue Blick. n8n reicht Daten zwischen Knoten immer als Liste von Objekten durch, und jedes Objekt verpackt seine Nutzdaten unter dem Schlüssel json (Dateianhänge liegen parallel unter binary). Die Grundform sieht so aus:

[
  { "json": { "name": "Muster GmbH", "umsatz": 1190 } },
  { "json": { "name": "Beispiel AG", "umsatz": 2380 } }
]

Im Modus Run Once for All Items holen Sie sich die Eingangsliste über $input.all() und geben eine Liste im selben Format zurück:

// Run Once for All Items
const items = $input.all();
return items.map((item) => ({
  json: {
    name: item.json.firma,
    brutto: item.json.netto * 1.19,
  },
}));

Im Modus Run Once for Each Item arbeiten Sie mit dem aktuellen Datensatz – $json liefert dessen Inhalt direkt – und geben ein einzelnes Objekt zurück:

// Run Once for Each Item
return {
  json: {
    name: $json.firma,
    brutto: $json.netto * 1.19,
  },
};

n8n ist beim Verpacken nachsichtig: Fehlt der json-Schlüssel, ergänzt der Code-Node ihn laut Dokumentation automatisch und packt das Ergebnis bei Bedarf in eine Liste. Trotzdem lohnt es sich, die Struktur bewusst zu schreiben – dann verstehen Sie sofort, warum ein nachfolgender Knoten ein Feld findet oder eben nicht. Neben $input.all() gibt es $input.first() und $input.last() für den ersten und letzten Datensatz, und mit $('Name des Nodes') greifen Sie auf die Ausgabe eines beliebigen früheren Knotens zu.

JavaScript oder Python?

Der Code-Node beherrscht zwei Sprachen. JavaScript ist die Voreinstellung und läuft auf Node.js. Es unterstützt Promises – Sie dürfen also statt der fertigen Daten ein Promise zurückgeben, das n8n auflöst – und console.log schreibt beim Testen in die Ausführungsansicht, was beim Debuggen hilft.

Python hat sich mit n8n 2.0 verändert: Laut den Release-Notes läuft es jetzt nativ über sogenannte Task Runner; die frühere, im Browser über WebAssembly ausgeführte Variante (Pyodide) ist entfallen. Zwei Dinge sollten Sie dazu wissen: Python ist im Code-Node spürbar langsamer als JavaScript, und auf n8n Cloud lassen sich derzeit keine Python-Bibliotheken importieren. Wer nicht ohnehin an Python gebunden ist, fährt mit JavaScript meist unkomplizierter. Details und den aktuellen Stand halten Sie am besten in der offiziellen Code-Node-Dokumentation nach, weil sich gerade hier zwischen Versionen etwas bewegt.

Was der Code-Node nicht kann – und nicht soll

Der Code-Node ist kein Freifahrtschein. Zwei Grenzen sind ausdrücklich dokumentiert: „Sie können nicht auf das Dateisystem zugreifen und keine HTTP-Anfragen stellen.“ Beides ist Absicht. Für HTTP nehmen Sie den HTTP-Request-Node, für Dateien die Read/Write-Files-Nodes – die sind dafür gebaut, protokollieren sauber und lassen sich ohne Code konfigurieren.

Auch bei externen Bibliotheken gibt es Regeln. Auf n8n Cloud stehen im Code-Node nur zwei Module bereit: das crypto-Modul von Node.js und das npm-Paket moment. Auf einer selbst gehosteten Instanz lassen sich weitere npm-Pakete per Konfiguration freischalten. Das eingebaute crypto reicht für erstaunlich viel – etwa für den zeitkonstanten Vergleich beim Prüfen von Webhook-Signaturen, der sich zuverlässig nur im Code-Node umsetzen lässt.

Statt im Code-Node …	… der richtige Baustein
Daten von einer API holen	HTTP-Request-Node
Datei lesen oder schreiben	Read/Write-Files-Node
Externe Bibliothek nutzen (Cloud)	nur crypto und moment verfügbar

Wartbarkeit – der ehrliche Preis

Jede Zeile Code, die Sie in einen Workflow legen, ist eine Zeile, die jemand später lesen, verstehen und pflegen muss. Der große Vorteil von n8n – dass man einem Ablauf ansieht, was er tut – geht im Code-Node ein Stück verloren: Ein Knoten mit fünfzig Zeilen JavaScript verrät von außen nichts über seinen Inhalt. Meine Faustregel ist deshalb, den Code-Node bewusst klein zu halten, ihm einen sprechenden Namen zu geben und eine komplexe Aufgabe lieber in mehrere klar benannte Schritte zu zerlegen, als alles in einen Block zu quetschen.

Ob eine Aufgabe überhaupt Code braucht oder ob eine Plattform wie n8n sie mit Bordmitteln löst, ist am Ende dieselbe Frage wie bei der grundsätzlichen Entscheidung zwischen Low-Code und Eigenentwicklung: Man öffnet die Notluke genau dort, wo der Standard nicht reicht – und nur dort.

Der ehrliche Nutzen

Der Code-Node macht n8n von einem Baukasten zu einem Werkzeug ohne feste Obergrenze: Was sich mit fertigen Knoten nicht abbilden lässt, holen Sie sich mit ein paar Zeilen JavaScript zurück. Der Preis ist ein Stück Sichtbarkeit – deshalb sparsam einsetzen, klein halten, die Datenstruktur im Griff behalten.

Wenn Sie überlegen, welche Prozesse sich in Ihrem Betrieb sauber automatisieren lassen, oder eine bestehende n8n-Umgebung ordentlich aufsetzen wollen: In einem kostenlosen Prozess-Check schauen wir uns Ihren konkreten Fall gemeinsam an. Und wenn Sie tiefer in die Umsetzung wollen, finden Sie in der n8n-Beratung den passenden Rahmen dafür.