Node.js v12.14.0 文档

最新推荐文章于 2023-05-07 21:08:59 发布

Michael18811380328

最新推荐文章于 2023-05-07 21:08:59 发布

阅读量426

点赞数

文章标签： node.js

本文链接：https://blog.csdn.net/weixin_41697143/article/details/129013299

版权

Node.js v12.14.0 文档

fs(文件系统)
文件路径
- URL 对象的支持
文件描述符
线程池的使用
fs.Dir 类
- dir.close()
- dir.close(callback)
- dir.closeSync()
- dir.path
- dir.read()
- dir.read(callback)
- dir.readSync()
- dir[Symbol.asyncIterator]()
fs.Dirent 类
- dirent.isBlockDevice()
- dirent.isCharacterDevice()
- dirent.isDirectory()
- dirent.isFIFO()
- dirent.isFile()
- dirent.isSocket()
- dirent.isSymbolicLink()
- dirent.name
fs.FSWatcher 类
- 'change' 事件
- 'close' 事件
- 'error' 事件
- watcher.close()
fs.ReadStream 类
- 'close' 事件
- 'open' 事件
- 'ready' 事件
- readStream.bytesRead
- readStream.path
- readStream.pending
fs.Stats 类
- stats.isBlockDevice()
- stats.isCharacterDevice()
- stats.isDirectory()
- stats.isFIFO()
- stats.isFile()
- stats.isSocket()
- stats.isSymbolicLink()
- stats.dev
- stats.ino
- stats.mode
- stats.nlink
- stats.uid
- stats.gid
- stats.rdev
- stats.size
- stats.blksize
- stats.blocks
- stats.atimeMs
- stats.mtimeMs
- stats.ctimeMs
- stats.birthtimeMs
- stats.atimeNs
- stats.mtimeNs
- stats.ctimeNs
- stats.birthtimeNs
- stats.atime
- stats.mtime
- stats.ctime
- stats.birthtime
- 文件属性的时间值
fs.WriteStream 类
- 'close' 事件
- 'open' 事件
- 'ready' 事件
- writeStream.bytesWritten
- writeStream.path
- writeStream.pending
[fs.access(path, mode], callback)
[fs.accessSync(path, mode])
[fs.appendFile(path, data, options], callback)
[fs.appendFileSync(path, data, options])
fs.chmod(path, mode, callback)
- 文件的模式
fs.chmodSync(path, mode)
fs.chown(path, uid, gid, callback)
fs.chownSync(path, uid, gid)
fs.close(fd, callback)
fs.closeSync(fd)
fs.constants
[fs.copyFile(src, dest, flags], callback)
[fs.copyFileSync(src, dest, flags])
[fs.createReadStream(path, options])
[fs.createWriteStream(path, options])
fs.exists(path, callback)
fs.existsSync(path)
fs.fchmod(fd, mode, callback)
fs.fchmodSync(fd, mode)
fs.fchown(fd, uid, gid, callback)
fs.fchownSync(fd, uid, gid)
fs.fdatasync(fd, callback)
fs.fdatasyncSync(fd)
[fs.fstat(fd, options], callback)
[fs.fstatSync(fd, options])
fs.fsync(fd, callback)
fs.fsyncSync(fd)
[fs.ftruncate(fd, len], callback)
[fs.ftruncateSync(fd, len])
fs.futimes(fd, atime, mtime, callback)
fs.futimesSync(fd, atime, mtime)
fs.lchmod(path, mode, callback)
fs.lchmodSync(path, mode)
fs.lchown(path, uid, gid, callback)
fs.lchownSync(path, uid, gid)
fs.link(existingPath, newPath, callback)
fs.linkSync(existingPath, newPath)
[fs.lstat(path, options], callback)
[fs.lstatSync(path, options])
[fs.mkdir(path, options], callback)
[fs.mkdirSync(path, options])
[fs.mkdtemp(prefix, options], callback)
[fs.mkdtempSync(prefix, options])
[fs.open(path, flags[, mode]], callback)
[fs.opendir(path, options], callback)
[fs.opendirSync(path, options])
[fs.openSync(path, flags, mode])
fs.read(fd, buffer, offset, length, position, callback)
[fs.readdir(path, options], callback)
[fs.readdirSync(path, options])
[fs.readFile(path, options], callback)
- 文件描述符
[fs.readFileSync(path, options])
[fs.readlink(path, options], callback)
[fs.readlinkSync(path, options])
fs.readSync(fd, buffer, offset, length, position)
[fs.realpath(path, options], callback)
[fs.realpath.native(path, options], callback)
[fs.realpathSync(path, options])
[fs.realpathSync.native(path, options])
fs.rename(oldPath, newPath, callback)
fs.renameSync(oldPath, newPath)
[fs.rmdir(path, options], callback)
[fs.rmdirSync(path, options])
[fs.stat(path, options], callback)
[fs.statSync(path, options])
[fs.symlink(target, path, type], callback)
[fs.symlinkSync(target, path, type])
[fs.truncate(path, len], callback)
[fs.truncateSync(path, len])
fs.unlink(path, callback)
fs.unlinkSync(path)
[fs.unwatchFile(filename, listener])
fs.utimes(path, atime, mtime, callback)
fs.utimesSync(path, atime, mtime)
[fs.watch(filename, options][, listener])
- 注意事项
- 可用性
- 索引节点
- 文件名参数
[fs.watchFile(filename, options], listener)
[fs.write(fd, buffer, offset[, length[, position]]], callback)
[fs.write(fd, string, position[, encoding]], callback)
[fs.writeFile(file, data, options], callback)
- 使用 fs.writeFile() 与文件描述符
[fs.writeFileSync(file, data, options])
[fs.writeSync(fd, buffer, offset[, length[, position]]])
[fs.writeSync(fd, string, position[, encoding]])
[fs.writev(fd, buffers, position], callback)
[fs.writevSync(fd, buffers, position])
fs 的 Promise API
- FileHandle 类
- filehandle.appendFile(data, options)
- filehandle.chmod(mode)
- filehandle.chown(uid, gid)
- filehandle.close()
- filehandle.datasync()
- filehandle.fd
- filehandle.read(buffer, offset, length, position)
- filehandle.readFile(options)
- [filehandle.stat(options])
- filehandle.sync()
- filehandle.truncate(len)
- filehandle.utimes(atime, mtime)
- [filehandle.write(buffer, offset[, length[, position]]])
- [filehandle.write(string, position[, encoding]])
- filehandle.writeFile(data, options)
- [filehandle.writev(buffers, position])
- [fsPromises.access(path, mode])
- [fsPromises.appendFile(path, data, options])
- fsPromises.chmod(path, mode)
- fsPromises.chown(path, uid, gid)
- [fsPromises.copyFile(src, dest, flags])
- fsPromises.lchmod(path, mode)
- fsPromises.lchown(path, uid, gid)
- fsPromises.link(existingPath, newPath)
- [fsPromises.lstat(path, options])
- [fsPromises.mkdir(path, options])
- [fsPromises.mkdtemp(prefix, options])
- [fsPromises.open(path, flags, mode])
- [fsPromises.opendir(path, options])
- [fsPromises.readdir(path, options])
- [fsPromises.readFile(path, options])
- [fsPromises.readlink(path, options])
- [fsPromises.realpath(path, options])
- fsPromises.rename(oldPath, newPath)
- [fsPromises.rmdir(path, options])
- [fsPromises.stat(path, options])
- [fsPromises.symlink(target, path, type])
- [fsPromises.truncate(path, len])
- fsPromises.unlink(path)
- fsPromises.utimes(path, atime, mtime)
- [fsPromises.writeFile(file, data, options])
FS 常量
- 文件可访问性的常量
- 文件拷贝的常量
- 文件打开的常量
- 文件类型的常量
- 文件模式的常量
文件系统标志

