Node.js의 경로 모듈(path module)

1. path 모듈이란

path 모듈은 파일과 디렉토리 경로를 다루기 위한 Node.js 내장 모듈입니다. 운영체제마다 경로 구분자가 다른데(Windows는 , POSIX는 /), path 모듈을 사용하면 운영체제에 관계없이 일관된 방식으로 경로를 처리할 수 있습니다.

2. path 모듈 불러오기

// CommonJS
const path = require('path');

// ES Modules
import path from 'node:path';

3. 경로 정보 추출

3.1 path.basename()

경로에서 파일명을 추출합니다.

const path = require('path');

console.log(path.basename('/home/user/file.txt'));
// file.txt

console.log(path.basename('/home/user/file.txt', '.txt'));
// file (확장자 제외)

console.log(path.basename('/home/user/'));
// user

3.2 path.dirname()

경로에서 디렉토리 경로를 추출합니다.

const path = require('path');

console.log(path.dirname('/home/user/file.txt'));
// /home/user

console.log(path.dirname('/home/user/docs/'));
// /home/user

3.3 path.extname()

파일 확장자를 추출합니다.

const path = require('path');

console.log(path.extname('file.txt'));       // .txt
console.log(path.extname('file.config.js')); // .js
console.log(path.extname('file'));           // '' (빈 문자열)
console.log(path.extname('.gitignore'));     // '' (빈 문자열)

3.4 path.parse()

경로를 구성 요소로 분해합니다.

const path = require('path');

const parsed = path.parse('/home/user/docs/file.txt');
console.log(parsed);
/*
{
  root: '/',
  dir: '/home/user/docs',
  base: 'file.txt',
  ext: '.txt',
  name: 'file'
}
*/

// Windows 경로
const parsedWin = path.parse('C:\\Users\\user\\file.txt');
console.log(parsedWin);
/*
{
  root: 'C:\\',
  dir: 'C:\\Users\\user',
  base: 'file.txt',
  ext: '.txt',
  name: 'file'
}
*/

4. 경로 생성 및 조합

4.1 path.join()

여러 경로 세그먼트를 하나의 경로로 결합합니다. 자동으로 구분자를 처리하고 정규화합니다.

const path = require('path');

console.log(path.join('/home', 'user', 'docs', 'file.txt'));
// /home/user/docs/file.txt

console.log(path.join('/home', 'user', '..', 'docs'));
// /home/docs (..은 상위 디렉토리로 이동)

console.log(path.join('folder', 'subfolder', 'file.txt'));
// folder/subfolder/file.txt

// 빈 문자열이나 현재 디렉토리 처리
console.log(path.join('/home', '', 'user'));
// /home/user

4.2 path.resolve()

절대 경로를 생성합니다. 오른쪽에서 왼쪽으로 경로를 처리하며, 절대 경로가 만들어지면 멈춥니다.

const path = require('path');

// 현재 작업 디렉토리 기준 절대 경로 생성
console.log(path.resolve('file.txt'));
// /현재/작업/디렉토리/file.txt

console.log(path.resolve('/home', 'user', 'file.txt'));
// /home/user/file.txt

console.log(path.resolve('/home', '/user', 'file.txt'));
// /user/file.txt (중간에 절대 경로가 있으면 그 이전은 무시)

// __dirname과 함께 사용
console.log(path.resolve(__dirname, 'config', 'settings.json'));
// /현재/파일/위치/config/settings.json

4.3 path.format()

parse()의 반대로, 객체를 경로 문자열로 변환합니다.

const path = require('path');

const pathString = path.format({
  dir: '/home/user',
  base: 'file.txt'
});
console.log(pathString);  // /home/user/file.txt

const pathString2 = path.format({
  root: '/',
  name: 'file',
  ext: '.txt'
});
console.log(pathString2);  // /file.txt

반응형

5. 경로 변환

5.1 path.normalize()

경로를 정규화합니다. 불필요한 . 이나 .., 중복 구분자를 처리합니다.

const path = require('path');

