Node.js v26.0.0 Dokumentation

Path#

Das node:path-Modul stellt Hilfsmittel für die Arbeit mit Datei- und Verzeichnispfaden bereit. Es kann wie folgt aufgerufen werden:

const path = require('node:path');
import path from 'node:path';
copy

Windows vs. POSIX#

Die Standardfunktionsweise des node:path-Moduls variiert je nach Betriebssystem, auf dem die Node.js-Anwendung ausgeführt wird. Insbesondere wenn das Modul auf einem Windows-Betriebssystem läuft, geht es davon aus, dass Pfade im Windows-Stil verwendet werden.

Daher kann die Verwendung von path.basename() auf POSIX und Windows unterschiedliche Ergebnisse liefern:

Unter POSIX

path.basename('C:\\temp\\myfile.html');
// Returns: 'C:\\temp\\myfile.html'
copy

Unter Windows

path.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'
copy

Um konsistente Ergebnisse bei der Arbeit mit Windows-Dateipfaden auf jedem Betriebssystem zu erzielen, verwenden Sie path.win32

Unter POSIX und Windows

path.win32.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'
copy

Um konsistente Ergebnisse bei der Arbeit mit POSIX-Dateipfaden auf jedem Betriebssystem zu erzielen, verwenden Sie path.posix

Unter POSIX und Windows

path.posix.basename('/tmp/myfile.html');
// Returns: 'myfile.html'
copy

Unter Windows folgt Node.js dem Konzept des laufwerksspezifischen Arbeitsverzeichnisses. Dieses Verhalten kann beobachtet werden, wenn ein Laufwerkspfad ohne Backslash verwendet wird. Zum Beispiel kann path.resolve('C:\\') potenziell ein anderes Ergebnis liefern als path.resolve('C:'). Weitere Informationen finden Sie auf dieser MSDN-Seite.

path.basename(path[, suffix])#

• path <string>
• suffix <string> Ein optionales Suffix, das entfernt werden soll
• Rückgabe: <string>

Die path.basename()-Methode gibt den letzten Teil eines path zurück, ähnlich dem Unix-Befehl basename. Nachgestellte Verzeichnistrennzeichen werden ignoriert.

path.basename('/foo/bar/baz/asdf/quux.html');
// Returns: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// Returns: 'quux'
copy

Obwohl Windows Dateinamen, einschließlich Dateierweiterungen, normalerweise nicht zwischen Groß- und Kleinschreibung unterscheidet, tut dies diese Funktion nicht. Zum Beispiel beziehen sich C:\\foo.html und C:\\foo.HTML auf dieselbe Datei, aber basename behandelt die Erweiterung als einen String, bei dem die Groß-/Kleinschreibung beachtet wird.

path.win32.basename('C:\\foo.html', '.html');
// Returns: 'foo'

path.win32.basename('C:\\foo.HTML', '.html');
// Returns: 'foo.HTML'
copy

Ein TypeError wird ausgelöst, wenn path kein String ist oder wenn ein suffix angegeben wurde, das kein String ist.

path.delimiter#

• Typ: <string>

Stellt das plattformspezifische Pfadtrennzeichen bereit:

• ; für Windows
• : für POSIX

Zum Beispiel unter 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

Unter 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>
• Rückgabe: <string>

Die path.dirname()-Methode gibt den Verzeichnisnamen eines path zurück, ähnlich dem Unix-Befehl dirname. Nachgestellte Verzeichnistrennzeichen werden ignoriert, siehe path.sep.

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

Ein TypeError wird ausgelöst, wenn path kein String ist.

path.extname(path)#

• path <string>
• Rückgabe: <string>

Die path.extname()-Methode gibt die Erweiterung des path zurück, vom letzten Vorkommen des . (Punkt)-Zeichens bis zum Ende des Strings im letzten Teil des path. Wenn kein . im letzten Teil des path vorhanden ist oder wenn es keine .-Zeichen gibt, außer dem ersten Zeichen des Basisnamens des path (siehe path.basename()), wird ein leerer String zurückgegeben.

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

Ein TypeError wird ausgelöst, wenn path kein String ist.

path.format(pathObject)#

• pathObject <Object> Jedes JavaScript-Objekt mit den folgenden Eigenschaften:
  • dir <string>
  • root <string>
  • base <string>
  • name <string>
  • ext <string>
