Путь

[Стабильно: 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 <строка>
suffix <строка> Необязательный суффикс для удаления
Возвращает: <строка>

Метод path.basename() возвращает последнюю часть пути, аналогично команде 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'

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

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

Если path не является строкой, генерируется исключение TypeError.

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

Если path не является строкой, генерируется исключение TypeError.

`path.format(pathObject)`

[История]

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

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

Метод 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)`

Добавлен в: v22.5.0, v20.17.0

[Стабильность: 1 - Экспериментальный]

Стабильность: 1 Стабильность: 1 - Экспериментальный

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

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

`path.isAbsolute(path)`

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

path <string>
Возвращает: <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

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

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

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

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

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

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

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

path.join('foo', {}, 'bar')
// Выбрасывает '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 предоставляет доступ к реализациям методов path, специфичным для POSIX.

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 предоставляет доступ к реализациям методов path, специфичным для Windows.

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

Путь ​

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 ​

Путь

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`