نود Code در N8N

نود Code یکی از قدرتمندترین نودهای N8N است که به شما اجازه می‌دهد داخل ورکفلو، کد اختصاصی بنویسید و داده‌ها را دقیقاً مطابق نیاز خود پردازش، تبدیل، فیلتر، ترکیب یا آماده‌سازی کنید. هرجا نودهای آماده N8N برای منطق دلخواه شما کافی نباشند، نود Code نقش یک ابزار انعطاف‌پذیر و حرفه‌ای را بازی می‌کند.

معرفی نود در N8N

نود Code برای اجرای کد سفارشی در جریان اجرای ورکفلو استفاده می‌شود. این نود معمولاً برای تغییر ساختار داده‌ها، انجام محاسبات، ساخت خروجی‌های سفارشی، ترکیب چند فیلد، پاک‌سازی داده‌ها، تولید شرط‌های پیچیده و آماده‌سازی اطلاعات برای ارسال به سرویس‌های دیگر کاربرد دارد.

نام نود: Code
دسته‌بندی: Function
نوع عملکرد: پردازش و تغییر داده با کدنویسی سفارشی
زبان‌های قابل استفاده: JavaScript و در نسخه‌های جدید N8N، Python نیز بسته به محیط و نسخه نصب‌شده
جایگزین نودهای قدیمی: Function و Function Item در بسیاری از سناریوها

اهمیت نود Code در این است که محدودیت‌های نودهای آماده را کاهش می‌دهد. برای مثال اگر بخواهید داده‌های دریافتی از یک API را به یک ساختار خاص تبدیل کنید، فیلدهای اضافی را حذف کنید، تاریخ‌ها را استاندارد کنید یا چند آیتم را به یک آیتم خلاصه تبدیل کنید، نود Code یکی از بهترین گزینه‌هاست.

موارد استفاده

نود Code در پروژه‌های واقعی اتوماسیون بسیار پرکاربرد است، مخصوصاً زمانی که داده‌ها دقیقاً با ساختار موردنیاز نودهای بعدی هماهنگ نیستند.

تبدیل ساختار داده‌ها

فرض کنید از یک API لیستی از کاربران دریافت می‌کنید، اما نود بعدی فقط به نام، ایمیل و وضعیت کاربر نیاز دارد. با نود Code می‌توانید فقط همین فیلدها را نگه دارید.

return $input.all().map(item => {  return {    json: {      name: item.json.full_name,      email: item.json.email_address,      status: item.json.is_active ? 'active' : 'inactive'    }  };});

فیلتر کردن داده‌ها

اگر بخواهید فقط سفارش‌هایی که مبلغ آن‌ها بیشتر از یک مقدار مشخص است وارد مرحله بعد شوند، می‌توانید از Code استفاده کنید.

return $input.all().filter(item => item.json.total_price > 1000000);

محاسبه و ساخت فیلدهای جدید

در یک ورکفلو فروش، ممکن است بخواهید مبلغ نهایی سفارش را با مالیات محاسبه کنید.

return $input.all().map(item => {  const price = item.json.price;  const tax = price * 0.09;  return {    json: {      ...item.json,      tax,      final_price: price + tax    }  };});

ترکیب با نودهای دیگر

Webhook + Code + Google Sheets: دریافت داده از فرم، پاک‌سازی داده‌ها و ذخیره در گوگل شیت.
HTTP Request + Code + Telegram: دریافت اطلاعات از API، خلاصه‌سازی متن و ارسال پیام در تلگرام.
Schedule Trigger + Code + Email: اجرای روزانه، بررسی داده‌ها و ارسال گزارش ایمیلی.
Postgres + Code + Slack: دریافت داده از دیتابیس، ساخت گزارش سفارشی و ارسال به اسلک.
IF + Code + CRM: بررسی شرط‌های پیچیده و ارسال لیدهای واجد شرایط به سیستم CRM.

پارامترها و تنظیمات

تنظیمات نود Code ساده به نظر می‌رسند، اما انتخاب درست آن‌ها تأثیر زیادی روی خروجی ورکفلو دارد.

Language

نوع داده: انتخابی
گزینه‌ها: JavaScript، Python در نسخه‌ها و محیط‌های پشتیبانی‌شده
کاربرد: مشخص می‌کند کد داخل نود با چه زبانی اجرا شود.
مثال عملی: اگر بیشتر با اکوسیستم N8N و نمونه‌های مستندات کار می‌کنید، JavaScript معمولاً انتخاب استانداردتر و رایج‌تر است.