• Rückgabe: <string>

Die path.format()-Methode gibt einen Pfad-String aus einem Objekt zurück. Dies ist das Gegenstück zu path.parse().

Beim Bereitstellen von Eigenschaften für das pathObject beachten Sie, dass es Kombinationen gibt, bei denen eine Eigenschaft Vorrang vor einer anderen hat:

• pathObject.root wird ignoriert, wenn pathObject.dir angegeben ist.
• pathObject.ext und pathObject.name werden ignoriert, wenn pathObject.base existiert.

Zum Beispiel unter 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

Unter Windows

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

path.matchesGlob(path, pattern)#

• path <string> Der Pfad für den Glob-Abgleich.
• pattern <string> Der Glob-Ausdruck, gegen den der Pfad geprüft werden soll.
• Rückgabe: <boolean> Ob der path dem pattern entspricht.

Die path.matchesGlob()-Methode bestimmt, ob path dem pattern entspricht.

Zum Beispiel

path.matchesGlob('/foo/bar', '/foo/*'); // true
path.matchesGlob('/foo/bar*', 'foo/bird'); // false
copy

Ein TypeError wird ausgelöst, wenn path oder pattern keine Strings sind.

path.isAbsolute(path)#

• path <string>
• Rückgabewert: <boolean>

Die path.isAbsolute()-Methode bestimmt, ob der literale path absolut ist. Daher ist sie nicht sicher zur Abwehr von Pfad-Traversierung (Path Traversal).

Wenn der angegebene path ein String der Länge Null ist, wird false zurückgegeben.

Zum Beispiel unter POSIX:

path.isAbsolute('/foo/bar');   // true
path.isAbsolute('/baz/..');    // true
path.isAbsolute('/baz/../..'); // true
path.isAbsolute('qux/');       // false
path.isAbsolute('.');          // false
copy

Unter 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

Ein TypeError wird ausgelöst, wenn path kein String ist.

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

• ...paths <string> Eine Sequenz von Pfadsegmenten
• Rückgabe: <string>

Die path.join()-Methode verbindet alle angegebenen path-Segmente unter Verwendung des plattformspezifischen Trennzeichens und normalisiert anschließend den resultierenden Pfad.

Segmente mit der Länge Null werden ignoriert. Wenn der zusammengefügte Pfad-String eine Länge von Null hat, wird '.' zurückgegeben, was das aktuelle Arbeitsverzeichnis repräsentiert.

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

Ein TypeError wird ausgelöst, wenn eines der Pfadsegmente kein String ist.

path.normalize(path)#

• path <string>
• Rückgabe: <string>

Die path.normalize()-Methode normalisiert den angegebenen path und löst '..'- und '.'-Segmente auf.

Wenn mehrere aufeinanderfolgende Pfadtrennzeichen gefunden werden (z. B. / unter POSIX und entweder \ oder / unter Windows), werden sie durch eine einzige Instanz des plattformspezifischen Trennzeichens ersetzt (/ unter POSIX und \ unter Windows). Nachgestellte Trennzeichen bleiben erhalten.

Wenn der path ein String der Länge Null ist, wird '.' zurückgegeben, was das aktuelle Arbeitsverzeichnis repräsentiert.

Unter POSIX entsprechen die von dieser Funktion angewandten Normalisierungsarten nicht strikt der POSIX-Spezifikation. Zum Beispiel ersetzt diese Funktion zwei führende Schrägstriche durch einen einzelnen Schrägstrich, als ob es ein regulärer absoluter Pfad wäre, während einige POSIX-Systeme Pfaden, die mit genau zwei Schrägstrichen beginnen, eine besondere Bedeutung beimessen. Ebenso können andere durch diese Funktion ausgeführte Ersetzungen, wie das Entfernen von ..-Segmenten, die Art und Weise ändern, wie das zugrunde liegende System den Pfad auflöst.

Zum Beispiel unter POSIX:

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

Unter Windows

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// Returns: 'C:\\temp\\foo\\'
copy

Da Windows mehrere Pfadtrennzeichen erkennt, werden beide Trennzeichen durch Instanzen des von Windows bevorzugten Trennzeichens (\) ersetzt.