console.log(path.normalize('/home//user/../docs/./file.txt'));
// /home/docs/file.txt

console.log(path.normalize('folder/subfolder/../file.txt'));
// folder/file.txt

5.2 path.relative()

한 경로에서 다른 경로로의 상대 경로를 계산합니다.

const path = require('path');

console.log(path.relative('/home/user/docs', '/home/user/images'));
// ../images

console.log(path.relative('/home/user', '/home/user/docs/file.txt'));
// docs/file.txt

console.log(path.relative('/home/user/docs', '/home/user/docs'));
// '' (빈 문자열 - 같은 경로)

5.3 path.isAbsolute()

경로가 절대 경로인지 확인합니다.

const path = require('path');

// POSIX
console.log(path.isAbsolute('/home/user'));  // true
console.log(path.isAbsolute('./file.txt'));  // false
console.log(path.isAbsolute('file.txt'));    // false

// Windows
console.log(path.isAbsolute('C:\\Users'));   // true
console.log(path.isAbsolute('\\Users'));     // true

6. 플랫폼별 처리

6.1 path.sep

운영체제의 경로 구분자입니다.

const path = require('path');

console.log(path.sep);
// POSIX: /
// Windows: \

// 경로를 배열로 분리
const filePath = '/home/user/docs/file.txt';
const segments = filePath.split(path.sep);
console.log(segments);  // ['', 'home', 'user', 'docs', 'file.txt']

6.2 path.delimiter

환경 변수 PATH의 구분자입니다.

const path = require('path');

console.log(path.delimiter);
// POSIX: :
// Windows: ;

// PATH 환경 변수 분리
console.log(process.env.PATH.split(path.delimiter));

6.3 플랫폼별 명시적 사용

const path = require('path');

// POSIX 스타일 강제
console.log(path.posix.join('home', 'user'));  // home/user

// Windows 스타일 강제
console.log(path.win32.join('home', 'user'));  // home\user

7. 실전 활용 예시

7.1 __dirname, __filename 활용

const path = require('path');

// 현재 파일의 절대 경로
console.log(__filename);
// /home/user/project/app.js

// 현재 파일의 디렉토리 경로
console.log(__dirname);
// /home/user/project

// 상대 경로로 파일 찾기
const configPath = path.join(__dirname, 'config', 'settings.json');
const publicPath = path.resolve(__dirname, '..', 'public');

7.2 파일 확장자에 따른 처리

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

async function processFiles(directory) {
  const files = await fs.readdir(directory);

  for (const file of files) {
    const ext = path.extname(file).toLowerCase();
    const filePath = path.join(directory, file);

    switch (ext) {
      case '.json':
        console.log('JSON 파일:', file);
        break;
      case '.js':
        console.log('JavaScript 파일:', file);
        break;
      case '.md':
        console.log('Markdown 파일:', file);
        break;
    }
  }
}

7.3 안전한 파일 경로 생성

const path = require('path');

function getSafeFilePath(baseDir, userInput) {
  // 사용자 입력에서 경로 조작 방지
  const fileName = path.basename(userInput);
  const safePath = path.join(baseDir, fileName);

  // 결과 경로가 baseDir 내에 있는지 확인
  const resolvedPath = path.resolve(safePath);
  const resolvedBase = path.resolve(baseDir);

  if (!resolvedPath.startsWith(resolvedBase)) {
    throw new Error('잘못된 파일 경로');
  }

  return resolvedPath;
}

// 사용
const safePath = getSafeFilePath('/uploads', '../../../etc/passwd');
// /uploads/passwd (경로 조작 방지됨)

결론

Node.js의 path 모듈은 파일 경로를 안전하고 일관되게 다루기 위한 필수 도구입니다. path.join()과 path.resolve()로 경로를 조합하고, path.parse()로 경로 정보를 추출할 수 있습니다. 운영체제에 따른 경로 구분자 차이를 자동으로 처리하므로, 크로스 플랫폼 애플리케이션 개발에 필수적입니다.