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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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