fs(文件系统)#

稳定性: 2 - 稳定

fs 模块提供了一个 API，用于以模仿标准 POSIX 函数的方式与文件系统进行交互。

要使用此模块：

const fs = require('fs');

所有文件系统操作都具有同步和异步的形式。

异步的形式总是将完成回调作为其最后一个参数。传给完成回调的参数取决于具体方法，但第一个参数始终预留用于异常。如果操作成功完成，则第一个参数将为 null 或 undefined。

const fs = require('fs');

fs.unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('已成功删除 /tmp/hello');
});

使用同步的操作发生的异常会立即抛出，可以使用 try…catch 处理，也可以允许冒泡。

const fs = require('fs');

try {
  fs.unlinkSync('/tmp/hello');
  console.log('已成功删除 /tmp/hello');
} catch (err) {
  // 处理错误
}

使用异步的方法时无法保证顺序。因此，以下的操作容易出错，因为 fs.stat() 操作可能在 fs.rename() 操作之前完成：

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  console.log('重命名完成');
});
fs.stat('/tmp/world', (err, stats) => {
  if (err) throw err;
  console.log(`文件属性: ${JSON.stringify(stats)}`);
});

要正确地排序这些操作，则将 fs.stat() 调用移动到 fs.rename() 操作的回调中：

