Node.js pathモジュールの使い方｜joinとresolveの違い早見表

pathモジュールは、ファイルやフォルダのパス文字列を組み立てたり分解したりするためのNode.js標準モジュールです。よく使う2つの違いは、path.joinが「渡された部品をつなげて整えるだけ」、path.resolveが「右から順にたどって必ず絶対パスを返す」という点にあります。

この記事では、同じ引数をjoinとresolveの両方に渡した出力を14パターン並べ、Windows形式とmacOS・Linux形式の結果もOS別の表にしました。basename・dirname・extname・parse・format・relative・normalize・sepの入出力早見表と、ESMで __dirname の代わりに使う import.meta.dirname（Node.js 20.11以降）と fileURLToPath の両方を、動かした版の結果つきで載せています。出力はすべてNode.js 22.22.2で実際に実行したものです。

pathモジュールの早見表

この記事の確認環境

path.win32 は、どのOSで動かしてもWindowsと同じ規則で文字列を処理する入口です。cwdを使わない計算（joinやbasenameなど）は実機と同じ結果になります。cwdを使う計算（相対パスのresolve）はcwdの部分だけが実機と異なるため、この記事の表ではその部分を (cwd) と書いています。作業フォルダのパスは /home/taro/app に置き換えています（表示は環境に合わせて置き換えています）。

読み込み方

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

// ESM
import path from 'node:path';

'path' と 'node:path' はどちらも同じモジュールです。node: を付けると、Node.jsの標準モジュールであることがひと目でわかります。

path.joinとpath.resolveの違いを実行結果で比べる

同じ引数を両方に渡した14パターン

次のスクリプトを /home/taro/app をcwdにして実行しました。

const path = require('node:path');

const cases = [
  ['a', 'b', 'c.txt'],
  ['/a', 'b'],
  ['a', '/b'],
  ['/a', '/b', 'c'],
  ['a', '../b'],
  ['a/b', '../../..', 'c'],
  ['a', '', 'b'],
  [''],
  [],
  ['a/', '/b/'],
  ['a', './b', '.'],
  ['/a/b', '../c', './d.txt'],
  ['.', 'a'],
  ['a//b', 'c/..'],
];

for (const c of cases) {
  console.log(JSON.stringify(c), '|', path.join(...c), '|', path.resolve(...c));
}

macOS・Linux形式の実行結果です。

表から読み取れる5つの決まり

• joinは全部つなげてから整える。 途中の引数が / で始まっていても部品として扱います（No.3は a/b、No.4は /a/b/c）
• resolveは右から左へ読み、絶対パスが現れたらそこで止まる。 cd コマンドを順に実行したときの行き先と同じ考え方です（No.3は cd a のあと cd /b をして /b、No.4は /b/c）
• resolveは絶対パスにならなければcwdを前に足す。 No.1・5・7・11・13・14がこれに当たります
• 空の結果は、joinでは .、resolveではcwd。 引数なしの path.resolve() は process.cwd() と同じ値でした
• 末尾の / はjoinでは残り、resolveでは取り除かれる。 No.10がこの違いです

No.2とNo.12のように、先頭の引数が絶対パスで、あとの引数が / で始まらない場合は、両方とも同じ結果になります。path.join(__dirname, 'data', 'a.txt') と path.resolve(__dirname, 'data', 'a.txt') が同じ値になるのはこのためです。

どちらを使うかの判断表

「結果をcwdに左右されたくないときはjoinに絶対パスの基準を渡す、相対でも絶対でも受け取りたいときはresolve」と覚えると選びやすくなります。

WindowsとmacOS・Linuxでの結果の違い

同じ引数のOS別の結果

同じ14パターンを path.win32 でも実行しました。違いが出る主なものを並べます。

Windows形式では、引数に / を書いても結果は \ にそろえられます。 逆にmacOS・Linux形式では \ は区切りではなく普通の文字として扱われます。

ドライブ文字を含むパス（Windows形式）

ここでもjoinとresolveの性格の違いが出ます。別ドライブの絶対パスを渡すと、joinはそのままつなげて C:\app\D:\data という使えないパスになり、resolveは D:\data に切り替えます。 利用者が入力したパスを受け取る処理ではresolveが向いています。

OSによって変わる値の一覧

Windowsで作られたパス文字列をLinuxのサーバーで処理するような場面では、path.basename がパス全体を返します。相手のOSが決まっているときは、path.win32.basename(...) のようにOSを明示した入口を使うと、動かす場所に関係なく同じ結果になります。

OSの違いを吸収する書き方

