Node.js의 파일 시스템 모듈(fs module)

1. fs 모듈이란

fs(File System) 모듈은 Node.js에서 파일과 디렉토리를 다루기 위한 내장 모듈입니다. 파일 읽기, 쓰기, 삭제, 디렉토리 생성 등의 작업을 수행할 수 있으며, 동기/비동기/프로미스 세 가지 방식의 API를 제공합니다.

2. fs 모듈 불러오기

// CommonJS
const fs = require('fs');
const fsPromises = require('fs').promises;
// 또는
const { readFile, writeFile } = require('fs/promises');

// ES Modules
import fs from 'node:fs';
import { readFile, writeFile } from 'node:fs/promises';

3. 파일 읽기

3.1 비동기 방식 (콜백)

const fs = require('fs');

fs.readFile('example.txt', 'utf8', (err, data) => {
  if (err) {
    console.error('파일 읽기 실패:', err.message);
    return;
  }
  console.log('파일 내용:', data);
});

3.2 동기 방식

const fs = require('fs');

try {
  const data = fs.readFileSync('example.txt', 'utf8');
  console.log('파일 내용:', data);
} catch (err) {
  console.error('파일 읽기 실패:', err.message);
}

3.3 프로미스 방식

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

async function readFileAsync() {
  try {
    const data = await fs.readFile('example.txt', 'utf8');
    console.log('파일 내용:', data);
  } catch (err) {
    console.error('파일 읽기 실패:', err.message);
  }
}

readFileAsync();

4. 파일 쓰기

4.1 새 파일 작성 (덮어쓰기)

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

async function writeToFile() {
  const content = '안녕하세요, Node.js!';

  await fs.writeFile('output.txt', content, 'utf8');
  console.log('파일 작성 완료');
}

4.2 파일에 내용 추가

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

async function appendToFile() {
  const content = '\n추가된 내용';

  await fs.appendFile('output.txt', content, 'utf8');
  console.log('내용 추가 완료');
}

4.3 JSON 파일 읽기/쓰기

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

// JSON 읽기
async function readJSON(filePath) {
  const data = await fs.readFile(filePath, 'utf8');
  return JSON.parse(data);
}

// JSON 쓰기
async function writeJSON(filePath, data) {
  const jsonString = JSON.stringify(data, null, 2);
  await fs.writeFile(filePath, jsonString, 'utf8');
}

// 사용
async function main() {
  const config = await readJSON('config.json');
  config.version = '2.0.0';
  await writeJSON('config.json', config);
}

반응형

5. 파일/디렉토리 정보 확인

5.1 파일 존재 여부 확인

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

async function checkFileExists(filePath) {
  try {
    await fs.access(filePath);
    return true;
  } catch {
    return false;
  }
}

// 사용
const exists = await checkFileExists('example.txt');
console.log('파일 존재:', exists);

5.2 파일/디렉토리 정보 (stat)

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

async function getFileInfo(filePath) {
  const stats = await fs.stat(filePath);

  console.log('파일 크기:', stats.size, 'bytes');
  console.log('생성일:', stats.birthtime);
  console.log('수정일:', stats.mtime);
  console.log('디렉토리인가:', stats.isDirectory());
  console.log('파일인가:', stats.isFile());
}

6. 디렉토리 작업

6.1 디렉토리 생성

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

// 단일 디렉토리 생성
await fs.mkdir('newFolder');

// 중첩 디렉토리 생성 (recursive 옵션)
await fs.mkdir('path/to/nested/folder', { recursive: true });

6.2 디렉토리 내용 읽기

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

async function listDirectory(dirPath) {
  // 기본 - 파일명 배열 반환
  const files = await fs.readdir(dirPath);
  console.log(files); // ['file1.txt', 'file2.txt', 'folder1']

  // withFileTypes 옵션 - Dirent 객체 배열 반환
  const entries = await fs.readdir(dirPath, { withFileTypes: true });

  for (const entry of entries) {
    const type = entry.isDirectory() ? '📁' : '📄';
    console.log(`${type} ${entry.name}`);
  }
}

6.3 디렉토리 삭제

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

// 빈 디렉토리 삭제
await fs.rmdir('emptyFolder');

// 내용이 있는 디렉토리 삭제 (recursive 옵션)
await fs.rm('folderWithContents', { recursive: true });

7. 파일 삭제 및 이름 변경

7.1 파일 삭제

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

await fs.unlink('fileToDelete.txt');
// 또는
await fs.rm('fileToDelete.txt');

7.2 파일/디렉토리 이름 변경

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

// 이름 변경
await fs.rename('oldName.txt', 'newName.txt');

// 파일 이동
await fs.rename('file.txt', 'folder/file.txt');

7.3 파일 복사

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

await fs.copyFile('source.txt', 'destination.txt');

8. 스트림을 이용한 대용량 파일 처리

대용량 파일은 스트림을 사용하여 메모리 효율적으로 처리합니다.

8.1 읽기 스트림

const fs = require('fs');

const readStream = fs.createReadStream('largefile.txt', {
  encoding: 'utf8',
  highWaterMark: 64 * 1024 // 64KB 청크
});

readStream.on('data', (chunk) => {
  console.log('청크 크기:', chunk.length);
});

readStream.on('end', () => {
  console.log('파일 읽기 완료');
});

readStream.on('error', (err) => {
  console.error('에러:', err.message);
});

8.2 쓰기 스트림

const fs = require('fs');

const writeStream = fs.createWriteStream('output.txt');

writeStream.write('첫 번째 줄\n');
writeStream.write('두 번째 줄\n');
writeStream.end('마지막 줄');

writeStream.on('finish', () => {
  console.log('파일 쓰기 완료');
});

8.3 파이프로 파일 복사

const fs = require('fs');

const readStream = fs.createReadStream('source.txt');
const writeStream = fs.createWriteStream('destination.txt');

readStream.pipe(writeStream);

writeStream.on('finish', () => {
  console.log('파일 복사 완료');
});

9. 파일 감시 (watch)

const fs = require('fs');

// 파일 변경 감시
fs.watch('watched.txt', (eventType, filename) => {
  console.log(`이벤트: ${eventType}, 파일: ${filename}`);
});

// 디렉토리 감시 (recursive 옵션)
fs.watch('watchedFolder', { recursive: true }, (eventType, filename) => {
  console.log(`이벤트: ${eventType}, 파일: ${filename}`);
});

결론

Node.js의 fs 모듈은 파일과 디렉토리를 다루는 다양한 API를 제공합니다. 프로미스 기반의 fs/promises를 사용하면 async/await로 깔끔하게 코드를 작성할 수 있습니다. 대용량 파일은 스트림을 사용하여 메모리 효율적으로 처리하고, 동기 방식은 서버 시작 시 설정 파일 로드 등 특수한 경우에만 사용하는 것이 좋습니다.