fs.rename('/tmp/hello', '/tmp/world', (err) => {
  if (err) throw err;
  fs.stat('/tmp/world', (err, stats) => {
    if (err) throw err;
    console.log(`文件属性: ${JSON.stringify(stats)}`);
  });
});

在繁忙的进程中，强烈建议使用这些调用的异步版本。同步的版本将阻塞整个进程，直到它们完成(停止所有连接)。

虽然不推荐这样使用，但大多数 fs 函数允许省略回调参数，在这种情况下，使用一个会重新抛出错误的默认回调。要获取原始调用点的跟踪，则设置 NODE_DEBUG 环境变量：

不推荐在异步的 fs 函数上省略回调函数，因为可能导致将来抛出错误。

$ cat script.js
function bad() {
  require('fs').readFile('/');
}
bad();

$ env NODE_DEBUG=fs node script.js
fs.js:88
        throw backtrace;
        ^
Error: EISDIR: illegal operation on a directory, read
    <stack trace.>

文件路径#

大多数 fs 操作接受的文件路径可以指定为字符串、Buffer、或使用 file: 协议的 URL 对象。

字符串形式的路径被解析为标识绝对或相对文件名的 UTF-8 字符序列。相对路径将相对于 process.cwd() 指定的当前工作目录进行解析。

在 POSIX 上使用绝对路径的示例：

const fs = require('fs');

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

在 POSIX 上使用相对路径(相对于 process.cwd())的示例：

fs.open('file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

使用 Buffer 指定的路径主要用于将文件路径视为不透明字节序列的某些 POSIX 操作系统。在这样的系统上，单个文件路径可以包含使用多种字符编码的子序列。与字符串路径一样， Buffer 路径可以是相对路径或绝对路径：

在 POSIX 上使用绝对路径的示例：

fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => {
  if (err) throw err;
  fs.close(fd, (err) => {
    if (err) throw err;
  });
});

在 Windows 上，Node.js 遵循每个驱动器工作目录的概念。当使用没有反斜杠的驱动器路径时，可以观察到此行为。例如， fs.readdirSync('c:\\') 可能会返回与 fs.readdirSync('c:') 不同的结果。有关详细信息，参阅此 MSDN 页面。

URL 对象的支持#

对于大多数 fs 模块的函数， path 或 filename 参数可以传入 WHATWG URL 对象。仅支持使用 file: 协议的 URL 对象。

