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

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

• <строка>

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

• ; для 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 <строка>
• Возвращает: <строка>

Метод 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 <строка>
• Возвращает: <строка>

Метод 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 <объект> Любой JavaScript-объект, имеющий следующие свойства:
  • dir <строка>
  • root <строка>
  • base <строка>
  • name <строка>
  • ext <строка>
• Возвращает: <строка>

Метод 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.isAbsolute(path)

• path <строка>
• Возвращает: <булево>

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

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

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

path.isAbsolute('/foo/bar'); // 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 <строка> Последовательность сегментов пути
• Возвращает: <строка>

Метод path.join() объединяет все заданные 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 <строка>
• Возвращает: <строка>

Метод 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 <строка>
• Возвращает: <Объект>

Метод path.parse() возвращает объект, свойства которого представляют значимые элементы path. Конечные разделители каталога игнорируются, см. path.sep.

Возвращаемый объект будет иметь следующие свойства:

• dir <строка>
• root <строка>
• base <строка>
• name <строка>
• ext <строка>

Например, в 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

• <Объект>

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

Доступ к API возможен через require('node:path').posix или require('node:path/posix').

path.relative(from, to)

• from <строка>
• to <строка>
• Возвращает: <строка>

Метод 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 <строка> Последовательность путей или сегментов пути
• Возвращает: <строка>

Метод path.resolve() разрешает последовательность путей или сегментов пути в абсолютный путь.

Указанная последовательность путей обрабатывается справа налево, каждый последующий path добавляется в начало до тех пор, пока не будет построен абсолютный путь. Например, для последовательности сегментов пути: /foo, /bar, baz, вызов path.resolve('/foo', '/bar', 'baz') вернёт /bar/baz, потому что 'baz' не является абсолютным путём, а '/bar' + '/' + 'baz' - является.

Если после обработки всех заданных 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

• <строка>

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

• \ в 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 <строка>
• Возвращает: <строка>

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

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

path.win32

• <Объект>

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

Доступ к API возможен через require('node:path').win32 или require('node:path/win32').