مستندات n8n
74+ نود
💻

کد

Code

اجرای کد JavaScript/Python برای پردازش و محاسبات سفارشی

ابزارهای توسعه
پیشرفته
۰ بازدید
n8n 1.0+

نمای کلی

نود Code چیست؟

نود Code قدرتمندترین نود n8n است که به شما امکان می‌دهد کد JavaScript یا Python بنویسید و در ورک‌فلو اجرا کنید. این نود برای موارد زیر ایده‌آل است:

  • پردازش پیچیده داده‌ها
  • محاسبات سفارشی و ریاضیاتی
  • تبدیل فرمت داده‌ها (JSON, XML, CSV)
  • فیلتر و مرتب‌سازی پیشرفته
  • رمزنگاری و امنیت
  • فراخوانی API‌های سفارشی
  • هر منطق خاصی که با نودهای استاندارد ممکن نیست

حالت‌های اجرا

1. Run Once for All Items

کد یکبار اجرا می‌شود و به همه آیتم‌های ورودی دسترسی دارد. مناسب برای:

  • محاسبه مجموع یا میانگین
  • گروه‌بندی داده‌ها
  • مقایسه آیتم‌ها با هم

2. Run Once for Each Item

کد برای هر آیتم جداگانه اجرا می‌شود. مناسب برای:

  • تبدیل هر آیتم
  • اعتبارسنجی داده‌ها
  • افزودن فیلد به هر آیتم

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

در JavaScript:

javascript
// همه آیتم‌های ورودی
const items = $input.all();

// آیتم اول
const firstItem = $input.first();

// آیتم فعلی (در حالت Run for Each)
const currentItem = $input.item;

// داده JSON آیتم
const data = items[0].json;

در Python:

python
# همه آیتم‌ها
items = _input.all()

# آیتم اول
first_item = _input.first()

# داده JSON
data = items[0]['json']

احراز هویت

احراز هویت

نود Code نیاز به احراز هویت خاصی ندارد.

دسترسی به Credentials دیگر نودها

اگر نیاز دارید در کد خود به credentials استفاده شده در نودهای دیگر دسترسی داشته باشید:

javascript
// دسترسی به متغیرهای محیطی (Environment Variables)
const apiKey = $env.MY_API_KEY;

// استفاده از HTTP Request داخلی
const response = await $http.request({
  method: 'GET',
  url: 'https://api.example.com/data',
  headers: {
    'Authorization': 'Bearer ' + apiKey
  }
});

نکات امنیتی

⚠️ هرگز اطلاعات حساس (API Key, Password) را مستقیم در کد ننویسید.

✅ از Environment Variables یا Credentials استفاده کنید.

عملیات‌های موجود

1

runOnceForAllItems

کد یکبار اجرا می‌شود و به همه آیتم‌ها دسترسی دارد

2

runOnceForEachItem

کد برای هر آیتم جداگانه اجرا می‌شود

کاربردهای متداول

کاربردهای رایج

۱. تبدیل ساختار داده (Data Transformation)

تغییر ساختار JSON برای سازگاری با API یا سرویس مقصد. مثلاً تبدیل flat object به nested، یا برعکس.

javascript
// تبدیل آرایه flat به ساختار درختی
const items = $input.all();
const flat = items.map(i => i.json);
const tree = flat.reduce((acc, item) => {
  const cat = item.category;
  if (!acc[cat]) acc[cat] = { name: cat, items: [] };
  acc[cat].items.push(item);
  return acc;
}, {});
return Object.values(tree).map(g => ({ json: g }));

۲. محاسبات مالی و حسابداری

محاسبه جمع فاکتور، مالیات بر ارزش افزوده، تخفیف، و تبدیل ارز.

javascript
const items = $input.all();
const orders = items.map(i => i.json);
const subtotal = orders.reduce((sum, o) => sum + o.amount, 0);
const tax = Math.round(subtotal * 0.09); // ۹% مالیات
const discount = subtotal > 1000000 ? Math.round(subtotal * 0.1) : 0;
const total = subtotal + tax - discount;
return [{ json: { subtotal, tax, discount, total,
  formatted: total.toLocaleString('fa-IR') + ' تومان' } }];

۳. پردازش متن و Regex

استخراج اطلاعات از متن با Regular Expressions: شماره موبایل، ایمیل، کد ملی، URL.

javascript
const text = $input.first().json.message;
const phones = text.match(/09[0-9]{9}/g) || [];
const emails = text.match(/[\w.-]+@[\w.-]+\.[a-z]{2,}/gi) || [];
const urls = text.match(/https?:\/\/[^\s]+/g) || [];
return [{ json: { phones, emails, urls } }];