نکته مهم: امکانات Python ممکن است بسته به نسخه N8N، نوع نصب و محیط اجرایی متفاوت باشد. برای بیشترین سازگاری، مخصوصاً در ورکفلوهای قابل انتقال، JavaScript انتخاب مطمئن‌تری است.

Mode

نوع داده: انتخابی
گزینه‌ها: Run Once for All Items، Run Once for Each Item
کاربرد: مشخص می‌کند کد شما یک‌بار برای کل آیتم‌ها اجرا شود یا برای هر آیتم جداگانه.

Run Once for All Items

در این حالت، کد فقط یک‌بار اجرا می‌شود و به همه آیتم‌های ورودی دسترسی دارد. این حالت برای کارهایی مثل تجمیع، گروه‌بندی، فیلتر کردن گروهی، تبدیل لیست‌ها و ساخت گزارش مناسب است.

const items = $input.all();const total = items.reduce((sum, item) => {  return sum + item.json.amount;}, 0);return [  {    json: {      total_amount: total,      count: items.length    }  }];

Run Once for Each Item

در این حالت، کد برای هر آیتم ورودی به‌صورت جداگانه اجرا می‌شود. این حالت برای تغییر ساده هر ردیف، اضافه کردن فیلد جدید یا فرمت کردن داده‌ها مناسب است.

$json.fullName = `${$json.firstName} ${$json.lastName}`;return {  json: $json};

Code

نوع داده: متن کد
کاربرد: محل نوشتن منطق سفارشی برای پردازش داده‌ها.
مثال عملی: تبدیل شماره موبایل به فرمت استاندارد.

return $input.all().map(item => {  let mobile = item.json.mobile || '';  mobile = mobile.replace(/s/g, '');  if (mobile.startsWith('0')) {    mobile = '+98' + mobile.substring(1);  }  return {    json: {      ...item.json,      mobile    }  };});

Always Output Data

نوع داده: Boolean
کاربرد: اگر فعال باشد، حتی در شرایطی که نود خروجی تولید نکند، اجرای ورکفلو می‌تواند با خروجی خالی یا پیش‌فرض ادامه پیدا کند.
مثال عملی: زمانی که فیلتر شما ممکن است همه آیتم‌ها را حذف کند اما نمی‌خواهید ورکفلو کاملاً متوقف شود.

On Error

نوع داده: انتخابی
گزینه‌های رایج: Stop Workflow، Continue، Continue using Error Output در نسخه‌های پشتیبانی‌شده
کاربرد: تعیین می‌کند اگر اجرای کد با خطا مواجه شد، ورکفلو متوقف شود یا مسیر جایگزین ادامه پیدا کند.
مثال عملی: در پردازش داده‌های حساس مالی بهتر است Stop Workflow انتخاب شود، اما در پردازش لیست‌های بزرگ می‌توان خطاها را جداگانه لاگ کرد.

Retry On Fail

نوع داده: Boolean
کاربرد: اجرای مجدد نود در صورت شکست، مخصوصاً زمانی مفید است که کد شما به سرویس بیرونی یا عملیات ناپایدار وابسته باشد.
نکته: اگر خطا مربوط به منطق کدنویسی باشد، Retry معمولاً مشکل را حل نمی‌کند.

نکات مهم هنگام پیکربندی

در حالت Run Once for All Items خروجی باید آرایه‌ای از آیتم‌ها باشد.
هر آیتم خروجی معمولاً باید ساختار { json: { ... } } داشته باشد.
برای داده‌های باینری باید فیلد binary را نیز در خروجی حفظ کنید.
در حالت Run Once for Each Item معمولاً یک آیتم برگردانده می‌شود.
از عملیات سنگین و حلقه‌های بسیار بزرگ بدون کنترل پرهیز کنید، چون می‌تواند اجرای ورکفلو را کند کند.
در محیط‌های n8n Cloud دسترسی به برخی ماژول‌ها و کتابخانه‌های خارجی محدود است.

ورودی‌ها و خروجی‌ها

نود Code معمولاً داده‌ها را از نود قبلی به‌صورت آیتم دریافت می‌کند. هر آیتم در N8N معمولاً شامل بخش json و گاهی بخش binary است.

نمونه ورودی

