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