Path

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/path.js

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

CJSESM

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');
// Возвращает: 'C:\\temp\\myfile.html'

В Windows:

path.basename('C:\\temp\\myfile.html');
// Возвращает: 'myfile.html'

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

В POSIX и Windows:

path.win32.basename('C:\\temp\\myfile.html');
// Возвращает: 'myfile.html'

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

В POSIX и Windows:

path.posix.basename('/tmp/myfile.html');
// Возвращает: 'myfile.html'

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

`path.basename(path[, suffix])`

[История]

Версия	Изменения
v6.0.0	Передача не-строки в качестве аргумента `path` теперь будет вызывать ошибку.
v0.1.25	Добавлено в: v0.1.25

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

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

path.basename('/foo/bar/baz/asdf/quux.html');
// Возвращает: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// Возвращает: 'quux'

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

path.win32.basename('C:\\foo.html', '.html');
// Возвращает: 'foo'

path.win32.basename('C:\\foo.HTML', '.html');
// Возвращает: 'foo.HTML'

Ошибка TypeError возникает, если path не является строкой или если suffix задан и не является строкой.

`path.delimiter`

Добавлено в версии: v0.9.3

<string>

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

; для Windows
: для POSIX

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

console.log(process.env.PATH);
// Выводит: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'

process.env.PATH.split(path.delimiter);
// Возвращает: ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']

В Windows:

console.log(process.env.PATH);
// Выводит: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'

process.env.PATH.split(path.delimiter);
// Возвращает ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']

`path.dirname(path)`

[История]

Версия	Изменения
v6.0.0	Передача нестрокового значения в качестве аргумента `path` теперь вызовет ошибку.
v0.1.16	Добавлено в версии: v0.1.16

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

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

path.dirname('/foo/bar/baz/asdf/quux');
// Возвращает: '/foo/bar/baz/asdf'

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

`path.extname(path)`

[История]

Версия	Изменения
v6.0.0	Передача нестрокового значения в качестве аргумента `path` теперь вызовет ошибку.
v0.1.25	Добавлено в версии: v0.1.25

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

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

path.extname('index.html');
// Возвращает: '.html'

path.extname('index.coffee.md');
// Возвращает: '.md'

path.extname('index.');
// Возвращает: '.'

path.extname('index');
// Возвращает: ''

path.extname('.index');
// Возвращает: ''

path.extname('.index.md');
// Возвращает: '.md'

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

`path.format(pathObject)`

[История]

Версия	Изменения
v19.0.0	Точка будет добавлена, если она не указана в `ext`.
v0.11.15	Добавлено в: v0.11.15

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:

// Если предоставлены `dir`, `root` и `base`,
// будет возвращено `${dir}${path.sep}${base}`. `root` игнорируется.
path.format({
  root: '/ignored',
  dir: '/home/user/dir',
  base: 'file.txt',
});
// Возвращает: '/home/user/dir/file.txt'

// `root` будет использоваться, если `dir` не указан.
// Если указан только `root` или `dir` равен `root`, то
// разделитель платформы не будет включен. `ext` будет игнорироваться.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignored',
});
// Возвращает: '/file.txt'

// `name` + `ext` будут использоваться, если `base` не указан.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt',
});
// Возвращает: '/file.txt'

// Точка будет добавлена, если она не указана в `ext`.
path.format({
  root: '/',
  name: 'file',
  ext: 'txt',
});
// Возвращает: '/file.txt'

В Windows:

path.format({
  dir: 'C:\\path\\dir',
  base: 'file.txt',
});
// Возвращает: 'C:\\path\\dir\\file.txt'

`path.matchesGlob(path, pattern)`

Added in: v22.5.0, v20.17.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Экспериментальный

path <string> Путь для сопоставления с шаблоном glob.
pattern <string> Шаблон glob для проверки пути.
Returns: <boolean> Указывает, соответствует ли path pattern.

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

