Node.js v25.0.0 文档
- Node.js v25.0.0
-
目录
- 路径
- Windows 与 POSIX
path.basename(path[, suffix])
path.delimiter
path.dirname(path)
path.extname(path)
path.format(pathObject)
path.matchesGlob(path, pattern)
path.isAbsolute(path)
path.join([...paths])
path.normalize(path)
path.parse(path)
path.posix
path.relative(from, to)
path.resolve([...paths])
path.sep
path.toNamespacedPath(path)
path.win32
- 路径
-
索引
- 断言测试
- 异步上下文跟踪
- 异步钩子
- 缓冲区
- C++ 插件
- 使用 Node-API 的 C/C++ 插件
- C++ 嵌入器 API
- 子进程
- 集群
- 命令行选项
- 控制台
- 加密
- 调试器
- 已弃用的 API
- 诊断通道
- DNS
- 域
- 环境变量
- 错误
- 事件
- 文件系统
- 全局对象
- HTTP
- HTTP/2
- HTTPS
- 检查器
- 国际化
- 模块:CommonJS 模块
- 模块:ECMAScript 模块
- 模块:
node:module
API - 模块:包
- 模块:TypeScript
- 网络
- 操作系统
- 路径
- 性能钩子
- 权限
- 进程
- Punycode
- 查询字符串
- 逐行读取
- REPL
- 报告
- 单一可执行文件应用
- SQLite
- 流
- 字符串解码器
- 测试运行器
- 定时器
- TLS/SSL
- 跟踪事件
- TTY
- UDP/数据报
- URL
- 实用工具
- V8
- 虚拟机
- WASI
- Web Crypto API
- Web Streams API
- 工作线程
- Zlib
- 其他版本
- 选项
路径#
源代码: lib/path.js
node:path
模块提供了用于处理文件和目录路径的实用工具。可以通过以下方式访问:
const path = require('node:path');
import path from 'node:path';
Windows 与 POSIX#
node:path
模块的默认操作会根据 Node.js 应用程序运行的操作系统而有所不同。具体来说,当在 Windows 操作系统上运行时,node:path
模块会假定正在使用 Windows 风格的路径。
因此,在 POSIX 和 Windows 上使用 path.basename()
可能会产生不同的结果。
在 POSIX 上
path.basename('C:\\temp\\myfile.html');
// Returns: 'C:\\temp\\myfile.html'
在 Windows 上
path.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'
要在任何操作系统上处理 Windows 文件路径时获得一致的结果,请使用 path.win32
。
在 POSIX 和 Windows 上
path.win32.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'
要在任何操作系统上处理 POSIX 文件路径时获得一致的结果,请使用 path.posix
。
在 POSIX 和 Windows 上
path.posix.basename('/tmp/myfile.html');
// Returns: 'myfile.html'
在 Windows 上,Node.js 遵循每个驱动器有各自工作目录的概念。当使用不带反斜杠的驱动器路径时,可以观察到此行为。例如,path.resolve('C:\\')
可能返回与 path.resolve('C:')
不同的结果。更多信息,请参阅此 MSDN 页面。
path.basename(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'
尽管 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'
如果 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']
在 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\\']
path.dirname(path)
#
path.dirname()
方法返回一个 path
的目录名,类似于 Unix 的 dirname
命令。尾部的目录分隔符会被忽略,请参阅 path.sep
。
path.dirname('/foo/bar/baz/asdf/quux');
// Returns: '/foo/bar/baz/asdf'
如果 path
不是字符串,则会抛出 TypeError
。
path.extname(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'
如果 path
不是字符串,则会抛出 TypeError
。
path.format(pathObject)
#
path.format()
方法从一个对象返回一个路径字符串。这与 path.parse()
相反。
当为 pathObject
提供属性时,请记住在某些组合中,一个属性的优先级高于另一个:
- 如果提供了
pathObject.dir
,则忽略pathObject.root
。 - 如果存在
pathObject.base
,则忽略pathObject.ext
和pathObject.name
。
例如,在 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'
在 Windows 上
path.format({
dir: 'C:\\path\\dir',
base: 'file.txt',
});
// Returns: 'C:\\path\\dir\\file.txt'
path.matchesGlob(path, pattern)
#
path.matchesGlob()
方法判断 path
是否匹配 pattern
。
例如:
path.matchesGlob('/foo/bar', '/foo/*'); // true
path.matchesGlob('/foo/bar*', 'foo/bird'); // false
如果 path
或 pattern
不是字符串,则抛出 TypeError
。
path.isAbsolute(path)
#
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
在 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
如果 path
不是字符串,则会抛出 TypeError
。
path.join([...paths])
#
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 {}'
如果任何路径片段不是字符串,则会抛出 TypeError
。
path.normalize(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'
在 Windows 上
path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// Returns: 'C:\\temp\\foo\\'
由于 Windows 识别多种路径分隔符,这两种分隔符都将被替换为 Windows 首选分隔符 (\
) 的实例。
path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// Returns: 'C:\\temp\\foo\\bar'
如果 path
不是字符串,则会抛出 TypeError
。
path.parse(path)
#
path.parse()
方法返回一个对象,其属性表示 path
的重要元素。尾部的目录分隔符会被忽略,请参阅 path.sep
。
返回的对象将具有以下属性:
例如,在 POSIX 上:
path.parse('/home/user/dir/file.txt');
// Returns:
// { root: '/',
// dir: '/home/user/dir',
// base: 'file.txt',
// ext: '.txt',
// name: 'file' }
┌─────────────────────┬────────────┐
│ dir │ base │
├──────┬ ├──────┬─────┤
│ root │ │ name │ ext │
" / home/user/dir / file .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)
在 Windows 上
path.parse('C:\\path\\dir\\file.txt');
// Returns:
// { root: 'C:\\',
// dir: 'C:\\path\\dir',
// base: 'file.txt',
// ext: '.txt',
// name: 'file' }
┌─────────────────────┬────────────┐
│ dir │ base │
├──────┬ ├──────┬─────┤
│ root │ │ name │ ext │
" C:\ path\dir \ file .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)
如果 path
不是字符串,则会抛出 TypeError
。
path.posix
#
- 类型:<Object>
path.posix
属性提供了对 path
方法的 POSIX 特定实现的访问。
该 API 可通过 require('node:path').posix
或 require('node:path/posix')
访问。
path.relative(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'
在 Windows 上
path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb');
// Returns: '..\\..\\impl\\bbb'
如果 from
或 to
不是字符串,则会抛出 TypeError
。
path.resolve([...paths])
#
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'
如果任何参数不是字符串,则会抛出 TypeError
。
path.sep
#
- 类型:<string>
提供特定于平台的路径片段分隔符:
- Windows 上是
\
- POSIX 上是
/
例如,在 POSIX 上:
'foo/bar/baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']
在 Windows 上
'foo\\bar\\baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']
在 Windows 上,正斜杠 (/
) 和反斜杠 (\
) 都被接受为路径片段分隔符;但是,path
方法只会添加反斜杠 (\
)。
path.toNamespacedPath(path)
#
仅在 Windows 系统上,为给定的 path
返回一个等效的命名空间前缀路径。如果 path
不是字符串,则会不加修改地返回 path
。
此方法仅在 Windows 系统上有意义。在 POSIX 系统上,此方法不起作用,并且总是返回未经修改的 path
。
path.win32
#
- 类型:<Object>
path.win32
属性提供了对 path
方法的 Windows 特定实现的访问。
该 API 可通过 require('node:path').win32
或 require('node:path/win32')
访问。