fs.writeFile()

كتابة ملف بشكل غير متزامن fs.writeFile()

fs.writeFile() تكتب بيانات لملف بشكل غير متزامن — تنشئ الملف إن لم يكن موجودًا، وتستبدل محتواه بالكامل إن كان موجودًا.

fs.writeFile() تأخذ مسار الملف والبيانات (نص أو Buffer) وتكتبها دفعة واحدة، ثم تستدعي callback واحد بمعامل خطأ فقط: (err). الترميز الافتراضي 'utf8' خلافًا لـ readFile الذي يرجّع Buffer افتراضيًا.

السلوك الافتراضي هو الاستبدال الكامل (flag: 'w') — أي أن الملف الموجود يُفرَّغ ويُكتب من جديد، وليس إضافة (append) للمحتوى القديم. للإضافة يجب تحديد flag: 'a' صراحة.

الصياغة

fs.writeFile(file, data[, options], callback)

📄 مثال

const fs = require('node:fs');

fs.writeFile('log.txt', 'بدأ التشغيل\n', (err) => {
  if (err) {
    console.error('فشلت الكتابة:', err.message);
    return;
  }
  console.log('تمت الكتابة بنجاح');
});

// إضافة سطر بدل الاستبدال:
fs.writeFile('log.txt', 'سطر إضافي\n', { flag: 'a' }, (err) => {
  if (err) throw err;
});

أهم المعاملات

المعامل	الوظيفة
file	مسار الملف المراد الكتابة إليه
data	المحتوى — نص أو Buffer أو كائن قابل للتحويل
options.flag	افتراضيًا 'w' (استبدال كامل) — استخدم 'a' للإضافة
callback(err)	يُستدعى بعد اكتمال الكتابة أو فشلها، بمعامل خطأ واحد فقط

💡 نصائح عملية

افتراضيًا الترميز 'utf8' — عكس readFile الذي يرجّع Buffer إن لم تحدّد الترميز
لتحديثات متكررة على نفس الملف (سجلات، logs) فكّر بـ fs.createWriteStream بدل استدعاء writeFile مرارًا

⚠️ أخطاء شائعة

الاعتقاد أن writeFile تضيف (append) للملف تلقائيًا — هي تستبدل المحتوى بالكامل ما لم تحدد flag: 'a'
تجاهل معامل الخطأ بالـ callback يجعل فشل الكتابة (نقص صلاحيات، قرص ممتلئ) يمر دون أي تنبيه

خصائص ذات صلة

fs.readFile() قراءة ملف بشكل غير متزامن

🎓 تريد فهم الصورة الكاملة خطوة بخطوة؟ ابدأ من مسار NODEJS الكامل بالعربي.