Например:

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

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

`path.isAbsolute(path)`

Added in: v0.11.2

path <string>
Returns: <boolean>

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

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

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

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

В 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

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

`path.join([...paths])`

Added in: v0.1.16

...paths <string> Последовательность сегментов пути
Returns: <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 {}'

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

`path.normalize(path)`

Добавлено в: v0.1.23

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

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

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

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

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

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

path.normalize('/foo/bar//baz/asdf/quux/..');
// Возвращает: '/foo/bar/baz/asdf'

В Windows:

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// Возвращает: 'C:\\temp\\foo\\'

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

path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// Возвращает: 'C:\\temp\\foo\\bar'

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

`path.parse(path)`

Добавлено в: v0.11.15

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');
// Возвращает:
// { root: '/',
//   dir: '/home/user/dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

text

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
(Все пробелы в строке "" следует игнорировать. Они предназначены исключительно для форматирования.)

В Windows:

path.parse('C:\\path\\dir\\file.txt');
// Возвращает:
// { root: 'C:\\',
//   dir: 'C:\\path\\dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

text

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
(Все пробелы в строке "" следует игнорировать. Они предназначены исключительно для форматирования.)

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

`path.posix`

[История]

Версия	Изменения
v15.3.0	Доступно как `require('path/posix')`.
v0.11.15	Добавлено в: v0.11.15

<Object>

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

API доступен через require('node:path').posix или require('node:path/posix').

`path.relative(from, to)`

[История]

Версия	Изменения
v6.8.0	В Windows, начальные слеши для UNC-путей теперь включены в возвращаемое значение.
v0.5.0	Добавлено в: v0.5.0

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');
// Возвращает: '../../impl/bbb'

В Windows:

path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb');
// Возвращает: '..\\..\\impl\\bbb'

Ошибка TypeError возникает, если from или to не являются строками.

`path.resolve([...paths])`

Добавлено в: v0.3.4

...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');
// Возвращает: '/foo/bar/baz'

path.resolve('/foo/bar', '/tmp/file/');
// Возвращает: '/tmp/file'

path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
// Если текущий рабочий каталог /home/myself/node,
// это вернет '/home/myself/node/wwwroot/static_files/gif/image.gif'

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

`path.sep`

Добавлено в: v0.7.9

<string>

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

\ в Windows
/ в POSIX

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

'foo/bar/baz'.split(path.sep);
// Вернет: ['foo', 'bar', 'baz']

В Windows:

'foo\\bar\\baz'.split(path.sep);
// Вернет: ['foo', 'bar', 'baz']

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

`path.toNamespacedPath(path)`

Добавлено в: v9.0.0

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

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

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

`path.win32`

[История]

Версия	Изменения
v15.3.0	Предоставляется как `require('path/win32')`.
v0.11.15	Добавлено в: v0.11.15

<Object>

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

API доступен через require('node:path').win32 или require('node:path/win32').

Path ​

Windows против POSIX ​

path.basename(path[, suffix]) ​

path.delimiter ​

path.dirname(path) ​

path.extname(path) ​

path.format(pathObject) ​

path.matchesGlob(path, pattern) ​

path.isAbsolute(path) ​

path.join([...paths]) ​

path.normalize(path) ​

path.parse(path) ​

path.posix ​

path.relative(from, to) ​

path.resolve([...paths]) ​

path.sep ​

path.toNamespacedPath(path) ​

path.win32 ​

Path

Windows против POSIX

`path.basename(path[, suffix])`

`path.delimiter`

`path.dirname(path)`

`path.extname(path)`

`path.format(pathObject)`

`path.matchesGlob(path, pattern)`

`path.isAbsolute(path)`

`path.join([...paths])`

`path.normalize(path)`

`path.parse(path)`

`path.posix`

`path.relative(from, to)`

`path.resolve([...paths])`

`path.sep`

`path.toNamespacedPath(path)`

`path.win32`