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

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

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

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

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

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

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

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

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

В Windows:

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

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 copy

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

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

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

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

Если какой-либо сегмент пути не является строкой, возникает ошибка 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' 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 <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' } 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

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

В Windows:

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

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

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

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

path.sep

• <string>

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

• \ в 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 <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').