path（ファイルパス操作）

// CommonJS方式
var path = require('path');

// ES Modules方式
import path from 'path';

複数のパス部品をOSの区切り文字で結合します。引数の末尾スラッシュは自動的に処理されます。

var path = require('path');

// OS に合った区切り文字で結合される
console.log(path.join('/home', 'itadori', 'docs', 'report.txt'));
// macOS/Linux: /home/itadori/docs/report.txt

// '..' も処理される
console.log(path.join('/home/itadori', '../fushiguro', 'notes.txt'));
// /home/fushiguro/notes.txt

// './' は除去される
console.log(path.join('./src', './utils', 'helper.js'));
// src/utils/helper.js

node path_join.js
/home/itadori/docs/report.txt
/home/fushiguro/notes.txt
src/utils/helper.js

右から左に引数を処理し、絶対パスになった時点で処理を停止します。絶対パスが見つからない場合はカレントディレクトリを基点にします。

var path = require('path');

// カレントディレクトリを起点に絶対パスを生成する
console.log(path.resolve('src', 'index.js'));
// /Users/gojo/project/src/index.js （カレントディレクトリによって異なる）

// 絶対パスが途中にあればそこから再起動する
console.log(path.resolve('/var/www', 'html', 'index.html'));
// /var/www/html/index.html

// __dirname と組み合わせるのが典型的な使い方
console.log(path.resolve(__dirname, 'assets', 'logo.png'));
// /Users/gojo/project/assets/logo.png

node path_resolve.js
/Users/gojo/project/src/index.js
/var/www/html/index.html
/Users/gojo/project/assets/logo.png

var path = require('path');

var filePath = '/home/sukuna/documents/curses.txt';

// ファイル名（拡張子含む）
console.log(path.basename(filePath));
// curses.txt

// 拡張子なしのファイル名
console.log(path.basename(filePath, '.txt'));
// curses

// ディレクトリ部分
console.log(path.dirname(filePath));
// /home/sukuna/documents

// 拡張子（ドット含む）
console.log(path.extname(filePath));
// .txt

node path_parts.js
curses.txt
curses
/home/sukuna/documents
.txt

path.parse() はパスを構成要素に分解します。path.format() は逆に、オブジェクトからパス文字列を組み立てます。

var path = require('path');

var parsed = path.parse('/home/kugisaki/images/photo.jpg');
console.log(parsed);
/*
{
  root: '/',
  dir: '/home/kugisaki/images',
  base: 'photo.jpg',
  ext: '.jpg',
  name: 'photo'
}
*/

// name の部分を変更してパスを組み立てる
parsed.name = 'thumbnail';
parsed.base = parsed.name + parsed.ext;  // base の更新も必要
console.log(path.format(parsed));
// /home/kugisaki/images/thumbnail.jpg

node path_parse.js
{ root: '/', dir: '/home/kugisaki/images', base: 'photo.jpg', ext: '.jpg', name: 'photo' }
/home/kugisaki/images/thumbnail.jpg

CommonJS環境では __dirname（現在のファイルのディレクトリ）と __filename（現在のファイルの絶対パス）が自動的に定義されています。

var path = require('path');

// 同じディレクトリにある config.json へのパスを作る
var configPath = path.join(__dirname, 'config.json');
console.log("設定ファイル: " + configPath);

// 一つ上のディレクトリの assets フォルダ
var assetsDir = path.resolve(__dirname, '..', 'assets');
console.log("アセット: " + assetsDir);

node dirname_sample.js
設定ファイル: /Users/itadori/project/config.json
アセット: /Users/itadori/assets

ES Modules（.mjs / type: "module"）では __dirname と __filename は使えません。import.meta.url を使って同等の値を得ます。

// ES Modules での代替方法
import { fileURLToPath } from 'url';
import path from 'path';

var __filename = fileURLToPath(import.meta.url);
var __dirname  = path.dirname(__filename);

以下はpathモジュールを使ってファイルのパス情報を分析するサンプルです。

path_analyzer.js

// path_analyzer.js — 複数ファイルパスのパス情報を一覧表示する
var path = require('path');

// 呪術高専メンバーのファイル一覧（仮想）
var files = [
    '/home/gojo/unlimited/infinity.js',
    '/home/itadori/yuji/black_flash.ts',
    '/home/fushiguro/megumi/ten_shadows.json',
    '/home/kugisaki/nobara/straw_doll.txt',
    '/home/sukuna/curses/malevolent_shrine.php'
];

files.forEach(function(filePath) {
    var parsed = path.parse(filePath);
    console.log("ファイル: " + parsed.base);
    console.log("  ディレクトリ : " + parsed.dir);
    console.log("  拡張子       : " + parsed.ext);
    console.log("  区切り文字   : " + path.sep);
    console.log("  絶対パス?    : " + path.isAbsolute(filePath));
    console.log("");
});

node path_analyzer.js
ファイル: infinity.js
  ディレクトリ : /home/gojo/unlimited
  拡張子       : .js
  区切り文字   : /
  絶対パス?    : true

ファイル: black_flash.ts
  ディレクトリ : /home/itadori/yuji
  拡張子       : .ts
  区切り文字   : /
  絶対パス?    : true

ファイル: ten_shadows.json
  ディレクトリ : /home/fushiguro/megumi
  拡張子       : .json
  区切り文字   : /
  絶対パス?    : true

ファイル: straw_doll.txt
  ディレクトリ : /home/kugisaki/nobara
  拡張子       : .txt
  区切り文字   : /
  絶対パス?    : true

ファイル: malevolent_shrine.php
  ディレクトリ : /home/sukuna/curses
  拡張子       : .php
  区切り文字   : /
  絶対パス?    : true

パスの区切り文字はOSによって異なります。path.sep を使うとOSに合った区切り文字を取得できます。

path.join() と path.resolve() は内部で path.sep を自動的に使うため、パスの連結には文字列の + や / のハードコードではなくこれらのメソッドを使うのが基本です。

よくあるミス1: path.join と path.resolve の違いを理解せず間違った方を使う

path.join() は引数のパス文字列を順番に連結するだけです。path.resolve() は右から左に処理し、絶対パスのセグメントに出会った時点でそこを起点として処理を止めます。

var path = require('path');

// path.join は単純に連結する
console.log(path.join('/foo', '/bar'));
// /foo/bar  （/bar の先頭スラッシュは区切り文字として扱われる）

// path.resolve は絶対パスを新しいルートとして扱う
console.log(path.resolve('/foo', '/bar'));
// /bar  （/bar が絶対パスなので /foo は無視される）

実行結果:

node join_vs_resolve.js
/foo/bar
/bar

パスのセグメントを結合するだけなら path.join()、特定のベースディレクトリからの絶対パスを組み立てるなら path.resolve(__dirname, ...) というのが典型的な使い分けです。

よくあるミス2: Windows で '/' をハードコードしてパスが壊れる

パスの区切り文字を文字列で直接書くと、Windows（区切り文字は \）でパスが壊れます。

NG（区切り文字をハードコードする）:

var dir = '/home/itadori/project';
var filename = 'black_flash.txt';

// Windows では壊れる
var filePath = dir + '/' + filename;
console.log(filePath);

OK（path.join() を使う）:

var path = require('path');

var dir = '/home/itadori/project';
var filename = 'black_flash.txt';

// OS に合った区切り文字が自動的に使われる
var filePath = path.join(dir, filename);
console.log(filePath);
// macOS/Linux: /home/itadori/project/black_flash.txt
// Windows:     \home\itadori\project\black_flash.txt

path.sep で現在のOSの区切り文字を確認できます。macOS/Linux では /、Windows では \ が返ります。