n8n Code Node JavaScript: tutorial de depuración
Tutorial de JavaScript en el nodo Code de n8n: modos de ejecución, acceso a datos, código async, depuración con console.log y errores de vinculación en producción.
Comprobado con las fuentes citadas el .
Primeros pasos con JavaScript en el nodo Code de n8n
Un script bien construido en el entorno JavaScript del nodo Code de n8n puede sustituir a varios nodos habituales con unas pocas líneas de lógica, pero los pequeños errores en cómo se cuentan o se devuelven los ítems pueden pasar desapercibidos hasta que el flujo de trabajo se ejecuta con datos reales. Este tutorial cubre cómo configurar un nodo Code, elegir el modo de ejecución adecuado, leer los datos de los ítems de forma segura, manejar código asíncrono y depurar con console.log, y luego qué cambia cuando ese mismo script tiene que ejecutarse contra datos reales de una API en producción.
Para seguir este tutorial necesitas un flujo de trabajo de n8n existente con al menos un nodo que produzca datos de ejemplo, además de un nodo Code colocado después de él y configurado para ejecutarse en modo JavaScript en lugar de Python. Este tutorial asume una familiaridad básica con la adición de nodos al lienzo y la trata como una navegación habitual, no como un paso de depuración. El objetivo a continuación es un pequeño script que lee los datos de los ítems entrantes, los transforma y registra su propio progreso, primero con un ítem de ejemplo y después con una respuesta realista de varios ítems.
Elige un modo de ejecución y accede a los datos de los ítems
El nodo Code ofrece dos modos de ejecución. Run Once for All Items es el predeterminado: el script se ejecuta una sola vez sin importar cuántos ítems lleguen, por lo que debe recorrer la entrada por sí mismo. Run Once for Each Item, en cambio, ejecuta el script por separado para cada ítem, lo que resulta más fácil de razonar mientras el script sigue siendo pequeño.
- Elige un modo de ejecución: Run Once for All Items o Run Once for Each Item.
- Accede a los datos de los ítems con $json, $input.item, $input.all() o una referencia a un nodo anterior.
- Maneja código síncrono o asíncrono, devolviendo una Promise cuando sea necesario.
- Depura con console.log mientras el script todavía sea pequeño.
Dentro del script, $json es un atajo para los datos JSON del ítem de entrada actual, y $input.item devuelve ese mismo ítem actual de forma explícita. $input.all() devuelve todos los ítems de entrada como un array, que es sobre lo que recorre un script en modo Run Once for All Items. Cuando un script necesita un campo de un nodo anterior en lugar de su entrada inmediata, $('Node Name').item.json obtiene directamente los datos de ese ítem vinculado.
| Atajo | Devuelve | Uso típico |
|---|---|---|
| $json | JSON del ítem de entrada actual | Lecturas rápidas dentro de Run Once for Each Item |
| $input.item | El ítem que se está procesando actualmente | Equivalente explícito de $json |
| $input.all() | Array con todos los ítems de entrada | Recorrer ítems en Run Once for All Items |
| $('Node Name').item.json | JSON del ítem vinculado de un nodo anterior | Obtener un campo que no está en el ítem actual |
Sources: Using the Code node | Build | n8n Docs, Reference previous nodes | Build | n8n Docs, Nodeinputdata | Build | n8n Docs
Maneja código asíncrono y depura con console.log
La mayoría de los scripts de transformación cortos son síncronos, pero el nodo Code también admite JavaScript asíncrono: en lugar de devolver los ítems directamente, un script puede devolver una Promise que n8n espera y resuelve antes de pasar los datos a los siguientes nodos. Esto importa cuando el JavaScript del nodo Code de n8n necesita esperar una operación en lugar de calcular un resultado de inmediato.
Para depurar, la propia documentación de n8n menciona console.log como una forma admitida de escribir en la consola desde dentro del nodo Code, útil para comprobar un valor o confirmar que un paso de transformación se ejecutó. Anthony Sidashin, un desarrollador que escribió sobre el uso de n8n desde la perspectiva de un desarrollador, describió este comportamiento a partir de su propia experiencia práctica con el nodo Code.
Sources: Using the Code node | Build | n8n Docs, My experience using n8n, from a developer perspective
Resultados esperados y solución de errores comunes del nodo Code
Después de ejecutar el nodo con un ítem de ejemplo, el panel de salida debería mostrar uno o más ítems, cada uno con una clave json, tal como n8n pasa los datos entre nodos: como un array de objetos envueltos en json. Si el valor devuelto por el script no coincide con esa forma, o no devuelve nada, el nodo genera un error de 'no devuelve los ítems correctamente' en lugar de pasar datos incorrectos de forma silenciosa.
Hay algunos otros errores que aparecen repetidamente cuando un script crece más allá de un único ítem de prueba, resumidos a continuación.
| Error | Causa probable | Solución |
|---|---|---|
| "No devuelve los ítems correctamente" | El valor devuelto no es un array de objetos envueltos en json | Devuelve un array donde cada ítem tenga una clave json |
| "Cannot find module" | El script importa un paquete npm externo no disponible en esa instancia | Instala y autoriza el módulo en un n8n autoalojado, o evita las importaciones externas en n8n Cloud |
| El nodo Code no puede leer una credencial | Por diseño, los nodos Code no pueden acceder a las credenciales guardadas | Obtén los datos autenticados con un nodo HTTP Request y pasa solo su JSON al nodo Code |
Sources: Common issues | Nodes | n8n Docs, Using the Code node | Build | n8n Docs
De datos de prueba a datos reales de una API en producción
Ejecutar el JavaScript del nodo Code de n8n contra datos reales de una API en producción cambia un supuesto que funcionaba bien con un único ítem de ejemplo: n8n solo gestiona la vinculación de ítems automáticamente cuando hay un único ítem de entrada. Cuando un script procesa una respuesta de la API con varios ítems, o crea ítems nuevos en lugar de pasar los mismos, esa vinculación automática deja de cubrir el resultado, y los nodos posteriores pueden perder el rastro de qué salida procede de qué entrada.
La solución es establecer pairedItem de forma explícita en cada ítem que devuelve el script, para que los nodos posteriores puedan seguir rastreando un resultado hasta su origen. Los límites de credenciales y módulos mencionados antes importan aún más aquí, ya que los scripts en producción son precisamente donde un equipo recurre a un paquete externo u olvida que las llamadas autenticadas pertenecen al nodo HTTP Request, no al nodo Code.
Sources: Preserving linking in the Code node | Build | n8n Docs