[  {    "json": {      "id": 1,      "firstName": "Ali",      "lastName": "Ahmadi",      "amount": 250000    }  },  {    "json": {      "id": 2,      "firstName": "Sara",      "lastName": "Karimi",      "amount": 430000    }  }]

نمونه کد برای پردازش ورودی

return $input.all().map(item => {  return {    json: {      id: item.json.id,      fullName: `${item.json.firstName} ${item.json.lastName}`,      amount: item.json.amount,      amountLabel: item.json.amount.toLocaleString('fa-IR') + ' تومان'    }  };});

نمونه خروجی

[  {    "json": {      "id": 1,      "fullName": "Ali Ahmadi",      "amount": 250000,      "amountLabel": "۲۵۰٬۰۰۰ تومان"    }  },  {    "json": {      "id": 2,      "fullName": "Sara Karimi",      "amount": 430000,      "amountLabel": "۴۳۰٬۰۰۰ تومان"    }  }]

دسترسی به داده‌های ورودی در JavaScript

$input.all(): دریافت همه آیتم‌های ورودی.
$input.first(): دریافت اولین آیتم ورودی.
$input.last(): دریافت آخرین آیتم ورودی.
$json: دسترسی مستقیم به JSON آیتم جاری در حالت Run Once for Each Item.
$binary: دسترسی به داده‌های باینری آیتم جاری، مانند فایل، تصویر یا PDF.
$itemIndex: شماره آیتم جاری در برخی حالت‌ها.
$node["Node Name"].json: دسترسی به خروجی یک نود قبلی با نام مشخص.
$workflow: دسترسی به اطلاعات ورکفلو.
$execution: دسترسی به اطلاعات اجرای فعلی.
$env: دسترسی به متغیرهای محیطی در محیط‌های پشتیبانی‌شده.

حفظ داده‌های باینری در خروجی

اگر آیتم ورودی شامل فایل باشد و شما فقط بخش json را برگردانید، ممکن است فایل در مراحل بعدی از دست برود. برای حفظ فایل، بخش binary را هم منتقل کنید.

return $input.all().map(item => {  return {    json: {      ...item.json,      processed: true    },    binary: item.binary  };});

نکات پیشرفته و ترفندها

استفاده از async و await

در JavaScript می‌توانید از کدهای asynchronous استفاده کنید. این قابلیت زمانی مفید است که نیاز به عملیات زمان‌بر، فراخوانی کمکی یا پردازش غیرهمزمان دارید.

const items = $input.all();const results = [];for (const item of items) {  results.push({    json: {      ...item.json,      processedAt: new Date().toISOString()    }  });}return results;

گروه‌بندی داده‌ها

برای ساخت گزارش از سفارش‌ها بر اساس وضعیت، می‌توانید آیتم‌ها را گروه‌بندی کنید.

const items = $input.all();const grouped = {};for (const item of items) {  const status = item.json.status || 'unknown';  if (!grouped[status]) {    grouped[status] = {      count: 0,      total: 0    };  }  grouped[status].count += 1;  grouped[status].total += item.json.amount || 0;}return Object.keys(grouped).map(status => {  return {    json: {      status,      count: grouped[status].count,      total: grouped[status].total    }  };});

اعتبارسنجی داده‌ها قبل از ارسال به API

قبل از ارسال داده به CRM، درگاه پرداخت یا سیستم ایمیل مارکتینگ، می‌توانید داده‌ها را بررسی و فقط آیتم‌های معتبر را عبور دهید.

return $input.all().filter(item => {  const email = item.json.email || '';  const mobile = item.json.mobile || '';  const validEmail = /^[^s@]+@[^s@]+.[^s@]+$/.test(email);  const validMobile = mobile.length >= 10;  return validEmail && validMobile;});

ساخت خروجی مناسب برای ارسال پیام

برای ارسال گزارش به Telegram یا Slack، می‌توانید متن پیام را داخل نود Code بسازید.

const items = $input.all();const lines = items.map(item => {  return `#${item.json.id} - ${item.json.customer}: ${item.json.amount} تومان`;});return [  {    json: {      message: lines.join('n')    }  }];

کاهش تعداد آیتم‌ها برای بهینه‌سازی

اگر نودهای بعدی مثل API یا Email محدودیت نرخ دارند، می‌توانید تعداد آیتم‌ها را در Code کنترل کنید.

