كتابة الملفات في Node.js: fs.writeFile وappendFile

تكتب fs.writeFile(path, data, callback) نصًا أو Buffer في ملف. إذا لم يكن الملف موجودًا ينشئه Node؛ وإذا كان موجودًا يُستبدل محتواه القديم. وتفعل fs.writeFileSync(path, data) الشيء نفسه وتنتظر حتى تنتهي الكتابة، أما fs.appendFile فتضيف إلى نهاية الملف بدلًا من استبداله.

const fs = require('fs');

fs.writeFile('hello.txt', 'Hello, file', (err) => {
    if (err) {
        console.error('Write failed:', err.message);
        return;
    }
    console.log('saved');
    console.log(fs.readFileSync('hello.txt', 'utf8'));
});

يطبع saved ثم النص الذي قرأه من جديد؛ ولا يستقبل الـ callback إلا خطأ (أو null)، لا البيانات أبدًا. مرّر 42 بدلًا من النص فيرمي الاستدعاء TypeError: يجب أن تكون البيانات نصًا أو Buffer.

writeFile وwriteFileSync وfs/promises

تأخذ الصيغ الثلاث الوسائط نفسها، وتختلف في طريقة انتظار النتيجة.

const fs = require('fs');
const fsp = require('fs/promises');

fs.writeFileSync('a.txt', 'one');            // blocks, throws on error

fs.writeFile('b.txt', 'two', (err) => {});   // callback with err

await fsp.writeFile('c.txt', 'three');       // promise, use in async code

استخدم writeFileSync في السكربتات وشيفرة بدء التشغيل، ونسخة الوعد في الخوادم، حيث تحجب الكتابة المتزامنة كل الطلبات الأخرى حتى ينتهي القرص. تعرض صفحة fs/promises بقية واجهة الوعود.

الإضافة إلى ملف عبر appendFile

تستبدل writeFile الملف كله. لإضافة سطر إلى سجل، استخدم appendFile، التي تنشئ الملف أيضًا في المرة الأولى.

const fs = require('fs');

fs.writeFileSync('log.txt', 'first\n');
fs.writeFileSync('log.txt', 'second\n');
console.log(JSON.stringify(fs.readFileSync('log.txt', 'utf8')));

fs.appendFileSync('log.txt', 'third\n');
fs.appendFileSync('log.txt', 'fourth\n');
console.log(JSON.stringify(fs.readFileSync('log.txt', 'utf8')));

تطبع القراءة الأولى "second\n"، لأن writeFileSync الثانية استبدلت first، وتطبع الثانية "second\nthird\nfourth\n" (يجعل JSON.stringify الأسطر الجديدة ظاهرة). أضف \n بنفسك: لا تضيفه أي من الدالتين.

لا تكتب فوق الملف: الخيار flag

يمكن أن يكون الوسيط الثالث كائن خيارات. خاصيته flag تحدد ما يحدث لملف موجود. القيمة 'wx' تعني "اكتب، لكن افشل إن كان الملف موجودًا"، وهي الطريقة الآمنة لإنشاء ملف مرة واحدة فقط.

const fs = require('fs');

function createOnce(file, text) {
    try {
        fs.writeFileSync(file, text, { flag: 'wx' });
        console.log('created', file);
    } catch (err) {
        if (err.code === 'EEXIST') {
            console.log(file, 'already exists, left alone');
        } else {
            throw err;
        }
    }
}

createOnce('id.txt', 'abc123');
createOnce('id.txt', 'zzz999');
console.log(fs.readFileSync('id.txt', 'utf8'));

يفشل الاستدعاء الثاني بـ EEXIST، فيبقى الملف حاويًا abc123. غيّر اسم الملف في الاستدعاء الثاني إلى id2.txt فيطبع الاستدعاءان created.

الخيارات التي ستصادفها أكثر: 'w' (الافتراضي، استبدال)، و'a' (إضافة)، و'wx' (إنشاء فقط)، و'ax' (إضافة، لكن إلى ملف جديد فقط).

التحقق بـ fs.existsSync أولًا ثم الكتابة يترك ثغرة: قد تنشئ عملية أخرى الملف بين الفحص والكتابة. أما 'wx' فتنجز الأمرين في خطوة واحدة.

كتابة JSON في ملف

لا تقبل writeFile الكائنات. حوّلها إلى نص بـ JSON.stringify؛ والوسيط الثالث، 2، يضيف مسافات بادئة للناتج ليكون الملف مقروءًا.

const fs = require('fs');

const settings = { theme: 'dark', fontSize: 14, plugins: ['git', 'lint'] };

fs.writeFileSync('settings.json', JSON.stringify(settings, null, 2));

console.log(fs.readFileSync('settings.json', 'utf8'));

const loaded = JSON.parse(fs.readFileSync('settings.json', 'utf8'));
console.log(loaded.plugins.length);

يحمل الملف الكائن على عدة أسطر بمسافات بادئة، وتحليله من جديد يعطي كائنًا مساويًا، فيطبع السطر الأخير 2. مرّر الكائن دون JSON.stringify فيرمي الاستدعاء TypeError.

أنشئ المجلد أولًا عبر mkdir

تنشئ writeFile الملفات لا المجلدات. الكتابة إلى reports/2026/june.txt حين لا يكون reports موجودًا تفشل بـ ENOENT. أنشئ المسار أولًا بـ mkdir مع { recursive: true }، التي تنشئ كل مجلد ناقص ولا تفعل شيئًا إن كانت المجلدات موجودة.

const fs = require('fs/promises');

async function main() {
    try {
        await fs.writeFile('reports/2026/june.txt', 'sales: 12');
    } catch (err) {
        console.log('first try:', err.code);
    }

    await fs.mkdir('reports/2026', { recursive: true });
    await fs.writeFile('reports/2026/june.txt', 'sales: 12');

    console.log(await fs.readdir('reports/2026'));
}
main();

تفشل الكتابة الأولى بـ ENOENT؛ وبعد mkdir تنجح الكتابة نفسها وتسرد readdir القيمة [ 'june.txt' ]. ابنِ هذه المسارات بـ path.join في الشيفرة الحقيقية لتعمل على Windows أيضًا.

أخطاء شائعة

افتراض أن الملف كُتب مباشرة بعد الاستدعاء. تعود fs.writeFile قبل أن تصل البيانات إلى القرص. اقرأ الملف أو ابدأ الخطوة التالية داخل الـ callback، أو انتظر نسخة الوعد بـ await.

فقدان البيانات بالكتابة داخل حلقة. استدعاء writeFile مرة لكل عنصر يستبدل الملف في كل مرة، فلا يبقى إلا العنصر الأخير. استخدم appendFile، أو ابنِ النص كاملًا واكتبه مرة واحدة.

كتابة [object Object]. تمرير كائن عبر String() أو قالب نصي يكتب [object Object]. استخدم JSON.stringify.