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' copy

На Windows:

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

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

На POSIX и Windows:

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

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

На POSIX и Windows:

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

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

path.basename(path[, suffix])

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

Метод 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' copy

Хотя 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' copy

Исключение TypeError выбрасывается, если path не является строкой или если suffix задано и не является строкой.

path.delimiter

• <строка>

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

• ; для 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'] copy

На 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\\'] copy

path.dirname(path)

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

Метод path.dirname() возвращает имя каталога path, аналогично команде Unix dirname. Конечные разделители каталогов игнорируются, см. path.sep.

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

Исключение TypeError выбрасывается, если path не является строкой.

path.extname(path)

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

Метод 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' copy

Исключение TypeError выбрасывается, если path не является строкой.

path.format(pathObject)

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

Метод 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' copy

На Windows:

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

path.isAbsolute(path)

• path <строка>
• Возвращает: <логическое>

Метод path.isAbsolute() определяет, является ли path абсолютным путем.

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

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

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

На 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 copy

Исключение TypeError выбрасывается, если path не является строкой.

path.join([...paths])

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

Метод path.join() соединяет все заданные 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 {}' copy

Исключение TypeError выбрасывается, если какой-либо сегмент пути не является строкой.

path.normalize(path)

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

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

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

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

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

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

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

В Windows:

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

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

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

Если path не является строкой, выбрасывается исключение TypeError.

path.parse(path)

• path <строка>
• Возвращает: <Объект>

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

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

• dir <строка>
• root <строка>
• base <строка>
• name <строка>
• ext <строка>

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

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

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

В Windows:

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

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

Если path не является строкой, выбрасывается исключение TypeError.

path.posix

• <Объект>

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

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

path.relative(from, to)

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

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

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

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

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

В Windows:

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

Если from или to не являются строками, выбрасывается исключение TypeError.

path.resolve([...paths])

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

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

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

Если после обработки всех заданных 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' copy

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

path.sep

• <строка>

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

• \ в Windows
• / в POSIX

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

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

В Windows:

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

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

path.toNamespacedPath(path)

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

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

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

path.win32

• <Объект>

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

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