Path

Модуль node:path предоставляет утилиты для работы с путями к файлам и каталогам. Доступ к нему можно получить с помощью:

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

import path from 'node:path';

Windows и POSIX

Поведение модуля node:path по умолчанию зависит от операционной системы, в которой выполняется приложение Node.js. В частности, при запуске в операционной системе Windows модуль node:path предполагает, что используются пути в стиле Windows.

Поэтому вызов path.basename() может давать разные результаты в POSIX и Windows:

В POSIX:

path.basename('C:\\temp\\myfile.html');
// Returns: 'C:\\temp\\myfile.html'
jscopy

В Windows:

path.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'
jscopy

Чтобы получать согласованные результаты при работе с путями Windows в любой операционной системе, используйте path.win32:

В POSIX и Windows:

path.win32.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'
jscopy

Чтобы получать согласованные результаты при работе с путями POSIX в любой операционной системе, используйте path.posix:

В POSIX и Windows:

path.posix.basename('/tmp/myfile.html');
// Returns: 'myfile.html'
jscopy

В Windows Node.js следует концепции рабочего каталога для каждого диска. Это поведение можно наблюдать при использовании пути к диску без обратной косой черты. Например, path.resolve('C:\\') может вернуть результат, отличающийся от результата path.resolve('C:'). Дополнительные сведения см. на этой странице MSDN.

path.basename(path[, suffix])

• path <string>
• suffix <string> Необязательный суффикс для удаления
• Возвращает: <string>

Метод path.basename() возвращает последнюю часть path, подобно команде Unix basename. Завершающие разделители каталогов игнорируются.

path.basename('/foo/bar/baz/asdf/quux.html');
// Returns: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// Returns: 'quux'
jscopy

Хотя Windows обычно обрабатывает имена файлов, включая расширения, без учёта регистра, эта функция не делает этого. Например, C:\\foo.html и C:\\foo.HTML указывают на один и тот же файл, но basename обрабатывает расширение как строку с учётом регистра:

path.win32.basename('C:\\foo.html', '.html');
// Returns: 'foo'

path.win32.basename('C:\\foo.HTML', '.html');
// Returns: 'foo.HTML'
jscopy

Возникает TypeError, если path не является строкой или если задано suffix, не являющееся строкой.

path.delimiter

• Тип: <string>

Предоставляет разделитель путей, специфичный для платформы:

• ; в Windows
• : в POSIX

Например, в POSIX:

console.log(process.env.PATH);
// Prints: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'

process.env.PATH.split(path.delimiter);
// Returns: ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
jscopy

В Windows:

console.log(process.env.PATH);
// Prints: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'

process.env.PATH.split(path.delimiter);
// Returns ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']
jscopy

path.dirname(path)

• path <string>
• Возвращает: <string>

Метод path.dirname() возвращает имя каталога из path, подобно команде Unix dirname. Завершающие разделители каталогов игнорируются; см. path.sep.

path.dirname('/foo/bar/baz/asdf/quux');
// Returns: '/foo/bar/baz/asdf'
jscopy

Возникает TypeError, если path не является строкой.

path.extname(path)

• path <string>
• Возвращает: <string>

Метод path.extname() возвращает расширение path — от последнего вхождения символа . (точки) до конца строки в последней части path. Если в последней части path нет . или если в ней нет символов ., кроме первого символа базового имени path (см. path.basename()), возвращается пустая строка.

path.extname('index.html');
// Returns: '.html'

path.extname('index.coffee.md');
// Returns: '.md'

path.extname('index.');
// Returns: '.'

path.extname('index');
// Returns: ''

path.extname('.index');
// Returns: ''

path.extname('.index.md');
// Returns: '.md'
jscopy

Возникает TypeError, если path не является строкой.

path.format(pathObject)

• pathObject <Object> Любой объект JavaScript со следующими свойствами:
  • dir <string>
  • root <string>
  • base <string>
  • name <string>
  • ext <string>
• Возвращает: <string>

Метод path.format() возвращает строку пути на основе объекта. Это противоположность методу path.parse().

При передаче свойств в pathObject учитывайте, что существуют комбинации, в которых одно свойство имеет приоритет над другим:

• pathObject.root игнорируется, если задано pathObject.dir
• pathObject.ext и pathObject.name игнорируются, если задано pathObject.base