۴. اعتبارسنجی داده‌ها (Validation)

بررسی صحت داده‌های ورودی قبل از ذخیره در دیتابیس یا ارسال به API.

javascript
const item = $input.first().json;
const errors = [];
if (!item.email?.match(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)) errors.push('ایمیل نامعتبر');
if (!item.phone?.match(/^09\d{9}$/)) errors.push('موبایل نامعتبر');
if (!item.name || item.name.length < 2) errors.push('نام کوتاه است');
return [{ json: { isValid: errors.length === 0, errors, data: item } }];

۵. تبدیل تاریخ میلادی/شمسی

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

javascript
const date = new Date($input.first().json.date);
const persian = date.toLocaleDateString('fa-IR', {
  year: 'numeric', month: 'long', day: 'numeric',
  weekday: 'long'
});
return [{ json: { original: date.toISOString(), persian } }];

۶. Deduplication (حذف تکراری‌ها)

حذف آیتم‌های تکراری بر اساس یک فیلد خاص (مثل email یا phone).

javascript
const items = $input.all();
const seen = new Set();
const unique = items.filter(item => {
  const key = item.json.email;
  if (seen.has(key)) return false;
  seen.add(key);
  return true;
});
return unique;

۷. Pagination Handler

مدیریت pagination برای APIهایی که داده‌ها را صفحه‌ای برمی‌گردانند.

javascript
const allData = [];
let page = 1;
let hasMore = true;
while (hasMore) {
  const res = await $http.request({
    url: 'https://api.example.com/data?page=' + page + '&limit=100'
  });
  allData.push(...res.body.data);
  hasMore = res.body.data.length === 100;
  page++;
}
return allData.map(d => ({ json: d }));

۸. ساخت پیام Telegram/Slack

فرمت‌بندی داده‌ها به صورت پیام خوانا با Markdown یا HTML.

javascript
const order = $input.first().json;
const msg = `🛒 *سفارش جدید #${order.id}*
👤 ${order.customer}
💰 ${order.total.toLocaleString()} تومان
📦 ${order.items.length} محصول
📅 ${new Date().toLocaleDateString('fa-IR')}`;
return [{ json: { message: msg } }];

۹. تولید CSV/Excel

تبدیل داده‌های JSON به فرمت CSV برای export و گزارش‌گیری.

۱۰. Merge/Join داده‌ها

ترکیب داده‌ها از چندین منبع بر اساس کلید مشترک (مشابه SQL JOIN).

javascript
const orders = $('Node1').all().map(i => i.json);
const customers = $('Node2').all().map(i => i.json);
const merged = orders.map(order => {
  const customer = customers.find(c => c.id === order.customerId);
  return { json: { ...order, customer } };
});
return merged;

نکات حرفه‌ای

نکات حرفه‌ای

۱. همیشه آرایه با ساختار صحیح برگردانید

javascript
// صحیح: آرایه‌ای از آبجکت‌ها با کلید json
return items.map(item => ({ json: { ...item.json, newField: 'value' } }));

۲. از Optional Chaining و Nullish Coalescing استفاده کنید

javascript
const value = data?.nested?.deep?.field ?? 'پیش‌فرض';
const count = data?.items?.length ?? 0;

۳. Debug با console.log

خروجی console.log در Execution Log نمایش داده می‌شود:

javascript
console.log('Items count:', items.length);
console.log('Data:', JSON.stringify(data, null, 2));

۴. دسترسی به داده‌های نودهای دیگر

javascript
// داده نود خاص (با نام)
const prevData = $('نام نود').all();
const firstItem = $('نام نود').first();

// آخرین نود
const lastData = $input.all();

۵. استفاده از Environment Variables

اطلاعات حساس را در Environment Variables ذخیره کنید:

javascript
const apiKey = $env.MY_API_KEY;
const baseUrl = $env.API_BASE_URL;

۶. مدیریت خطا با try/catch

javascript
try {
  const result = await someOperation();
  return [{ json: { success: true, data: result } }];
} catch (error) {
  return [{ json: { success: false, error: error.message } }];
}

۷. ماژول‌های مجاز Node.js

این ماژول‌ها در Code node قابل استفاده‌اند: crypto, url, querystring, path, Buffer, Date, Math, JSON, RegExp.

۸. Run Once for All vs Run for Each

  • All Items: وقتی نیاز به مقایسه یا aggregation بین آیتم‌ها دارید
  • Each Item: وقتی هر آیتم مستقل پردازش می‌شود

