fs.readFile w Node.js: odczyt plików (sync, async, promise)

fs.readFile(path, 'utf8', callback) czyta cały plik i przekazuje jego zawartość do callbacku jako string. fs.readFileSync(path, 'utf8') zwraca string bezpośrednio i czeka na koniec odczytu, a await readFile(path, 'utf8') z fs/promises robi to samo bez blokowania. Jeśli pominiesz 'utf8', zamiast tekstu dostaniesz Buffer z surowymi bajtami.

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

Najpierw wypisuje się readFile called: readFile tylko rozpoczyna odczyt, a callback wykonuje się, gdy zawartość jest gotowa. Usuń 'utf8', i uruchom ponownie: callback dostaje <Buffer 42 75 79 20 6d 69 6c 6b 0a 43 61 6c 6c 20 41 64 61>, czyli surowe bajty pliku.

readFile vs readFileSync vs fs/promises

Wszystkie trzy czytają ten sam plik. Różnią się tym, jak dostajesz wynik i czy reszta programu czeka.

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

Linia synchroniczna wypisuje się pierwsza, bo nic innego się nie wykonuje, dopóki ona nie wróci. Pozostałe dwie kończą się po głównym kodzie, w kolejności, w jakiej zakończą się ich odczyty.

Używaj readFileSync przy odczycie konfiguracji na starcie albo w krótkim skrypcie. Na serwerze odczyt synchroniczny zatrzymuje każde inne żądanie, dopóki dysk pracuje, więc tam użyj wersji z promise. Strona o fs/promises opisuje resztę tego API.

Obsługa brakującego pliku (ENOENT)

Gdy plik nie istnieje, błąd ma code: 'ENOENT' ("error, no entry"). Sprawdzaj err.code, żeby odróżnić brak pliku od innych błędów, np. problemu z uprawnieniami.

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

Pierwsze wywołanie nie znajduje pliku i wraca do default settings; drugie odczytuje dark mode. Ponowne rzucanie pozostałych błędów sprawia, że prawdziwe problemy są widoczne, zamiast po cichu używać wartości domyślnych.

fs.existsSync: dlaczego lepiej po prostu czytać

fs.existsSync(path) zwraca true albo false i kusi, żeby sprawdzać przed odczytem:

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

To dwa kroki tam, gdzie wystarczy jeden, a plik może zostać usunięty między nimi, więc odczyt i tak może rzucić wyjątek. Po prostu czytaj i obsługuj ENOENT, jak wyżej. existsSync jest w porządku, gdy chcesz tylko wiedzieć, czy coś istnieje, i nie będziesz tego otwierać, np. żeby zdecydować, czy utworzyć folder.

Odczyt pliku JSON

Odczytaj tekst, a potem sparsuj go przez JSON.parse. Plik z błędem składni rzuca SyntaxError, więc trzymaj to w tym samym 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);

Wypisuje 3001 i boolean: po sparsowaniu wartości mają swoje typy z JSON. require('./config.json') też działa, ale cache'uje wynik, więc drugie require zwraca stary obiekt, nawet gdy plik się zmienił.

Czytanie pliku linia po linii

Plik, który mieści się w pamięci, odczytaj w całości i podziel po znaku nowej linii. Odfiltruj pusty string, który zostaje po końcowym znaku nowej linii.

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

Podział daje 4 elementy, ostatni pusty, więc pętla wypisuje trzy ponumerowane linie. Pliki zapisane w Windows kończą linie przez \r\n; dziel po /\r?\n/, żeby obsłużyć oba przypadki.

Log o rozmiarze kilku gigabajtów nie zmieści się w pamięci. Zamiast tego czytaj go strumieniem, żeby w pamięci była tylko jedna linia naraz:

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

Częste błędy

Używanie wyniku poza callbackiem. const text = fs.readFile(...) to undefined. Zawartość istnieje tylko w callbacku albo po await.

Zapominanie o kodowaniu. Bez 'utf8' dostajesz Buffer, a data.split('\n') rzuca data.split is not a function. Przekazuj kodowanie zawsze, gdy chcesz tekst.

Ścieżki względem złego folderu. 'data.txt' jest szukany tam, gdzie uruchomiono node. Użyj path.join(__dirname, 'data.txt') dla pliku, który leży obok twojego skryptu.