const items = $input.all();return items.slice(0, 50);

حذف فیلدهای حساس

قبل از ارسال داده به سرویس‌های خارجی، فیلدهایی مانند رمز عبور، توکن، کد ملی یا اطلاعات محرمانه را حذف کنید.

return $input.all().map(item => {  const data = { ...item.json };  delete data.password;  delete data.accessToken;  delete data.nationalId;  return {    json: data  };});

محدودیت‌ها و خطاها

محدودیت‌ها

نود Code برای پردازش‌های بسیار سنگین و طولانی‌مدت مناسب نیست و ممکن است باعث کندی یا timeout شود.
در n8n Cloud امکان نصب یا استفاده آزادانه از همه کتابخانه‌های خارجی وجود ندارد.
دسترسی به فایل‌سیستم، ماژول‌های سیستمی یا منابع خارجی بسته به تنظیمات امنیتی محیط محدود است.
خروجی نادرست، مانند برگرداندن یک آبجکت ساده به‌جای آرایه در حالت Run Once for All Items، باعث خطا می‌شود.
اگر داده باینری را در خروجی حفظ نکنید، فایل‌ها در نودهای بعدی در دسترس نخواهند بود.
کدهای وابسته به نسخه خاص Node.js یا امکانات خاص محیط ممکن است در سرور دیگر به‌درستی اجرا نشوند.

خطای رایج: خروجی باید آرایه باشد

در حالت Run Once for All Items، اگر خروجی را به‌صورت آبجکت برگردانید، ممکن است با خطا مواجه شوید.

اشتباه:

return {  json: {    success: true  }};

درست:

return [  {    json: {      success: true    }  }];

خطای رایج: فراموش کردن json

هر آیتم خروجی باید معمولاً دارای کلید json باشد.

اشتباه:

return [  {    name: 'Ali'  }];

درست:

return [  {    json: {      name: 'Ali'    }  }];

خطای رایج: دسترسی به فیلد ناموجود

اگر فیلدی در بعضی آیتم‌ها وجود نداشته باشد، کد ممکن است خطا بدهد.

راه‌حل: از مقدار پیش‌فرض یا Optional Chaining استفاده کنید.

return $input.all().map(item => {  return {    json: {      city: item.json.address?.city || 'نامشخص'    }  };});

خطای رایج: از دست رفتن binary

وقتی فایل‌ها را پردازش می‌کنید، حتماً binary را به خروجی منتقل کنید.

return $input.all().map(item => {  return {    json: {      ...item.json,      checked: true    },    binary: item.binary  };});

خطای رایج: استفاده از کتابخانه خارجی بدون مجوز

در نصب‌های Self-hosted می‌توان با تنظیم متغیرهای محیطی مشخص، استفاده از برخی ماژول‌ها را فعال کرد، اما در محیط Cloud این امکان محدودتر است.

NODE_FUNCTION_ALLOW_BUILTIN: برای اجازه به ماژول‌های داخلی Node.js در محیط‌های پشتیبانی‌شده.
NODE_FUNCTION_ALLOW_EXTERNAL: برای اجازه به پکیج‌های خارجی نصب‌شده در محیط‌های پشتیبانی‌شده.

ایده ها

سیستم امتیازدهی لیدها: دریافت لید از فرم یا CRM، محاسبه امتیاز بر اساس شهر، بودجه، منبع ورودی و رفتار کاربر، سپس ارسال لیدهای باکیفیت به تیم فروش.
گزارش‌ساز روزانه فروش: دریافت سفارش‌ها از دیتابیس، گروه‌بندی بر اساس وضعیت، محاسبه مجموع فروش و ارسال گزارش به تلگرام یا ایمیل.
پاک‌سازی هوشمند داده‌های فرم: استانداردسازی شماره موبایل، حذف فاصله‌ها، اصلاح ایمیل، حذف فیلدهای اضافی و ذخیره خروجی تمیز در Google Sheets.
ساخت پیام‌های شخصی‌سازی‌شده: ترکیب نام، محصول خریداری‌شده و تاریخ سفارش برای تولید پیام اختصاصی جهت ارسال با SMS، WhatsApp یا Email.
کنترل کیفیت داده قبل از ارسال به API: بررسی معتبر بودن فیلدها، حذف آیتم‌های ناقص، ساخت خروجی استاندارد و جلوگیری از خطا در سرویس‌های خارجی.