入出力早見表：分解する・組み立てる・整える

ここからの結果は、すべてmacOS・Linux形式での実行結果です。

basename・dirname・extname

.tar.gz のような二重の拡張子は、extnameでは .gz だけが返ります。 .tar.gz 全体を扱いたいときは、name.endsWith('.tar.gz') のように文字列として判定します。

parseとformat

path.parse はパスを5つの部品に分け、path.format はその逆を行います。

console.log(path.parse('/home/taro/app/src/report.final.tar.gz'));

{
  root: '/',
  dir: '/home/taro/app/src',
  base: 'report.final.tar.gz',
  ext: '.gz',
  name: 'report.final.tar'
}

「dir + 区切り文字 + base」で元のパスに戻り、baseは「name + ext」に分かれる、という2段の関係です。formatの例を並べます。

formatの優先順位は「dirがrootより優先」「baseがname + extより優先」の2つです。parseした結果の拡張子だけを変えたいときは、baseを渡さずにnameとextを渡します（次の「コピペ用の実例」を参照）。

relative・normalize・isAbsolute・sep

path.matchesGlob は比較的新しい関数で、今回は20.20.2で関数として存在すること、22.22.2と24.21.0で上の結果になることを確認しました。18.20.8では typeof path.matchesGlob が undefined だったため、複数の版で動かすコードでは存在を確かめてから使います。

文字列以外を渡したとき

path.join('a', null);

TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received null

pathの関数は文字列だけを受け取ります。 環境変数や設定値が未設定で undefined のまま渡るとこのエラーになるので、渡す前に既定値を入れておくと安定します。

ESMでの__dirnameの置き換え方

CommonJSでは __dirname（そのファイルがあるフォルダ）と __filename（そのファイルのパス）が最初から使えます。ESM（.mjs、または "type": "module" の .js）にはこの2つがないため、次のどちらかで置き換えます。

方法1：import.meta.dirname（Node.js 20.11以降）

// esm.mjs
import path from 'node:path';

console.log('import.meta.dirname  :', import.meta.dirname);
console.log('import.meta.filename :', import.meta.filename);
console.log(path.join(import.meta.dirname, 'data', 'a.txt'));

import.meta.dirname  : /home/taro/app
import.meta.filename : /home/taro/app/esm.mjs
/home/taro/app/data/a.txt

公式ドキュメントでは、追加された版はv20.11.0 / v21.2.0、安定版になったのはv22.16.0 / v24.0.0と記載されています。file: のモジュールでだけ使える点も書かれています。

方法2：fileURLToPath（ESMが使える全版）

// esm.mjs
import path from 'node:path';
import { fileURLToPath } from 'node:url';

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

console.log('import.meta.url :', import.meta.url);
console.log('__filename      :', __filename);
console.log('__dirname       :', __dirname);

import.meta.url : file:///home/taro/app/esm.mjs
__filename      : /home/taro/app/esm.mjs
__dirname       : /home/taro/app

版ごとの結果と選び方

fileURLToPath の列は、18.20.8 / 20.18.3 / 20.20.2 / 22.11.0 / 22.22.2 / 24.21.0で同じ書き方が動くことを確認しています。

URLのpathnameをそのまま使わない

new URL('./x', import.meta.url).pathname でもパスらしい文字列が取れますが、日本語や空白が入ると結果が変わります。

const url = new URL('./デー タ/a.txt', import.meta.url);
console.log('URL.pathname  :', url.pathname);
console.log('fileURLToPath :', fileURLToPath(url));

URL.pathname  : /home/taro/app/%E3%83%87%E3%83%BC%20%E3%82%BF/a.txt
fileURLToPath : /home/taro/app/デー タ/a.txt

pathnameはURLとしてエンコードされた文字列なので、ファイルのパスとして使うときは fileURLToPath を通します。 逆にパスからURLを作るときは pathToFileURL を使います。

import { pathToFileURL } from 'node:url';
console.log(pathToFileURL('/home/taro/app/a b.txt').href);

file:///home/taro/app/a%20b.txt

コピペ用の実例

拡張子を差し替える・ファイル名の末尾に文字を足す

const path = require('node:path');

function replaceExt(file, ext) {
  const { dir, name } = path.parse(file);
  return path.format({ dir, name, ext });
}

function addSuffix(file, suffix) {
  const { dir, name, ext } = path.parse(file);
  return path.format({ dir, name: name + suffix, ext });
}

console.log(replaceExt('/home/taro/app/docs/guide.md', '.html'));
console.log(addSuffix('/home/taro/app/img/photo.png', '@2x'));

