Node.js fs.readFile: Dateien lesen (sync, async, Promises)

fs.readFile(path, 'utf8', callback) liest eine ganze Datei und übergibt ihren Inhalt als String an den Callback. fs.readFileSync(path, 'utf8') gibt den String direkt zurück und wartet, bis das Lesen fertig ist, und await readFile(path, 'utf8') aus fs/promises macht dasselbe, ohne zu blockieren. Lässt du 'utf8' weg, bekommst du statt Text einen Buffer mit den rohen Bytes.

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 erscheint zuerst: readFile startet das Lesen nur, und der Callback läuft, sobald der Inhalt bereit ist. Lösch 'utf8', und führ es noch einmal aus: Der Callback bekommt <Buffer 42 75 79 20 6d 69 6c 6b 0a 43 61 6c 6c 20 41 64 61>, die rohen Bytes der Datei.

readFile vs. readFileSync vs. fs/promises

Alle drei lesen dieselbe Datei. Sie unterscheiden sich darin, wie du das Ergebnis bekommst und ob der Rest des Programms wartet.

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();

Die synchrone Zeile erscheint zuerst, weil nichts anderes läuft, bis sie zurückkehrt. Die anderen beiden werden nach dem Hauptcode fertig, in der Reihenfolge, in der ihre Lesevorgänge abgeschlossen sind.

Nimm readFileSync, wenn du beim Start eine Konfiguration liest oder in einem kurzen Skript. In einem Server hält ein synchrones Lesen jede andere Anfrage an, während die Festplatte arbeitet, nimm dort also die Promise-Variante. Die Seite zu fs/promises behandelt den Rest dieser API.

Eine fehlende Datei behandeln (ENOENT)

Wenn die Datei nicht existiert, hat der Fehler code: 'ENOENT' ("error, no entry"). Prüf err.code, um eine fehlende Datei von anderen Fehlern zu unterscheiden, etwa einem Berechtigungsproblem.

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'));

Der erste Aufruf findet keine Datei und fällt auf default settings zurück; der zweite liest dark mode. Wenn du die anderen Fehler erneut wirfst, bleiben echte Probleme sichtbar, statt dass still Standardwerte genutzt werden.

fs.existsSync: Warum du einfach lesen solltest

fs.existsSync(path) gibt true oder false zurück, und es ist verlockend, vor dem Lesen zu prüfen:

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

Das sind zwei Schritte, wo einer reicht, und die Datei kann zwischen ihnen gelöscht werden, das Lesen kann also trotzdem werfen. Versuch einfach zu lesen und behandle ENOENT wie oben. existsSync ist in Ordnung, wenn du nur wissen musst, ob etwas existiert, und es nicht öffnest, zum Beispiel um zu entscheiden, ob ein Ordner angelegt werden soll.

Eine JSON-Datei lesen

Lies den Text und parse ihn dann mit JSON.parse. Eine Datei mit Syntaxfehler wirft einen SyntaxError, lass das also im selben 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);

Es gibt 3001 und boolean aus: Nach dem Parsen haben die Werte ihre JSON-Typen. require('./config.json') funktioniert auch, cacht aber das Ergebnis, ein zweites require gibt also das alte Objekt zurück, selbst wenn sich die Datei geändert hat.

Eine Datei zeilenweise lesen

Eine Datei, die in den Speicher passt, liest du ganz und teilst sie am Zeilenumbruch. Filter den leeren String heraus, den ein abschließender Zeilenumbruch hinterlässt.

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);
});

Das Split ergibt 4 Elemente, das letzte leer, deshalb gibt die Schleife drei nummerierte Zeilen aus. Unter Windows geschriebene Dateien beenden Zeilen mit \r\n; teil an /\r?\n/, um beides abzudecken.

Ein Log mit mehreren Gigabyte passt nicht in den Speicher. Streame es stattdessen, damit immer nur eine Zeile gehalten wird:

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();

Häufige Fehler

Das Ergebnis außerhalb des Callbacks nutzen. const text = fs.readFile(...) ist undefined. Der Inhalt existiert nur im Callback oder nach await.

Das Encoding vergessen. Ohne 'utf8' bekommst du einen Buffer, und data.split('\n') wirft data.split is not a function. Übergib das Encoding immer, wenn du Text willst.

Pfade relativ zum falschen Ordner. 'data.txt' wird dort gesucht, wo node gestartet wurde. Nimm path.join(__dirname, 'data.txt') für eine Datei, die neben deinem Skript liegt.