Например, в POSIX:

// If `dir`, `root` and `base` are provided,
// `${dir}${path.sep}${base}`
// will be returned. `root` is ignored.
path.format({
  root: '/ignored',
  dir: '/home/user/dir',
  base: 'file.txt',
});
// Returns: '/home/user/dir/file.txt'

// `root` will be used if `dir` is not specified.
// If only `root` is provided or `dir` is equal to `root` then the
// platform separator will not be included. `ext` will be ignored.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignored',
});
// Returns: '/file.txt'

// `name` + `ext` will be used if `base` is not specified.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt',
});
// Returns: '/file.txt'

// The dot will be added if it is not specified in `ext`.
path.format({
  root: '/',
  name: 'file',
  ext: 'txt',
});
// Returns: '/file.txt'
jscopy

В Windows:

path.format({
  dir: 'C:\\path\\dir',
  base: 'file.txt',
});
// Returns: 'C:\\path\\dir\\file.txt'
jscopy

path.matchesGlob(path, pattern)

• path <string> Путь, который будет проверен на соответствие glob-шаблону.
• pattern <string> Glob-шаблон для проверки пути.
• Возвращает: <boolean> Соответствует ли path шаблону pattern.

Метод path.matchesGlob() определяет, соответствует ли path шаблону pattern.

Например:

path.matchesGlob('/foo/bar', '/foo/*'); // true
path.matchesGlob('/foo/bar*', 'foo/bird'); // false
jscopy

Возникает TypeError, если path или pattern не являются строками.

path.isAbsolute(path)

• path <string>
• Возвращает: <boolean>

Метод path.isAbsolute() определяет, является ли буквальный путь path абсолютным. Поэтому он не подходит для защиты от обхода путей.

Если заданный path представляет собой строку нулевой длины, будет возвращено false.

Например, в POSIX:

path.isAbsolute('/foo/bar');   // true
path.isAbsolute('/baz/..');    // true
path.isAbsolute('/baz/../..'); // true
path.isAbsolute('qux/');       // false
path.isAbsolute('.');          // false
jscopy

В Windows:

path.isAbsolute('//server');    // true
path.isAbsolute('\\\\server');  // true
path.isAbsolute('C:/foo/..');   // true
path.isAbsolute('C:\\foo\\..'); // true
path.isAbsolute('bar\\baz');    // false
path.isAbsolute('bar/baz');     // false
path.isAbsolute('.');           // false
jscopy

Возникает TypeError, если path не является строкой.

path.join([...paths])

• ...paths <string> Последовательность сегментов пути
• Возвращает: <string>

Метод path.join() объединяет все заданные сегменты path, используя разделитель, специфичный для платформы, а затем нормализует полученный путь.

Сегменты path нулевой длины игнорируются. Если объединённая строка пути имеет нулевую длину, будет возвращено '.', обозначающее текущий рабочий каталог.

path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
// Returns: '/foo/bar/baz/asdf'

path.join('foo', {}, 'bar');
// Throws 'TypeError: Path must be a string. Received {}'
jscopy

Возникает TypeError, если какой-либо сегмент пути не является строкой.

path.normalize(path)

• path <string>
• Возвращает: <string>

Метод path.normalize() нормализует заданный path, обрабатывая сегменты '..' и '.'.

Если обнаруживаются несколько последовательных символов-разделителей сегментов пути (например, / в POSIX и \ или / в Windows), они заменяются одним разделителем сегментов пути, специфичным для платформы (/ в POSIX и \ в Windows). Завершающие разделители сохраняются.

Если path представляет собой строку нулевой длины, возвращается '.', обозначающее текущий рабочий каталог.

В POSIX нормализация, выполняемая этой функцией, не полностью соответствует спецификации POSIX. Например, функция заменяет две начальные косые черты одной, как если бы это был обычный абсолютный путь, хотя некоторые системы POSIX придают особое значение путям, начинающимся ровно с двух косых черт. Аналогично, другие преобразования, выполняемые этой функцией, например удаление сегментов .., могут изменить способ обработки пути базовой системой.

Например, в POSIX:

path.normalize('/foo/bar//baz/asdf/quux/..');
// Returns: '/foo/bar/baz/asdf'
jscopy