/home/taro/app/docs/guide.html
/home/taro/app/img/photo@2x.png

parseの結果からbaseを外し、nameとextを渡すのがポイントです。baseを残したままだと、formatはbaseを優先して元のファイル名を返します。

基準フォルダの外を指していないか確かめる

利用者が入力したファイル名を基準フォルダの下で開くときは、組み立てたあとに「基準フォルダの内側か」を確かめます。

const path = require('node:path');

function resolveInside(baseDir, userPath) {
  const target = path.resolve(baseDir, userPath);
  const rel = path.relative(baseDir, target);
  const inside = rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
  return { target, rel, inside };
}

console.log(resolveInside('/home/taro/app/uploads', 'a/b.png'));
console.log(resolveInside('/home/taro/app/uploads', '../secret.txt'));
console.log(resolveInside('/home/taro/app/uploads', '/etc/hosts'));

{
  target: '/home/taro/app/uploads/a/b.png',
  rel: 'a/b.png',
  inside: true
}
{
  target: '/home/taro/app/secret.txt',
  rel: '../secret.txt',
  inside: false
}
{ target: '/etc/hosts', rel: '../../../../etc/hosts', inside: false }

resolveで絶対パスにしてから、relativeの結果が .. で始まらないことを確かめる流れです。joinだけでは .. を含む入力が基準フォルダの外へ出ることがあるため、入力を受け取る処理ではこの確認を入れておくと安心です。rel !== '' の条件は、基準フォルダそのものを指す入力（空文字や .）を対象外にするためのものです。フォルダ自体を許可したい処理では、この条件を外します。シンボリックリンクまで考える場合は、fs.realpath で実際のパスに直してから比べます（この部分は未実行）。

区切り文字を / にそろえる・PATHを分割する

const toPosix = (p) => p.split(path.win32.sep).join(path.posix.sep);
console.log(toPosix('src\\components\\Button.vue'));

console.log('/usr/local/bin:/usr/bin:/bin'.split(path.delimiter));

src/components/Button.vue
[ '/usr/local/bin', '/usr/bin', '/bin' ]

つまずきやすい箇所と直し方

書く前のチェックリスト

よくある質問

Q. path.joinとpath.resolveはどう使い分けますか？ A. joinは渡した部品をつなげて整えるだけで、cwdを使いません。resolveは右から順にたどって必ず絶対パスを返し、絶対パスにならないときはcwdを前に足します。ファイルの場所を基準に決まった位置を指すなら path.join(__dirname, ...)、利用者から受け取った相対・絶対どちらもありうるパスを扱うなら path.resolve(...) が向いています。

Q. ESMで__dirnameを使うにはどうすればよいですか？ A. Node.js 20.11以降なら import.meta.dirname がそのまま使えます。18系でも動かす場合は、fileURLToPath(import.meta.url) でファイルのパスを取り出し、path.dirname でフォルダ部分にします。今回の実行では、18.20.8で import.meta.dirname は undefined、20.18.3以降ではフォルダのパスが返りました。

Q. Windowsでも同じコードで動きますか？ A. path.join や path.resolve を使っていれば、区切り文字はOSに合わせて自動で切り替わります。違いが出るのは、パスを / で直接分割している箇所や、別のOSで作られたパス文字列を処理する箇所です。前者は path.sep、後者は path.win32 / path.posix を使うとそろえられます。この記事のWindows形式の結果は path.win32 をLinux上で動かしたもので、実機での実行は未実行です。

Q. path.parseとpath.formatはどんなときに使いますか？ A. ファイル名の一部だけを変えたいときに便利です。parseでroot・dir・base・name・extに分け、変えたい部品を差し替えてformatで組み立て直します。拡張子を変えるときは、baseを渡さずnameとextを渡すのがポイントです。

まとめ

• joinは「つなげて整える」、resolveは「右からたどって必ず絶対パスを返す」
• resolveは途中に絶対パスがあると左側を捨てる（resolve('a', '/b') は /b）。joinは部品としてつなげる（a/b）
• cwdに左右されたくないときは path.join(__dirname, ...)、ESMでは import.meta.dirname（20.11以降）
• 18系でも動かすESMは path.dirname(fileURLToPath(import.meta.url))
• extnameは最後のドットから後ろだけ、formatは「dirがrootより優先」「baseがname + extより優先」
• Windows形式では区切りが \ にそろい、別ドライブの絶対パスはresolveが切り替える
• 入力されたパスはresolve + relativeで基準フォルダの内側か確かめる

株式会社RJCでは、Node.jsのパス操作の考え方を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。