۹. Performance Tips

  • از Map و Set برای lookup سریع استفاده کنید
  • از Array.reduce بجای حلقه‌های تو در تو
  • داده‌های بزرگ را stream کنید
  • عملیات async را parallel اجرا کنید

۱۰. Binary Data

برای کار با فایل‌ها (تصویر، PDF، CSV):

javascript
// خواندن binary
const binaryData = items[0].binary.data;
const buffer = Buffer.from(binaryData.data, 'base64');

// ایجاد binary
return [{ json: {}, binary: {
  data: { data: Buffer.from('content').toString('base64'),
          mimeType: 'text/csv', fileName: 'export.csv' }
}}];

۱۱. دسترسی به Workflow Info

javascript
const workflowId = $workflow.id;
const workflowName = $workflow.name;
const executionId = $execution.id;
const isTestRun = $execution.mode === 'manual';

۱۲. Timestamp و تاریخ فارسی

javascript
const now = new Date();
const persian = now.toLocaleDateString('fa-IR');
const timestamp = Math.floor(now.getTime() / 1000);

۱۳. کار با Python

Python در Code node با sandbox اجرا می‌شود. از _input (با underscore) بجای $input استفاده کنید.

۱۴. Reusable Functions

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

javascript
function formatPrice(amount) {
  return amount.toLocaleString('fa-IR') + ' تومان';
}

۱۵. Conditional Output

برای ارسال داده به مسیرهای مختلف:

javascript
// فقط آیتم‌های معتبر برگردانید
const valid = items.filter(i => i.json.isValid);
if (valid.length === 0) return []; // خروجی خالی = توقف مسیر
return valid;

رفع مشکلات

رفع مشکلات رایج

❌ خطای SyntaxError

علت: اشکال در نوشتار کد (پرانتز، براکت، نقطه‌ویرگول)

راه‌حل

  • کد را در VS Code یا editor دیگر بررسی کنید
  • از linter استفاده کنید
  • مطمئن شوید همه پرانتزها بسته شده‌اند

❌ خطای "Cannot read property of undefined"

علت: دسترسی به فیلدی که وجود ندارد

راه‌حل

javascript
// بد ❌
const name = item.json.user.name;

// خوب ✅ - Optional Chaining
const name = item.json?.user?.name || 'پیش‌فرض';

❌ خطای Timeout (کد بیش از حد طول می‌کشد)

علت: حلقه‌های سنگین یا درخواست‌های API زیاد

راه‌حل

  • از حلقه‌های بهینه استفاده کنید
  • $http.request را بجای fetch استفاده کنید
  • داده‌های بزرگ را batch کنید
  • از async parallel بجای sequential استفاده کنید

❌ خطای "Module not found"

علت: ماژول درخواستی در n8n وجود ندارد

راه‌حل

  • فقط ماژول‌های built-in Node.js مجاز هستند: crypto, url, querystring, path, Buffer
  • ماژول‌های npm خارجی مستقیماً قابل import نیستند
  • از $http.request بجای axios یا node-fetch استفاده کنید
  • در n8n self-hosted، admin می‌تواند ماژول‌های مجاز را تنظیم کند

❌ خروجی خالی (Empty Output)

علت: return نادرست

راه‌حل

  • حتماً آرایه‌ای از آبجکت‌ها با کلید json برگردانید:
javascript
// صحیح ✅
return [{ json: { result: 'مقدار' } }];

// اشتباه ❌ - آرایه نیست
return { json: { result: 'مقدار' } };

// اشتباه ❌ - کلید json ندارد
return [{ result: 'مقدار' }];

❌ خطای "items is not iterable"

علت: خروجی نود قبلی خالی است

راه‌حل

javascript
const items = $input.all();
if (!items || items.length === 0) {
  return [{ json: { error: 'داده‌ای دریافت نشد' } }];
}

❌ مشکل Encoding فارسی

علت: مشکل در encode/decode کاراکترهای فارسی

راه‌حل

  • از encodeURIComponent() برای URL استفاده کنید
  • JSON.stringify به صورت پیش‌فرض Unicode را handle می‌کند
  • برای Binary data از Buffer.from(text, 'utf-8') استفاده کنید

❌ خطای "Execution data is too large"

علت: حجم داده‌های خروجی بیش از حد مجاز

راه‌حل

  • فقط فیلدهای مورد نیاز را برگردانید
  • داده‌های binary بزرگ را جداگانه handle کنید
  • از delete item.json.largeField برای حذف فیلدهای غیرضروری استفاده کنید
اشتراک‌گذاری:

آیا این مستندات مفید بود؟