В Windows:

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// Returns: 'C:\\temp\\foo\\'
jscopy

Поскольку Windows распознаёт несколько разделителей путей, оба разделителя заменяются предпочтительным разделителем Windows (\):

path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// Returns: 'C:\\temp\\foo\\bar'
jscopy

Возникает TypeError, если path не является строкой.

path.parse(path)

• path <string>
• Возвращает: <Object>

Метод path.parse() возвращает объект, свойства которого представляют значимые элементы path. Завершающие разделители каталогов игнорируются; см. path.sep.

Возвращаемый объект будет иметь следующие свойства:

• dir <string>
• root <string>
• base <string>
• name <string>
• ext <string>

Например, в POSIX:

path.parse('/home/user/dir/file.txt');
// Returns:
// { root: '/',
//   dir: '/home/user/dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }
jscopy

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)
textcopy

В Windows:

path.parse('C:\\path\\dir\\file.txt');
// Returns:
// { root: 'C:\\',
//   dir: 'C:\\path\\dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }
jscopy

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)
textcopy

Возникает TypeError, если path не является строкой.

path.posix

• Тип: <Object>

Свойство path.posix предоставляет доступ к реализациям методов path, специфичным для POSIX.

Доступ к API можно получить через require('node:path').posix или require('node:path/posix').

path.relative(from, to)

• from <string>
• to <string>
• Возвращает: <string>

Метод path.relative() возвращает относительный путь от from до to относительно текущего рабочего каталога. Если from и to разрешаются в один и тот же путь (после вызова path.resolve() для каждого из них), возвращается строка нулевой длины.

Если в качестве from или to передана строка нулевой длины, вместо неё будет использован текущий рабочий каталог.

Например, в POSIX:

path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb');
// Returns: '../../impl/bbb'
jscopy

В Windows:

path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb');
// Returns: '..\\..\\impl\\bbb'
jscopy

Возникает TypeError, если from или to не является строкой.

path.resolve([...paths])

• ...paths <string> Последовательность путей или сегментов пути
• Возвращает: <string>

Метод path.resolve() преобразует последовательность путей или сегментов пути в абсолютный путь.

Заданная последовательность путей обрабатывается справа налево; каждый следующий path добавляется в начало, пока не будет построен абсолютный путь. Например, для последовательности сегментов пути /foo, /bar, baz вызов path.resolve('/foo', '/bar', 'baz') вернёт /bar/baz, поскольку 'baz' не является абсолютным путём, а '/bar' + '/' + 'baz' является.

Если после обработки всех заданных сегментов path абсолютный путь всё ещё не построен, используется текущий рабочий каталог.

Полученный путь нормализуется, а завершающие косые черты удаляются, если путь не разрешается в корневой каталог.

Сегменты path нулевой длины игнорируются.

Если сегменты path не переданы, path.resolve() вернёт абсолютный путь текущего рабочего каталога.

path.resolve('/foo/bar', './baz');
// Returns: '/foo/bar/baz'

path.resolve('/foo/bar', '/tmp/file/');
// Returns: '/tmp/file'

path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
// If the current working directory is /home/myself/node,
// this returns '/home/myself/node/wwwroot/static_files/gif/image.gif'
jscopy

Возникает TypeError, если какой-либо аргумент не является строкой.

path.sep

• Тип: <string>

Предоставляет разделитель сегментов пути, специфичный для платформы:

• \ в Windows
• / в POSIX

Например, в POSIX:

'foo/bar/baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']
jscopy

В Windows:

'foo\\bar\\baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']
jscopy

В Windows в качестве разделителей сегментов пути принимаются как прямая косая черта (/), так и обратная косая черта (\); однако методы path добавляют только обратные косые черты (\).

path.toNamespacedPath(path)

• path <string>
• Возвращает: <string>

Только в системах Windows возвращает эквивалентный путь с префиксом пространства имён для заданного path. Если path не является строкой, path возвращается без изменений.

Этот метод имеет смысл только в системах Windows. В системах POSIX он не выполняет никаких действий и всегда возвращает path без изменений.

path.win32

• Тип: <Object>

Свойство path.win32 предоставляет доступ к реализациям методов path, специфичным для Windows.

Доступ к API можно получить через require('node:path').win32 или require('node:path/win32').