fs.readFile في Node.js: قراءة الملفات بكل الطرق

تقرأ fs.readFile(path, 'utf8', callback) ملفًا كاملًا وتمرر محتواه إلى دالة callback كنص. وتعيد fs.readFileSync(path, 'utf8') النص مباشرة بعد أن تنتظر انتهاء القراءة، بينما تفعل await readFile(path, 'utf8') من fs/promises الشيء نفسه دون حجب. إذا حذفت 'utf8' تحصل على Buffer من البايتات الخام بدلًا من النص.

const fs = require('fs');

// Setup: create a file to read
fs.writeFileSync('notes.txt', 'Buy milk\nCall Ada');

fs.readFile('notes.txt', 'utf8', (err, text) => {
    if (err) {
        console.error('Could not read:', err.message);
        return;
    }
    console.log(text);
});

console.log('readFile called');

يُطبع readFile called أولًا: readFile تبدأ القراءة فقط، والـ callback يعمل حين يجهز المحتوى. احذف 'utf8', وشغّل من جديد: يستقبل الـ callback القيمة <Buffer 42 75 79 20 6d 69 6c 6b 0a 43 61 6c 6c 20 41 64 61>، وهي البايتات الخام للملف.

readFile مقابل readFileSync مقابل fs/promises

الثلاثة تقرأ الملف نفسه. الفرق في طريقة حصولك على النتيجة، وفي ما إذا كان بقية البرنامج ينتظر.

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

// Setup: create a file to read
fs.writeFileSync('greeting.txt', 'Hello from a file');

// 1. Sync: returns the text, blocks until done
const a = fs.readFileSync('greeting.txt', 'utf8');
console.log('sync:', a);

// 2. Callback: the result arrives later
fs.readFile('greeting.txt', 'utf8', (err, b) => {
    console.log('callback:', b);
});

// 3. Promise: await it inside an async function
async function main() {
    const c = await fsp.readFile('greeting.txt', 'utf8');
    console.log('promise:', c);
}
main();

يُطبع السطر المتزامن أولًا لأن لا شيء آخر يعمل حتى يعود. ينتهي الآخران بعد الشيفرة الرئيسية، بحسب الترتيب الذي تكتمل به قراءتهما.

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

التعامل مع ملف غير موجود (ENOENT)

حين لا يكون الملف موجودًا، يحمل الخطأ code: 'ENOENT' ("error, no entry"). افحص err.code لتميّز الملف الغائب عن الأخطاء الأخرى، مثل مشكلة في الصلاحيات.

const fs = require('fs');

function readSettings(file) {
    try {
        return fs.readFileSync(file, 'utf8');
    } catch (err) {
        if (err.code === 'ENOENT') {
            return 'default settings';
        }
        throw err; // anything else is a real problem
    }
}

console.log(readSettings('settings.txt'));

// Setup: now create the file and read again
fs.writeFileSync('settings.txt', 'dark mode');
console.log(readSettings('settings.txt'));

لا يجد الاستدعاء الأول الملف فيرجع إلى default settings؛ ويقرأ الثاني dark mode. إعادة رمي الأخطاء الأخرى تُبقي المشاكل الحقيقية ظاهرة بدلًا من استخدام القيم الافتراضية بصمت.

fs.existsSync: لماذا تكفي محاولة القراءة

تعيد fs.existsSync(path) القيمة true أو false، ومن المغري أن تتحقق قبل القراءة:

if (fs.existsSync('data.txt')) {
    const text = fs.readFileSync('data.txt', 'utf8');
}

هاتان خطوتان حيث تكفي واحدة، وقد يُحذف الملف بينهما فترمي القراءة خطأ رغم ذلك. جرّب القراءة وتعامل مع ENOENT، كما في المثال السابق. تناسب existsSync الحالات التي تحتاج فيها فقط إلى معرفة وجود شيء ولن تفتحه، مثل أن تقرر هل تنشئ مجلدًا.

قراءة ملف JSON

اقرأ النص، ثم حلّله بـ JSON.parse. الملف الذي فيه خطأ في الصياغة يرمي SyntaxError، فأبقِه داخل try نفسها.

const fs = require('fs');

// Setup: write a JSON file
fs.writeFileSync('config.json', '{ "port": 3000, "debug": true }');

const config = JSON.parse(fs.readFileSync('config.json', 'utf8'));
console.log(config.port + 1);
console.log(typeof config.debug);

يطبع 3001 وboolean: بعد التحليل تأخذ القيم أنواعها في JSON. تعمل require('./config.json') أيضًا، لكنها تخزّن النتيجة، فيعيد require الثاني الكائن القديم حتى بعد تغيّر الملف.

قراءة ملف سطرًا سطرًا

للملف الذي يتسع في الذاكرة، اقرأه كاملًا وقسّمه عند محرف السطر الجديد. وصفِّ النص الفارغ الذي يتركه السطر الجديد الأخير.

const fs = require('fs');

// Setup: write a file with three lines
fs.writeFileSync('log.txt', 'start\nwarn: disk 91%\nstop\n');

const lines = fs.readFileSync('log.txt', 'utf8').split('\n');
console.log(lines.length);

lines.filter(Boolean).forEach((line, i) => {
    console.log(i + 1, line);
});

يعطي التقسيم 4 عناصر، آخرها فارغ، فتطبع الحلقة ثلاثة أسطر مرقّمة. الملفات المكتوبة على Windows تنهي أسطرها بـ \r\n؛ قسّم على /\r?\n/ لتتعامل مع الحالتين.

سجل بحجم عدة غيغابايتات لا يتسع في الذاكرة. اقرأه كتدفق (stream) بدلًا من ذلك، فلا يُحفظ إلا سطر واحد في كل مرة:

const fs = require('fs');
const readline = require('readline');

async function main() {
    const rl = readline.createInterface({
        input: fs.createReadStream('big.log'),
        crlfDelay: Infinity,
    });
    for await (const line of rl) {
        console.log(line);
    }
}
main();

أخطاء شائعة

استخدام النتيجة خارج الـ callback. const text = fs.readFile(...) قيمته undefined. لا يوجد المحتوى إلا داخل الـ callback، أو بعد await.

نسيان الترميز. دون 'utf8' تحصل على Buffer، فترمي data.split('\n') الخطأ data.split is not a function. مرّر الترميز كلما أردت نصًا.

مسارات نسبية إلى المجلد الخطأ. يُبحث عن 'data.txt' حيث شُغّل node. استخدم path.join(__dirname, 'data.txt') لملف يأتي بجوار سكربتك.