const fs = require('fs');
const fileUrl = new URL('file:///tmp/hello');

fs.readFileSync(fileUrl);

file: URL 始终是绝对路径。

使用 WHATWG URL 对象可能会采用特定于平台的行为。

在 Windows 上，带有主机名的 file: URL 转换为 UNC 路径，而带有驱动器号的 file: URL 转换为本地绝对路径。没有主机名和驱动器号的 file: URL 将导致抛出错误：

// 在 Windows 上：

// - 带有主机名的 WHATWG 文件的 URL 转换为 UNC 路径。
// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));

// - 带有驱动器号的 WHATWG 文件的 URL 转换为绝对路径。
// file:///C:/tmp/hello => C:\tmp\hello
fs.readFileSync(new URL('file:///C:/tmp/hello'));

// - 没有主机名的 WHATWG 文件的 URL 必须包含驱动器号。
fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file'));
fs.readFileSync(new URL('file:///c/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute

带有驱动器号的 file: URL 必须使用 : 作为驱动器号后面的分隔符。使用其他分隔符将导致抛出错误。

在所有其他平台上，不支持带有主机名的 file: URL，使用时将导致抛出错误：

// 在其他平台上：

// - 不支持带有主机名的 WHATWG 文件的 URL。
// file://hostname/p/a/t/h/file => throw!
fs.readFileSync(new URL('file://hostname/p/a/t/h/file'));
// TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute

// - WHATWG 文件的 URL 转换为绝对路径。
// file:///tmp/hello => /tmp/hello
fs.readFileSync(new URL('file:///tmp/hello'));

包含编码后的斜杆字符(%2F)的 file: URL 在所有平台上都将导致抛出错误：

// 在 Windows 上：
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

// 在 POSIX 上：
fs.readFileSync(new URL('file:///p/a/t/h/%2F'));
fs.readFileSync(new URL('file:///p/a/t/h/%2f'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
/ characters */

在 Windows 上，包含编码后的反斜杆字符(%5C)的 file: URL 将导致抛出错误：

// 在 Windows 上：
fs.readFileSync(new URL('file:///C:/path/%5C'));
fs.readFileSync(new URL('file:///C:/path/%5c'));
/* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded
\ or / characters */

文件描述符#

在 POSIX 系统上，对于每个进程，内核都维护着一张当前打开着的文件和资源的表格。每个打开的文件都分配了一个称为文件描述符的简单的数字标识符。在系统层，所有文件系统操作都使用这些文件描述符来标识和跟踪每个特定的文件。 Windows 系统使用了一个虽然不同但概念上类似的机制来跟踪资源。为了简化用户的工作，Node.js 抽象出操作系统之间的特定差异，并为所有打开的文件分配一个数字型的文件描述符。

fs.open() 方法用于分配新的文件描述符。一旦被分配，则文件描述符可用于从文件读取数据、向文件写入数据、或请求关于文件的信息。

fs.open('/open/some/file.txt', 'r', (err, fd) => {
  if (err) throw err;
  fs.fstat(fd, (err, stat) => {
    if (err) throw err;
    // 使用文件属性。

    // 始终关闭文件描述符！
    fs.close(fd, (err) => {
      if (err) throw err;
    });
  });
});

大多数操作系统限制在任何给定时间内可能打开的文件描述符的数量，因此当操作完成时关闭描述符至关重要。如果不这样做将导致内存泄漏，最终导致应用程序崩溃。

线程池的使用#

所有的文件系统 API，除了 fs.FSWatcher() 和那些显式同步的之外，都使用 libuv 的线程池，这对某些应用程序可能会产生意外和负面的性能影响。有关更多信息，参阅 UV_THREADPOOL_SIZE 文档。

fs.Dir 类#

代表目录流的类。

由 fs.opendir()、fs.opendirSync() 或 fsPromises.opendir() 创建。

const fs = require('fs');

async function print(path) {
  const dir = await fs.promises.opendir(path);
  for await (const dirent of dir) {
    console.log(dirent.name);
  }
}
print('./').catch(console.error);

dir.close()#

异步地关闭目录的底层资源句柄。随后的读取将会导致错误。

返回一个 Promise，将会在关闭资源之后被解决。

dir.close(callback)#

callback
err

异步地关闭目录的底层资源句柄。随后的读取将会导致错误。

关闭资源句柄之后将会调用 callback。

dir.closeSync()#

同步地关闭目录的底层资源句柄。随后的读取将会导致错误。

dir.path#

此目录的只读路径，与提供给 fs.opendir()、fs.opendirSync() 或 fsPromises.opendir() 的一样。

dir.read()#

返回: 包含 | 。

通过 readdir(3) 异步地读取下一个目录项作为 fs.Dirent。

读取完成之后，将会返回一个 Promise，它被解决时将会返回 fs.Dirent 或 null(如果没有更多的目录项要读取)。

此函数返回的目录项不遵循操作系统的底层目录机制所提供的特定顺序。遍历目录时添加或删除的目录项可能会或可能不会包含在遍历的结果中。

常量	八进制值	说明
`fs.constants.S_IRUSR`	`0o400`	所有者可读
`fs.constants.S_IWUSR`	`0o200`	所有者可写
`fs.constants.S_IXUSR`	`0o100`	所有者可执行或搜索
`fs.constants.S_IRGRP`	`0o40`	群组可读
`fs.constants.S_IWGRP`	`0o20`	群组可写
`fs.constants.S_IXGRP`	`0o10`	群组可执行或搜索
`fs.constants.S_IROTH`	`0o4`	其他人可读
`fs.constants.S_IWOTH`	`0o2`	其他人可写
`fs.constants.S_IXOTH`	`0o1`	其他人可执行或搜索

数字	说明
`7`	可读、可写、可执行
`6`	可读、可写
`5`	可读、可执行
`4`	只读
`3`	可写、可执行
`2`	只写
`1`	只可执行
`0`	没有权限

常量	说明
`F_OK`	表明文件对调用进程可见。这对于判断文件是否存在很有用，但对 `rwx` 权限没有任何说明。如果未指定模式，则默认值为该值。
`R_OK`	表明调用进程可以读取文件。
`W_OK`	表明调用进程可以写入文件。
`X_OK`	表明调用进程可以执行文件。在 Windows 上无效(表现得像 `fs.constants.F_OK`)。

常量	说明
`COPYFILE_EXCL`	如果目标路径已存在，则拷贝操作将失败。
`COPYFILE_FICLONE`	拷贝操作将尝试创建写时拷贝链接。如果底层平台不支持写时拷贝，则使用备选的拷贝机制。
`COPYFILE_FICLONE_FORCE`	拷贝操作将尝试创建写时拷贝链接。如果底层平台不支持写时拷贝，则拷贝操作将失败。

常量	说明
`O_RDONLY`	表明打开文件用于只读访问。
`O_WRONLY`	表明打开文件用于只写访问。
`O_RDWR`	表明打开文件用于读写访问。
`O_CREAT`	表明如果文件尚不存在则创建该文件。
`O_EXCL`	表明如果设置了 `O_CREAT` 标志且文件已存在，则打开文件应该失败。
`O_NOCTTY`	表明如果路径表示终端设备，则打开该路径不应该造成该终端变成进程的控制终端(如果进程还没有终端)。
`O_TRUNC`	表明如果文件存在且是常规文件、并且文件成功打开以进行写入访问，则其长度应截断为零。
`O_APPEND`	表明数据将会追加到文件的末尾。
`O_DIRECTORY`	表明如果路径不是目录，则打开应该失败。
`O_NOATIME`	表明文件系统的读取访问将不再导致与文件相关联的 `atime` 信息的更新。仅在 Linux 操作系统上可用。
`O_NOFOLLOW`	表明如果路径是符号链接，则打开应该失败。
`O_SYNC`	表明文件是为同步 I/O 打开的，写入操作将会等待文件的完整性。
`O_DSYNC`	表明文件是为同步 I/O 打开的，写入操作将会等待数据的完整性
`O_SYMLINK`	表明打开符号链接自身，而不是它指向的资源。
`O_DIRECT`	表明将尝试最小化文件 I/O 的缓存效果。
`O_NONBLOCK`	表明在可能的情况下以非阻塞模式打开文件。
`UV_FS_O_FILEMAP`	当设置后，将会使用内存文件的映射来访问文件。此标志仅在 Windows 操作系统上可用。在其他操作系统上，此标志会被忽略。

常量	说明
`S_IFMT`	用于提取文件类型代码的位掩码。
`S_IFREG`	表示常规文件。
`S_IFDIR`	表示目录。
`S_IFCHR`	表示面向字符的设备文件。
`S_IFBLK`	表示面向块的设备文件。
`S_IFIFO`	表示 FIFO 或管道。
`S_IFLNK`	表示符号链接。
`S_IFSOCK`	表示套接字。

常量	说明
`S_IRWXU`	表明所有者可读、可写、可执行。
`S_IRUSR`	表明所有者可读。
`S_IWUSR`	表明所有者可写。
`S_IXUSR`	表明所有者可执行。
`S_IRWXG`	表明群组可读、可写、可执行。
`S_IRGRP`	表明群组可读。
`S_IWGRP`	表明群组可写。
`S_IXGRP`	表明群组可执行。
`S_IRWXO`	表明其他人可读、可写、可执行。
`S_IROTH`	表明其他人可读。
`S_IWOTH`	表明其他人可写。
`S_IXOTH`	表明其他人可执行。

Node.js v12.14.0 文档

Node.js v12.14.0 文档

目录

fs(文件系统)#

文件路径#

URL 对象的支持#

文件描述符#

线程池的使用#

fs.Dir 类#

dir.close()#

dir.close(callback)#

dir.closeSync()#

dir.path#

dir.read()#

dir.read(callback)#

dir.readSync()#

dirSymbol.asyncIterator#

fs.Dirent 类#

dirent.isBlockDevice()#

dirent.isCharacterDevice()#

dirent.isDirectory()#

dirent.isFIFO()#

dirent.isFile()#

dirent.isSocket()#

dirent.isSymbolicLink()#

dirent.name#

fs.FSWatcher 类#

'change' 事件#

'close' 事件#

'error' 事件#

watcher.close()#

fs.ReadStream 类#

'close' 事件#

'open' 事件#

'ready' 事件#

readStream.bytesRead#

readStream.path#

readStream.pending#

fs.Stats 类#

stats.isBlockDevice()#

stats.isCharacterDevice()#

stats.isDirectory()#

stats.isFIFO()#

stats.isFile()#

stats.isSocket()#

stats.isSymbolicLink()#

stats.dev#

stats.ino#

stats.mode#

stats.nlink#

stats.uid#

stats.gid#

stats.rdev#

stats.size#

stats.blksize#

stats.blocks#

stats.atimeMs#

stats.mtimeMs#

stats.ctimeMs#

stats.birthtimeMs#

stats.atimeNs#

stats.mtimeNs#

stats.ctimeNs#

stats.birthtimeNs#

stats.atime#

stats.mtime#

stats.ctime#

stats.birthtime#

文件属性的时间值#

fs.WriteStream 类#

'close' 事件#

'open' 事件#

'ready' 事件#

writeStream.bytesWritten#

writeStream.path#

writeStream.pending#

fs.access(path[, mode], callback)#

fs.accessSync(path[, mode])#

fs.appendFile(path, data[, options], callback)#

fs.appendFileSync(path, data[, options])#

dirSymbol.asyncIterator #