fs.readFile no Node.js: ler arquivos (sync, async, promises)

fs.readFile(path, 'utf8', callback) lê um arquivo inteiro e passa o conteúdo para o callback como string. fs.readFileSync(path, 'utf8') retorna a string diretamente e espera a leitura terminar, e await readFile(path, 'utf8') de fs/promises faz o mesmo sem bloquear. Deixe 'utf8' de fora e você recebe um Buffer de bytes crus em vez de texto.

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 imprime primeiro: readFile só inicia a leitura, e o callback roda quando o conteúdo está pronto. Apague 'utf8', e rode de novo: o callback recebe <Buffer 42 75 79 20 6d 69 6c 6b 0a 43 61 6c 6c 20 41 64 61>, os bytes crus do arquivo.

readFile vs readFileSync vs fs/promises

Os três leem o mesmo arquivo. A diferença está em como você recebe o resultado e se o resto do programa espera.

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

A linha síncrona imprime primeiro porque nada mais roda até ela retornar. As outras duas terminam depois do código principal, na ordem em que as leituras completarem.

Use readFileSync para ler uma config na inicialização ou em um script curto. Em um servidor, uma leitura síncrona trava todas as outras requisições enquanto o disco trabalha, então use a versão com promise ali. A página do fs/promises cobre o resto dessa API.

Trate um arquivo que não existe (ENOENT)

Quando o arquivo não existe, o erro tem code: 'ENOENT' ("error, no entry"). Verifique err.code para diferenciar um arquivo ausente de outras falhas, como um problema de permissão.

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

A primeira chamada não encontra arquivo e cai em default settings; a segunda lê dark mode. Relançar os outros erros mantém os problemas reais visíveis, em vez de usar os valores padrão em silêncio.

fs.existsSync: por que é melhor tentar a leitura

fs.existsSync(path) retorna true ou false, e é tentador verificar antes de ler:

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

São dois passos onde um basta, e o arquivo pode ser apagado entre eles, então a leitura ainda pode lançar erro. Tente a leitura e trate ENOENT, como acima. existsSync serve quando você só precisa saber se algo existe e não vai abri-lo, por exemplo para decidir se cria uma pasta.

Ler um arquivo JSON

Leia o texto e depois interprete com JSON.parse. Um arquivo com erro de sintaxe lança SyntaxError, então deixe isso dentro do mesmo 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);

Ele imprime 3001 e boolean: depois do parse, os valores têm seus tipos JSON. require('./config.json') também funciona, mas guarda o resultado em cache, então um segundo require retorna o objeto antigo mesmo depois de o arquivo mudar.

Ler um arquivo linha por linha

Para um arquivo que cabe na memória, leia inteiro e divida no caractere de quebra de linha. Filtre a string vazia que uma quebra de linha final deixa para trás.

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

O split dá 4 itens, o último vazio, então o loop imprime três linhas numeradas. Arquivos escritos no Windows terminam as linhas com \r\n; divida com /\r?\n/ para tratar os dois.

Um log de vários gigabytes não cabe na memória. Use stream, assim só uma linha por vez fica guardada:

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

Erros comuns

Usar o resultado fora do callback. const text = fs.readFile(...) é undefined. O conteúdo só existe dentro do callback, ou depois do await.

Esquecer o encoding. Sem 'utf8' você recebe um Buffer, e data.split('\n') lança data.split is not a function. Passe o encoding sempre que quiser texto.

Caminhos relativos à pasta errada. 'data.txt' é procurado onde o node foi iniciado. Use path.join(__dirname, 'data.txt') para um arquivo que fica ao lado do seu script.