Node.js로 서버나 유틸성 스크립트를 만들다 보면 디렉토리 내부의 파일 목록을 가져와야 하는 경우가 종종 있습니다. 이미지 처리 파이프라인을 만든다거나, 정적 파일을 자동으로 읽어서 클라이언트에 전달하는 식의 작업이 그렇죠.
이럴 때 많이 사용하는 함수가 바로
fs.readdir 기본 사용법
사용법은 매우 단순하지만, 콜백 기반이기 때문에 기본 구조는 이렇게 생겼습니다:
const fs = require('fs');
fs.readdir('./uploads', (err, files) => {
if (err) {
console.error('에러 발생:', err);
return;
}
console.log('파일 목록:', files);
});위 예제는
파일인지 폴더인지 구분하려면?
const path = require('path');
fs.readdir('./uploads', (err, files) => {
if (err) return;
files.forEach((file) => {
const fullPath = path.join('./uploads', file);
fs.stat(fullPath, (err, stats) => {
if (err) return;
if (stats.isFile()) console.log('파일:', file);
if (stats.isDirectory()) console.log('폴더:', file);
});
});
});Promise 기반으로도 사용 가능할까?
Node.js v10 이후부터는
const fs = require('fs').promises;
const path = require('path');
async function listFiles() {
try {
const files = await fs.readdir('./uploads');
for (const file of files) {
const fullPath = path.join('./uploads', file);
const stat = await fs.stat(fullPath);
if (stat.isFile()) console.log('파일:', file);
if (stat.isDirectory()) console.log('폴더:', file);
}
} catch (err) {
console.error('에러 발생:', err);
}
}
listFiles();사용 시 주의할 점
readdir 은 기본적으로 파일명만 반환하므로, 파일 타입을 구분하려면 별도의 I/O 호출이 필요합니다.- 대량의 파일이 존재하는 경우,
fs.stat 등을 반복 호출하면 I/O 병목이 발생할 수 있습니다. - 에러가 발생하면 반드시 예외 처리를 해줘야 합니다. 콜백이나
try-catch 를 반드시 포함하세요. fs.readdir 은 UTF-8 인코딩을 기본으로 처리하므로, 경로 인코딩 문제가 있다면 옵션 설정이 필요합니다.
마무리 요약
요약하자면:
- 콜백 기반 비동기 디렉토리 읽기 함수
fs.stat 을 조합해 파일/폴더 구분 가능fs.promises.readdir 을 통해async/await 도 지원- 고성능 서버 코드에서는 Sync 함수보다 훨씬 유리함
파일 목록을 다뤄야 하는 모든 Node.js 개발자에게는 꼭 알아야 할 필수 함수 중 하나입니다.