path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// Returns: 'C:\\temp\\foo\\bar'
copy

Ein TypeError wird ausgelöst, wenn path kein String ist.

path.parse(path)#

• path <string>
• Rückgabewert: <Object>

Die path.parse()-Methode gibt ein Objekt zurück, dessen Eigenschaften signifikante Elemente des path repräsentieren. Nachgestellte Verzeichnistrennzeichen werden ignoriert, siehe path.sep.

Das zurückgegebene Objekt hat die folgenden Eigenschaften:

• dir <string>
• root <string>
• base <string>
• name <string>
• ext <string>

Zum Beispiel unter 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

Unter 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

Ein TypeError wird ausgelöst, wenn path kein String ist.

path.posix#

• Typ: <Object>

Die Eigenschaft path.posix bietet Zugriff auf die POSIX-spezifischen Implementierungen der path-Methoden.

Die API ist über require('node:path').posix oder require('node:path/posix') zugänglich.

path.relative(from, to)#

• from <string>
• to <string>
• Rückgabe: <string>

Die path.relative()-Methode gibt den relativen Pfad von from nach to basierend auf dem aktuellen Arbeitsverzeichnis zurück. Wenn from und to beide denselben Pfad auflösen (nachdem path.resolve() auf beide angewendet wurde), wird ein leerer String zurückgegeben.

Wenn ein leerer String als from oder to übergeben wird, wird anstelle des leeren Strings das aktuelle Arbeitsverzeichnis verwendet.

Zum Beispiel unter POSIX:

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

Unter Windows

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

Ein TypeError wird ausgelöst, wenn entweder from oder to kein String ist.

path.resolve([...paths])#

• ...paths <string> Eine Sequenz von Pfaden oder Pfadsegmenten
• Rückgabe: <string>

Die path.resolve()-Methode löst eine Sequenz von Pfaden oder Pfadsegmenten in einen absoluten Pfad auf.

Die angegebene Sequenz von Pfaden wird von rechts nach links verarbeitet, wobei jeder nachfolgende path vorangestellt wird, bis ein absoluter Pfad konstruiert ist. Zum Beispiel: Bei der Sequenz von Pfadsegmenten /foo, /bar, baz würde der Aufruf path.resolve('/foo', '/bar', 'baz') den Wert /bar/baz zurückgeben, da 'baz' kein absoluter Pfad ist, aber '/bar' + '/' + 'baz' schon.

Wenn nach der Verarbeitung aller angegebenen path-Segmente noch kein absoluter Pfad generiert wurde, wird das aktuelle Arbeitsverzeichnis verwendet.

Der resultierende Pfad wird normalisiert und nachgestellte Schrägstriche werden entfernt, sofern der Pfad nicht in das Stammverzeichnis aufgelöst wird.

Segmente mit der Länge Null werden ignoriert.

Wenn keine path-Segmente übergeben werden, gibt path.resolve() den absoluten Pfad des aktuellen Arbeitsverzeichnisses zurück.

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

Ein TypeError wird ausgelöst, wenn eines der Argumente kein String ist.

path.sep#

• Typ: <string>

Stellt das plattformspezifische Pfadsegment-Trennzeichen bereit:

• \ unter Windows
• / unter POSIX

Zum Beispiel unter POSIX:

'foo/bar/baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']
copy

Unter Windows

'foo\\bar\\baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']
copy

Unter Windows werden sowohl der normale Schrägstrich (/) als auch der Backslash (\) als Pfadsegment-Trennzeichen akzeptiert; die path-Methoden fügen jedoch nur Backslashes (\) hinzu.

path.toNamespacedPath(path)#

• path <string>
• Rückgabe: <string>

Gibt nur auf Windows-Systemen einen äquivalenten Namespace-präfixierten Pfad für den angegebenen path zurück. Wenn path kein String ist, wird path ohne Änderungen zurückgegeben.

Diese Methode ist nur auf Windows-Systemen sinnvoll. Auf POSIX-Systemen ist die Methode funktionslos und gibt immer path ohne Änderungen zurück.

path.win32#

• Typ: <Object>

Die Eigenschaft path.win32 bietet Zugriff auf die Windows-spezifischen Implementierungen der path-Methoden.

Die API ist über require('node:path').win32 oder require('node:path/win32') zugänglich.