目录

• fs - 文件系统

  • 文件路径

    • 支持 URL 对象
  • 文件描述符
  • 线程池的使用

  • fs.FSWatcher 类

    • 'change' 事件
    • 'close' 事件
    • 'error' 事件
    • watcher.close()

  • fs.ReadStream 类

    • 'close' 事件
    • 'open' 事件
    • 'ready' 事件
    • readStream.bytesRead
    • readStream.path

  • 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.atime
    • stats.mtime
    • stats.ctime
    • stats.birthtime
    • Stat 时间的值

  • fs.WriteStream 类

    • 'close' 事件
    • 'open' 事件
    • 'ready' 事件
    • writeStream.bytesWritten
    • writeStream.path
  • 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)

    • File modes
  • 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[, mode], callback)
  • fs.mkdirSync(path[, mode])
  • fs.mkdtemp(prefix[, options], callback)
  • fs.mkdtempSync(prefix[, options])
  • fs.open(path, flags[, mode], callback)
  • 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, callback)
  • fs.rmdirSync(path)
  • 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.writeFileSync(file, data[, options])
  • fs.writeSync(fd, buffer[, offset[, length[, position]]])
  • fs.writeSync(fd, string[, position[, encoding]])

  • fs Promises API

    • class: 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.writeFile(data, options)
    • 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[, mode])
    • fsPromises.mkdtemp(prefix[, options])
    • fsPromises.open(path, flags[, mode])
    • fsPromises.readdir(path[, options])
    • fsPromises.readFile(path[, options])
    • fsPromises.readlink(path[, options])
    • fsPromises.realpath(path[, options])
    • fsPromises.rename(oldPath, newPath)
    • fsPromises.rmdir(path)
    • 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 常量

    • 文件访问常量
    • File Copy Constants
    • 文件打开常量
    • 文件类型常量
    • 文件模式常量
  • 文件系统 flag

fs - 文件系统#

查看英文版参与翻译

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('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}

异步的方法不能保证执行顺序。 所以下面的例子可能会出错，因为 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 环境变量：

不建议省略异步函数的回调函数，未来的版本可能会导致抛出错误。

$ 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() 定义的当前工作目录进行处理。

使用绝对路径的例子：

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;
  });
});

使用相对路径的例子（相对于 process.cwd()）：

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

使用 Buffer 定义的路径主要用于将文件路径处理为 opaque 字节序列的特定 POSIX 操作系统。 在这种系统上，一个文件路径可能包含使用多种字符编码的子序列。 与字符串路径一样，Buffer 路径也可以是相对的或绝对的。

使用绝对路径的例子：

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 遵循 per-drive 工作目录的理念。 当使用驱动器路径不带反斜杠时可以观察到该特性。 例如，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'));

包含编码后的斜杆符号的 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 上，包含编码后的反斜杆符号的 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 系统，内核为所有进程维护着一张当前打开着的文件与资源的表格。 每个打开的文件都会分配一个名为文件描述符的数值标识。 在系统层，所有文件系统操作使用这些文件描述符来识别与追踪每个特定的文件。 Window 系统使用了一个不同但概念类似的机制来追踪资源。 为方便用户，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.FSWatcher 类#

查看英文版参与翻译

成功调用 fs.watch() 方法会返回一个新的 fs.FSWatcher 对象。

所有 fs.FSWatcher 对象都是 EventEmitter 的，每当监视的文件被修改时会触发 'change' 事件。

'change' 事件#

查看英文版参与翻译

• eventType <string> 发生的变化事件的类型。
• filename <string> | <Buffer> 变化的文件名（如果是相关的或有效的）。

当被监视的目录或文件有变化时触发。 详见 fs.watch()。

filename 参数可能不会被提供，这依赖于操作系统支持。 如果提供了 filename，若 fs.watch() 被调用时 encoding 选项被设置为 'buffer'，则它会是一个 Buffer，否则 filename 会是一个 UTF-8 字符串。

// 例子，处理 fs.watch() 监听器。
fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => {
  if (filename) {
    console.log(filename);
    // 打印: <Buffer ...>
  }
});

'close' 事件#

查看英文版参与翻译

当 watcher 停止监视文件变化时触发。 关闭的 fs.FSWatcher 对象在事件处理函数中不再可用。

'error' 事件#

查看英文版参与翻译

• error <Error>

当监视文件发生错误时触发。 发生错误的 fs.FSWatcher 对象在事件处理函数中不再可用。

watcher.close()#

查看英文版参与翻译

fs.FSWatcher 停止监视文件的变化。 一旦停止，fs.FSWatcher 对象将不再可用。

fs.ReadStream 类#

查看英文版参与翻译

成功调用 fs.createReadStream() 会返回一个新的 fs.ReadStream 对象。

fs.ReadStream 对象都是可读流。

'close' 事件#

查看英文版参与翻译

当 fs.ReadStream 底层的文件描述符被关闭时触发。

'open' 事件#

查看英文版参与翻译

• fd <integer> ReadStream 使用的整数型文件描述符。

当 fs.ReadStream' 的文件描述符被打开时触发。

'ready' 事件#

查看英文版参与翻译

当 fs.ReadStream 已准备好被使用时触发。

'open' 之后立即触发。

readStream.bytesRead#

查看英文版参与翻译

• <number>

已读取的字节数。

readStream.path#

查看英文版参与翻译

• <string> | <Buffer>

流正在读取的文件的路径，指定在 fs.createReadStream() 的第一个参数。 如果 path 传入的是字符串，则 readStream.path 是一个字符串。 如果 path 传入的是 Buffer，则 readStream.path 是一个 Buffer。

fs.Stats 类#

查看英文版参与翻译

fs.Stats 对象提供了一个文件的信息。

从 fs.stat()、fs.lstat() 和 fs.fstat() 及其同步版本返回的对象都是该类型。 如果传入这些函数的 options 中的 bigint 为 true，则数值会是 bigint 型而不是 number 型。

Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

bigint 版本：

Stats {
  dev: 2114n,
  ino: 48064969n,
  mode: 33188n,
  nlink: 1n,
  uid: 85n,
  gid: 100n,
  rdev: 0n,
  size: 527n,
  blksize: 4096n,
  blocks: 8n,
  atimeMs: 1318289051000n,
  mtimeMs: 1318289051000n,
  ctimeMs: 1318289051000n,
  birthtimeMs: 1318289051000n,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }

stats.isBlockDevice()#

查看英文版参与翻译

• 返回: <boolean>

如果 fs.Stats 对象表示一个块设备，则返回 true 。

stats.isCharacterDevice()#

查看英文版参与翻译

• 返回: <boolean>

如果 fs.Stats 对象表示一个字符设备，则返回 true 。

stats.isDirectory()#

查看英文版参与翻译

• 返回: <boolean>

如果 fs.Stats 对象表示一个文件系统目录，则返回 true 。

stats.isFIFO()#

查看英文版参与翻译

• 返回: <boolean>

如果 fs.Stats 对象表示一个先进先出（FIFO）管道，则返回 true 。

stats.isFile()#

查看英文版参与翻译

• 返回: <boolean>

如果 fs.Stats 对象表示一个普通文件，则返回 true 。

stats.isSocket()#

查看英文版参与翻译

• 返回: <boolean>

如果 fs.Stats 对象表示一个 socket，则返回 true 。

stats.isSymbolicLink()#

查看英文版参与翻译

• 返回: <boolean>

如果 fs.Stats 对象表示一个符号链接，则返回 true 。

该方法只在使用 fs.lstat() 时有效。

stats.dev#

查看英文版参与翻译

• <number> | <bigint>

包含文件的设备的数值型标识。

stats.ino#

查看英文版参与翻译

• <number> | <bigint>

文件系统特定的文件索引节点数值。

stats.mode#

查看英文版参与翻译

• <number> | <bigint>

表示文件类型与模式的位域。

stats.nlink#

查看英文版参与翻译

• <number> | <bigint>

文件的硬链接数量。

stats.uid#

查看英文版参与翻译

• <number> | <bigint>

文件拥有者的数值型用户标识。

stats.gid#

查看英文版参与翻译

• <number> | <bigint>

拥有文件的群组的数值型群组标识。

stats.rdev#

查看英文版参与翻译

• <number> | <bigint>

如果文件是一个特殊文件，则返回数值型的设备标识。

stats.size#

查看英文版参与翻译

• <number> | <bigint>

文件的字节大小。

stats.blksize#

查看英文版参与翻译

• <number> | <bigint>

文件系统用于 I/O 操作的块大小。

stats.blocks#

查看英文版参与翻译

• <number> | <bigint>

分配给文件的块的数量。

stats.atimeMs#

查看英文版参与翻译

• <number> | <bigint>

表示文件最后一次被访问的时间戳。

stats.mtimeMs#

查看英文版参与翻译

• <number> | <bigint>

表示文件最后一次被修改的时间戳。

stats.ctimeMs#

查看英文版参与翻译

• <number> | <bigint>

表示文件状态最后一次被改变的时间戳。

stats.birthtimeMs#

查看英文版参与翻译

• <number> | <bigint>

表示文件的创建时间戳。

stats.atime#

查看英文版参与翻译

• <Date>

表示文件最后一次被访问的时间。

stats.mtime#

查看英文版参与翻译

• <Date>

表示文件最后一次被修改的时间。

stats.ctime#

查看英文版参与翻译

• <Date>

表示文件状态最后一次被改变的时间。

stats.birthtime#

查看英文版参与翻译

• <Date>

表示文件的创建时间。

Stat 时间的值#

查看英文版参与翻译

atimeMs、mtimeMs、ctimeMs 以及 birthtimeMs 属性是以毫秒为单位保存相对应时间的数值。 它们的精度与平台有关。 atime、mtime、ctime 以及 birthtime 表示各个时间的 Date 对象。 Date 与数值没有关联。 对数值重新赋值，或者改变 Date 的值，都不会影响到对应的属性。

stat 对象中的时间遵循以下语义：

• atime "访问时间" - 文件数据最近被访问的时间。 会被 mknod(2)、 utimes(2) 和 read(2) 系统调用改变。
• mtime "修改时间" - 文件数据最近被修改的时间。 会被 mknod(2)、 utimes(2) 和 write(2) 系统调用改变。
• ctime "变化时间" - 文件状态最近被改变的时间（修改索引节点数据）。 会被 chmod(2)、 chown(2)、 link(2)、 mknod(2)、 rename(2)、 unlink(2)、 utimes(2)、 read(2) 和 write(2) 系统调用改变。
• birthtime "创建时间" - 文件创建的时间。 当文件被创建时设定一次。 在不支持创建时间的文件系统中，该字段可能被替代为 ctime 或 1970-01-01T00:00Z（如 Unix 的纪元时间戳 0）。 注意，该值在此情况下可能会大于 atime 或 mtime。 在 Darwin 和其它的 FreeBSD 衍生系统中，如果 atime 被使用 utimes(2) 系统调用显式地设置为一个比当前 birthtime 更早的值，也会有这种情况。

在 Node.js v0.12 之前的版本中，在 Windows 上，ctime 保存 birthtime。 注意，在 v0.12 中，ctime 不是“创建时间”，且在 Unix 系统中一直都不是。

fs.WriteStream 类#

查看英文版参与翻译

WriteStream 是一个可写流。

'close' 事件#

查看英文版参与翻译

当 WriteStream 底层的文件描述符被关闭时触发。

'open' 事件#

查看英文版参与翻译

• fd <integer> 被 WriteStream 使用的整数型文件描述符。

当 WriteStream 的文件被打开时触发。

'ready' 事件#

查看英文版参与翻译

当 fs.WriteStream 已准备好被使用时触发。

在 'open' 事件之后立即触发。

writeStream.bytesWritten#

查看英文版参与翻译

已写入的字节数。 不包括仍在排队等待写入的数据。

writeStream.path#

查看英文版参与翻译

流正在写入的文件的路径，指定在 fs.createWriteStream() 的第一个参数。 如果 path 传入的是一个字符串，则 writeStream.path 是一个字符串。 如果 path 传入的是一个 Buffer，则 writeStream.path 是一个 Buffer。

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

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer> 默认为 fs.constants.F_OK。

• callback <Function>

  • err <Error>

测试 path 指定的文件或目录的用户权限。 mode 参数是一个可选的整数，指定要执行的可访问性检查。 文件访问常量定义了 mode 可选的值。 可以创建由两个或更多个值的位或组成的掩码（例如 fs.constants.W_OK | fs.constants.R_OK）。

最后一个参数 callback 是一个回调函数，会传入一个可能的错误参数。 如果可访问性检查失败，则错误参数会是一个 Error 对象。 下面的例子会检查 package.json 文件是否存在，且是否可读或可写。

const file = 'package.json';

// 检查文件是否存在于当前目录。
fs.access(file, fs.constants.F_OK, (err) => {
  console.log(`${file} ${err ? '不存在' : '存在'}`);
});

// 检查文件是否可读。
fs.access(file, fs.constants.R_OK, (err) => {
  console.log(`${file} ${err ? '不可读' : '可读'}`);
});

// 检查文件是否可写。
fs.access(file, fs.constants.W_OK, (err) => {
  console.log(`${file} ${err ? '不可写' : '可写'}`);
});

// 检查文件是否存在于当前目录，且是否可写。
fs.access(file, fs.constants.F_OK | fs.constants.W_OK, (err) => {
  if (err) {
    console.error(
      `${file} ${err.code === 'ENOENT' ? '不存在' : '只可读'}`);
  } else {
    console.log(`${file} 存在，且可写`);
  }
});

不建议在调用 fs.open() 、 fs.readFile() 或 fs.writeFile() 之前使用 fs.access() 检查一个文件的可访问性。 如此处理会造成紊乱情况，因为其他进程可能在两个调用之间改变该文件的状态。 所以，用户代码应该直接打开/读取/写入文件，当文件无法访问时再处理错误。

写入（不推荐）

fs.access('myfile', (err) => {
  if (!err) {
    console.error('文件已存在');
    return;
  }

  fs.open('myfile', 'wx', (err, fd) => {
    if (err) throw err;
    writeMyData(fd);
  });
});

写入（推荐）

fs.open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('文件已存在');
      return;
    }

    throw err;
  }

  writeMyData(fd);
});

读取（不推荐）

fs.access('myfile', (err) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('文件不存在');
      return;
    }

    throw err;
  }

  fs.open('myfile', 'r', (err, fd) => {
    if (err) throw err;
    readMyData(fd);
  });
});

读取（推荐）

fs.open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('文件不存在');
      return;
    }

    throw err;
  }

  readMyData(fd);
});

以上不推荐的例子会检查可访问性之后再使用文件； 但推荐的例子更好，因为它们直接使用文件并处理任何错误。

通常，仅在文件不会被直接使用时才检查一个文件的可访问性，例如当它的可访问性是来自另一个进程的信号。

fs.accessSync(path[, mode])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer> 默认为 fs.constants.F_OK。

同步地测试 path 指定的文件或目录的用户权限。 mode 参数是一个可选的整数，指定要执行的可访问性检查。 文件访问常量定义了 mode 可选的值。 可以创建由两个或更多个值的位或组成的掩码（例如 fs.constants.W_OK | fs.constants.R_OK）。

如果可访问性检查失败，则抛出一个 Error 对象。 否则返回 undefined。

try {
  fs.accessSync('etc/passwd', fs.constants.R_OK | fs.constants.W_OK);
  console.log('可读可写');
} catch (err) {
  console.error('不可访问！');
}

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

查看英文版参与翻译

• file <string> | <Buffer> | <URL> | <number> 文件名或文件描述符
• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> 默认为 'utf8'
  • mode <integer> 默认为 0o666
  • flag <string> 默认为 'a'

• callback <Function>

  • err <Error>

异步地追加数据到一个文件，如果文件不存在则创建文件。 data 可以是一个字符串或 Buffer。

例子：

fs.appendFile('message.txt', 'data to append', (err) => {
  if (err) throw err;
  console.log('The "data to append" was appended to file!');
});

如果 options 是一个字符串，则它指定了字符编码。例如：

fs.appendFile('message.txt', 'data to append', 'utf8', callback);

file 可能是一个被打开用来追加数据的数字文件描述符（通过 fs.open() 或者 fs.openSync()）。这样的文件描述符将不会被自动关闭。

fs.open('message.txt', 'a', (err, fd) => {
  if (err) throw err;
  fs.appendFile(fd, 'data to append', 'utf8', (err) => {
    fs.close(fd, (err) => {
      if (err) throw err;
    });
    if (err) throw err;
  });
});

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

查看英文版参与翻译

• file <string> | <Buffer> | <URL> | <number> 文件名或文件描述符
• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> 默认为 'utf8'
  • mode <integer> 默认为 0o666
  • flag <string> 默认为 'a'

Synchronously append data to a file, creating the file if it does not yet exist. data can be a string or a Buffer.

Example:

try {
  fs.appendFileSync('message.txt', 'data to append');
  console.log('The "data to append" was appended to file!');
} catch (err) {
  /* Handle the error */
}

If options is a string, then it specifies the encoding. Example:

fs.appendFileSync('message.txt', 'data to append', 'utf8');

The file may be specified as a numeric file descriptor that has been opened for appending (using fs.open() or fs.openSync()). The file descriptor will not be closed automatically.

let fd;

try {
  fd = fs.openSync('message.txt', 'a');
  fs.appendFileSync(fd, 'data to append', 'utf8');
} catch (err) {
  /* Handle the error */
} finally {
  if (fd !== undefined)
    fs.closeSync(fd);
}

fs.chmod(path, mode, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer>

• callback <Function>

  • err <Error>

异步地改变文件的权限。 完成回调只有一个可能的异常参数。

详见 chmod(2)。

File modes#

查看英文版参与翻译

mode 参数会在 fs.chmod() 和 fs.chmodSync()方法中用到，它是用下面的常量进行逻辑或(logical OR)操作后的数字掩码：

Constant	Octal	Description
fs.constants.S_IRUSR	0o400	read by owner
fs.constants.S_IWUSR	0o200	write by owner
fs.constants.S_IXUSR	0o100	execute/search by owner
fs.constants.S_IRGRP	0o40	read by group
fs.constants.S_IWGRP	0o20	write by group
fs.constants.S_IXGRP	0o10	execute/search by group
fs.constants.S_IROTH	0o4	read by others
fs.constants.S_IWOTH	0o2	write by others
fs.constants.S_IXOTH	0o1	execute/search by others

一个构造 mode 的更简单的方式是使用3位八进制串（比如，765）。最左侧的数字（例中的7）代表了文件所有者的权限。中间一位（例中的6）代表了组的权限。最右侧的数字（例中的5）代表其他人的权限。 A

Number	Description
7	read, write, and execute
6	read and write
5	read and execute
4	read only
3	write and execute
2	write only
1	execute only
0	no permission

举个例子，八进制值 0o765 表示：

• 文件所有者可以进行读、写和执行。
• 文件所属组可以读和写。
• 其他人可以对文件进行读和执行。

fs.chmodSync(path, mode)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer>

同步地改变文件的权限。 返回 undefined。 fs.chmod()的同步版本。

详见 chmod(2)。

fs.chown(path, uid, gid, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

• callback <Function>

  • err <Error>

异步地改变文件的所有者和群组。 完成回调只有一个可能的异常参数。

详见 chown(2)。

fs.chownSync(path, uid, gid)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

同步地改变文件的所有者和群组。 返回 undefined。 fs.chown() 的同步版本。

详见 chown(2)。

fs.close(fd, callback)#

查看英文版参与翻译

• fd <integer>

• callback <Function>

  • err <Error>

异步的 close(2)。 完成回调只有一个可能的异常参数。

fs.closeSync(fd)#

查看英文版参与翻译

• fd <integer>

同步的 close(2)。返回 undefined。

fs.constants#

查看英文版参与翻译

返回一个包含常用文件系统操作的常量的对象。 具体的常量定义在 FS Constants 中描述。

fs.copyFile(src, dest[, flags], callback)#

查看英文版参与翻译

• src <string> | <Buffer> | <URL> 要被拷贝的源文件名称
• dest <string> | <Buffer> | <URL> 拷贝操作的目标文件名
• flags <number> 拷贝操作修饰符 默认: 0
• callback <Function>

异步的将 src 拷贝到 dest。Asynchronously copies src to dest. 默认情况下，如果 dest 已经存在会被覆盖。回调函数没有给出除了异常以外的参数。Node.js 不能保证拷贝操作的原子性。如果目标文件打开后出现错误，Node.js 将尝试删除它。

flags 是一个可选的整数，用于指定行为的拷贝操作。唯一支持的 flag 是 fs.constants.COPYFILE_EXCL ，如果 dest 已经存在，则会导致拷贝操作失败。

例:

const fs = require('fs');

// 默认情况下，destination.txt 将创建或覆盖
fs.copyFile('source.txt', 'destination.txt', (err) => {
  if (err) throw err;
  console.log('source.txt was copied to destination.txt');
});

如果第三个参数是数字，那么肯定是 flags，代码如下所示:

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

// 使用 COPYFILE_EXCL ，如果 destination.txt 文件存在，操作将失败。
fs.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL, callback);

fs.copyFileSync(src, dest[, flags])#

查看英文版参与翻译

• src <string> | <Buffer> | <URL> 要被拷贝的源文件名称
• dest <string> | <Buffer> | <URL> 拷贝操作的目标文件名
• flags <number> 拷贝操作修饰符 默认: 0

同步的将 src 拷贝到 dest。默认情况下，如果 dest 已经存在会被覆盖。返回值是 undefined。Node.js 不能保证拷贝操作的原子性。如果目标文件打开后出现错误，Node.js 将尝试删除它。

flags 是一个可选的整数，用于指定行为的拷贝操作。唯一支持的 flag 是 fs.constants.COPYFILE_EXCL ，如果 dest 已经存在，则会导致拷贝操作失败。

例:

const fs = require('fs');

// 默认情况下，destination.txt 将创建或覆盖
fs.copyFileSync('source.txt', 'destination.txt');
console.log('source.txt was copied to destination.txt');

如果第三个参数是数字，那么肯定是 flags，代码如下所示:

const fs = require('fs');
const { COPYFILE_EXCL } = fs.constants;

// 使用 COPYFILE_EXCL ，如果 destination.txt 文件存在，操作将失败。
fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL);

fs.createReadStream(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> 详见支持的文件系统flag。默认为 'r'。
  • encoding <string> 默认为 null。
  • fd <integer> 默认为 null。
  • mode <integer> 默认为 0o666。
  • autoClose <boolean> 默认为 true。
  • start <integer>
  • end <integer> 默认为 Infinity。
  • highWaterMark <integer> 默认为 64 * 1024。
• 返回: <fs.ReadStream> 详见可读流。

不同于 highWaterMark 默认值为 16 kb 的可读流，该方法返回的流的 highWaterMark 默认为 64 kb。

options 可以包括 start 和 end 值，用于从文件读取一定范围的字节而不是整个文件。 start 和 end 都是包括在内的，且从 0 开始。 如果指定了 fd 且 start 不传或为 undefined，则 fs.createReadStream() 从当前文件位置按顺序地读取。 encoding 可以是任何可以被 Buffer 接受的值。

如果指定了 fd，则 ReadStream 会忽略 path 参数并且会使用指定的文件描述符。 这意味着不会触发 'open' 事件。 fd 必须是阻塞的，非阻塞的 fd 应该传给 net.Socket。

如果 autoClose 为 false，则文件描述符不会被关闭，即使有错误。 应用程序需要负责关闭它，并且确保没有文件描述符泄漏。 如果 autoClose 被设置为 true（默认），则在 error 或 end 时，文件描述符会被自动关闭。

mode 用于设置文件模式（权限和粘滞位），但仅限创建文件时。

例子，从一个大小为 100 字节的文件中读取最后 10 个字节：

fs.createReadStream('sample.txt', { start: 90, end: 99 });

如果 options 是一个字符串，则它指定字符编码。

fs.createWriteStream(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • flags <string> 详见支持的文件系统flag。默认为 'w'。
  • encoding <string> 默认为 'utf8'。
  • fd <integer> 默认为 null。
  • mode <integer> 默认为 0o666。
  • autoClose <boolean> 默认为 true。
  • start <integer>
• 返回: <fs.WriteStream> 详见可写流。

options 也有 start 选项，用于写入数据到文件指定位置。 如果是修改文件而不是覆盖它，则 flags 模式需为 r+ 模式而不是默认的 w 模式。 encoding 可以是任何可以被 Buffer 接受的值。

如果 autoClose 被设置为 true（默认），则在 error 或 finish 时，文件描述符会被自动关闭。 如果 autoClose 为 false，则文件描述符不会被关闭，即使有错误。 应用程序需要负责关闭它，并且确保没有文件描述符泄漏。

类似 ReadStream，如果指定了 fd，则 WriteStream 会忽略 path 参数并且会使用指定的文件描述符。 这意味着不会触发 'open' 事件。 fd 必须是阻塞的，非阻塞的 fd 应该传给 net.Socket。

如果 options 是一个字符串，则它指定字符编码。

fs.exists(path, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• callback <Function>

  • exists <boolean>

通过检查文件系统来测试给定的路径是否存在。然后使用 true 或 false 为参数调用 callback。例子：

fs.exists('/etc/passwd', (exists) => {
  console.log(exists ? 'it\'s there' : 'no passwd!');
});

注意此回调的参数和其他 Node.js 回调的参数不一致。 通常，Node.js 回调的第一个参数是 err, 接下来是一些其他可选参数。 fs.exists() 只有一个布尔类型的参数。这也是为什么推荐使用 fs.access() 代替 fs.exists()。

不推荐在调用 fs.open，fs.readFile()，fs.writeFile() 之前使用 fs.exists() 检测文件是否存在。这样做会引起竞争条件，因为在两次调用之间，其他进程可能修改文件。作为替代，用户应该直接开/读取/写入文件，当文件不存在时再处理错误。

例子：

write (不推荐)

fs.exists('myfile', (exists) => {
  if (exists) {
    console.error('myfile already exists');
  } else {
    fs.open('myfile', 'wx', (err, fd) => {
      if (err) throw err;
      writeMyData(fd);
    });
  }
});

write (推荐)

fs.open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  writeMyData(fd);
});

read (不推荐)

fs.exists('myfile', (exists) => {
  if (exists) {
    fs.open('myfile', 'r', (err, fd) => {
      readMyData(fd);
    });
  } else {
    console.error('myfile does not exist');
  }
});

read (推荐)

fs.open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  readMyData(fd);
});

上面这些 不推荐 的例子先检测文件是否存在再使用文件；推荐 的例子更好因为它直接使用文件并处理任何错误。

通常，仅在文件不会被直接使用时才检查一个文件的可访问性，例如当它的可访问性是来自另一个进程的信号。

fs.existsSync(path)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

fs.exists() 的同步版本。 如果路径存在，则返回 true，否则返回 false。

注意，虽然 fs.exists() 是废弃的，但 fs.existsSync() 不是。 （fs.exists() 的回调接收的参数与其他 Node.js 回调不一致，fs.existsSync() 不使用回调。）

fs.fchmod(fd, mode, callback)#

查看英文版参与翻译

• fd <integer>
• mode <integer>

• callback <Function>

  • err <Error>

异步的 fchmod(2)。 完成回调只有一个可能的异常参数。

fs.fchmodSync(fd, mode)#

查看英文版参与翻译

• fd <integer>
• mode <integer>

同步的 fchmod(2)。返回 undefined。

fs.fchown(fd, uid, gid, callback)#

查看英文版参与翻译

• fd <integer>
• uid <integer>
• gid <integer>

• callback <Function>

  • err <Error>

异步的 fchown(2)。 完成回调只有一个可能的异常参数。

fs.fchownSync(fd, uid, gid)#

查看英文版参与翻译

• fd <integer>
• uid <integer>
• gid <integer>

同步的 fchown(2)。返回 undefined。

fs.fdatasync(fd, callback)#

查看英文版参与翻译

• fd <integer>

• callback <Function>

  • err <Error>

异步的 fdatasync(2)。 完成回调只有一个可能的异常参数。

fs.fdatasyncSync(fd)#

查看英文版参与翻译

• fd <integer>

同步的 fdatasync(2)。返回 undefined。

fs.fstat(fd[, options], callback)#

查看英文版参与翻译

• fd <integer>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Asynchronous fstat(2). The callback gets two arguments (err, stats) where stats is an fs.Stats object. fstat() is identical to stat(), except that the file to be stat-ed is specified by the file descriptor fd.

fs.fstatSync(fd[, options])#

查看英文版参与翻译

• fd <integer>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.
• Returns: <fs.Stats>

Synchronous fstat(2).

fs.fsync(fd, callback)#

查看英文版参与翻译

• fd <integer>

• callback <Function>

  • err <Error>

异步的 fsync(2)。 完成回调只有一个可能的异常参数。

fs.fsyncSync(fd)#

查看英文版参与翻译

• fd <integer>

同步的 fsync(2)。返回 undefined。

fs.ftruncate(fd[, len], callback)#

查看英文版参与翻译

• fd <integer>
• len <integer> 默认 = 0

• callback <Function>

  • err <Error>

异步的 ftruncate(2)。 完成回调只有一个可能的异常参数。

如果文件描述符指向的文件大于 len 个字节，则只有前面 len 个字节会保留在文件中。

例子，下面的程序会只保留文件前4个字节。

console.log(fs.readFileSync('temp.txt', 'utf8'));
// 输出: Node.js

// 获取要截断的文件的文件描述符
const fd = fs.openSync('temp.txt', 'r+');

// 截断文件至前4个字节
fs.ftruncate(fd, 4, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt', 'utf8'));
});
// 输出: Node

如果前面的文件小于 len 个字节，则扩展文件，且扩展的部分用空字节（'\0'）填充。例子：

console.log(fs.readFileSync('temp.txt', 'utf8'));
// 输出: Node.js

// 获取要截断的文件的文件描述符
const fd = fs.openSync('temp.txt', 'r+');

// 截断文件至前10个字节，但实际大小是7个字节
fs.ftruncate(fd, 10, (err) => {
  assert.ifError(err);
  console.log(fs.readFileSync('temp.txt'));
});
// 输出: <Buffer 4e 6f 64 65 2e 6a 73 00 00 00>
// ('Node.js\0\0\0' in UTF8)

最后3个字节是空字节（'\0'），用于补充超出的截断。

fs.ftruncateSync(fd[, len])#

查看英文版参与翻译

• fd <integer>
• len <integer> 默认 = 0

同步的 ftruncate(2)。返回 undefined。

fs.futimes(fd, atime, mtime, callback)#

查看英文版参与翻译

• fd <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

• callback <Function>

  • err <Error>

改变由所提供的文件描述符所指向的对象的文件系统时间戳。详见 fs.utimes()。

请注意: 该函数不支持AIX 7.1以下版本，在AIX 7.1以下版本会返回UV_ENOSYS错误。

fs.futimesSync(fd, atime, mtime)#

查看英文版参与翻译

• fd <integer>
• atime <integer>
• mtime <integer>

fs.futimes() 的同步版本。返回 undefined。

fs.lchmod(path, mode, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer>

• callback <Function>

  • err <Error>

异步的 lchmod(2)。 完成回调只有一个可能的异常参数。

只在 macOS 有效。

fs.lchmodSync(path, mode)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer>

同步的 lchmod(2)。返回 undefined。

fs.lchown(path, uid, gid, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

• callback <Function>

  • err <Error>

异步的 lchown(2)。 完成回调只有一个可能的异常参数。

fs.lchownSync(path, uid, gid)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>

同步的 lchown(2)。返回 undefined。

fs.link(existingPath, newPath, callback)#

查看英文版参与翻译

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

• callback <Function>

  • err <Error>

异步的 link(2)。 完成回调只有一个可能的异常参数。

fs.linkSync(existingPath, newPath)#

查看英文版参与翻译

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

同步的 link(2)。返回 undefined。

fs.lstat(path[, options], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Asynchronous lstat(2). The callback gets two arguments (err, stats) where stats is a fs.Stats object. lstat() is identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.

fs.lstatSync(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.
• Returns: <fs.Stats>

Synchronous lstat(2).

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

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer> Default: 0o777

• callback <Function>

  • err <Error>

异步地创建目录。 完成回调只有一个可能的异常参数。 mode 默认为 0o777。

详见 mkdir(2)。

fs.mkdirSync(path[, mode])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer> Default: 0o777

同步地创建目录。 返回 undefined。 fs.mkdir() 的同步版本。

详见 mkdir(2)。

fs.mkdtemp(prefix[, options], callback)#

查看英文版参与翻译

• prefix <string>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

• callback <Function>

  • err <Error>
  • folder <string>

创建一个唯一的临时目录。

生成六位随机字符附加到一个要求的 prefix 后面，然后创建一个唯一的临时目录。

创建的目录路径会作为字符串传给回调的第二个参数。

可选的 options 参数可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。

例子：

fs.mkdtemp(path.join(os.tmpdir(), 'foo-'), (err, folder) => {
  if (err) throw err;
  console.log(folder);
  // 输出: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
});

注意：fs.mkdtemp() 方法会直接附加六位随机选择的字符串到 prefix 字符串。 例如，指定一个目录 /tmp，如果目的是要在 /tmp 里创建一个临时目录，则 prefix 必须 以一个指定平台的路径分隔符（require('path').sep）结尾。

// 新建的临时目录的父目录
const tmpDir = os.tmpdir();

// 该方法是 *错误的*：
fs.mkdtemp(tmpDir, (err, folder) => {
  if (err) throw err;
  console.log(folder);
  // 会输出类似于 `/tmpabc123`。
  // 注意，一个新的临时目录会被创建在文件系统的根目录，而不是在 /tmp 目录里。
});

// 该方法是 *正确的*：
const { sep } = require('path');
fs.mkdtemp(`${tmpDir}${sep}`, (err, folder) => {
  if (err) throw err;
  console.log(folder);
  // 会输出类似于 `/tmp/abc123`。
  // 一个新的临时目录会被创建在 /tmp 目录里。
});

fs.mkdtempSync(prefix[, options])#

查看英文版参与翻译

• prefix <string>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

fs.mkdtemp() 的同步版本。 返回创建的目录的路径。

可选的 options 参数可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。

fs.open(path, flags[, mode], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• flags <string> | <number>
• mode <integer> Default: 0o666

• callback <Function>

  • err <Error>
  • fd <integer>

异步地打开文件。详见 open(2)。 flags 可以是：

• 'r' - 以读取模式打开文件。如果文件不存在则发生异常。

• 'r+' - 以读写模式打开文件。如果文件不存在则发生异常。

• 'rs+' - 以同步读写模式打开文件。命令操作系统绕过本地文件系统缓存。

  这对 NFS 挂载模式下打开文件很有用，因为它可以让你跳过潜在的旧本地缓存。 它对 I/O 的性能有明显的影响，所以除非需要，否则不要使用此标志。

  注意，这不会使 fs.open() 进入同步阻塞调用。 如果那是你想要的，则应该使用 fs.openSync()。

• 'w' - 以写入模式打开文件。文件会被创建（如果文件不存在）或截断（如果文件存在）。

• 'wx' - 类似 'w'，但如果 path 存在，则失败。

• 'w+' - 以读写模式打开文件。文件会被创建（如果文件不存在）或截断（如果文件存在）。

• 'wx+' - 类似 'w+'，但如果 path 存在，则失败。

• 'a' - 以追加模式打开文件。如果文件不存在，则会被创建。

• 'ax' - 类似于 'a'，但如果 path 存在，则失败。

• 'a+' - 以读取和追加模式打开文件。如果文件不存在，则会被创建。

• 'ax+' - 类似于 'a+'，但如果 path 存在，则失败。

mode 可设置文件模式（权限和 sticky 位），但只有当文件被创建时才有效。默认为 0o666，可读写。

该回调有两个参数 (err, fd)。

特有的标志 'x'（在 open(2) 中的 O_EXCL 标志）确保 path 是新创建的。 在 POSIX 操作系统中，path 会被视为存在，即使是一个链接到一个不存在的文件的符号。 该特有的标志有可能在网络文件系统中无法使用。

flags 也可以是一个数字，[open(2)] 文档中有描述； 常用的常量可从 fs.constants 获取。 在 Windows 系统中，标志会被转换为与它等同的替代者，例如，O_WRONLY 转换为 FILE_GENERIC_WRITE、或 O_EXCL|O_CREAT 转换为 CREATE_NEW，通过 CreateFileW 接受。

在 Linux 中，当文件以追加模式打开时，定位的写入不起作用。 内核会忽略位置参数，并总是附加数据到文件的末尾。

注意：fs.open() 某些标志的行为是与平台相关的。 因此，在 macOS 和 Linux 下用 'a+' 标志打开一个目录（见下面的例子），会返回一个错误。 与此相反，在 Windows 和 FreeBSD，则会返回一个文件描述符。

// macOS 与 Linux
fs.open('<directory>', 'a+', (err, fd) => {
  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
});

// Windows 与 FreeBSD
fs.open('<directory>', 'a+', (err, fd) => {
  // => null, <fd>
});

有些字符 (< > : " / \ | ? *) 在Windows下保留，通过命名文件、路径和命名空间来记录。 在NTFS下，如果文件名包含冒号，Node.js 将打开一个文件系统流， 具体描述在 MSDN页。

许多函数也是基于 fs.open() 拥有这样的效果。例: fs.writeFile(), fs.readFile(), 等。

fs.openSync(path, flags[, mode])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• flags <string> | <number>
• mode <integer> Default: 0o666

fs.open() 的同步版本。 返回一个表示文件描述符的整数。

fs.read(fd, buffer, offset, length, position, callback)#

查看英文版参与翻译

• fd <integer>
• buffer <Buffer> | <Uint8Array>
• offset <integer>
• length <integer>
• position <integer>

• callback <Function>

  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

从 fd 指定的文件中读取数据。

buffer 是数据将被写入到的 buffer。

offset 是 buffer 中开始写入的偏移量。

length 是一个整数，指定要读取的字节数。

position 指定从文件中开始读取的位置。 如果 position 为 null，则数据从当前文件读取位置开始读取，且文件读取位置会被更新。 如果 position 为一个整数，则文件读取位置保持不变。

回调有三个参数 (err, bytesRead, buffer)。

如果调用该方法的 util.promisify() 版本，将会返回一个包含 bytesRead 和 buffer 属性的 Promise。

fs.readdir(path[, options], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

• callback <Function>

  • err <Error>
  • files <string[]> | <Buffer[]>

异步的 readdir(3)。 读取一个目录的内容。 回调有两个参数 (err, files)，其中 files 是目录中不包括 '.' 和 '..' 的文件名的数组。

可选的 options 参数用于传入回调的文件名，它可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。 如果 encoding 设为 'buffer'，则返回的文件名会被作为 Buffer 对象传入。 注意: 'path' 的路径是以当前文件为基准进行查找的,而不是运行的时候的相对路径

fs.readdirSync(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

同步的 readdir(3). 返回一个不包括 '.' 和 '..' 的文件名的数组。

可选的 options 参数用于传入回调的文件名，它可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。 如果 encoding 设为 'buffer'，则返回的文件名会被作为 Buffer 对象传入。

fs.readFile(path[, options], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL> | <integer> 文件名或文件描述符。

• options <Object> | <string>

  • encoding <string> | <null> 默认为 null。
  • flag <string> 详见支持的文件系统flag。默认为 'r'。

• callback <Function>

  • err <Error>
  • data <string> | <Buffer>

异步地读取一个文件的全部内容。 例子：

fs.readFile('/etc/passwd', (err, data) => {
  if (err) throw err;
  console.log(data);
});

回调有两个参数 (err, data)，其中 data 是文件的内容。

如果未指定字符编码，则返回原始的 buffer。

如果 options 是一个字符串，则它指定了字符编码。 例子：

fs.readFile('/etc/passwd', 'utf8', callback);

当 path 是一个目录时，fs.readFile() 与 fs.readFileSync() 的行为与平台有关。 在 macOS、Linux 与 Windows 上，会返回一个错误。 在 FreeBSD 上，会返回目录内容的描述。

// 在 macOS、Linux 与 Windows 上：
fs.readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: illegal operation on a directory, read <directory>]
});

// 在 FreeBSD 上：
fs.readFile('<directory>', (err, data) => {
  // => null, <data>
});

任何指定的文件描述符必须支持读取。

如果 path 是一个文件描述符，则它不会被自动关闭。

fs.readFile() 函数会缓存整个文件。 为了最小化内存占用，尽可能优先使用 fs.createReadStream()。

fs.readFileSync(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL> | <integer> 文件名或文件描述符。

• options <Object> | <string>

  • encoding <string> | <null> 默认为 null。
  • flag <string> 详见支持的文件系统flag。默认为 'r'。
• 返回: <string> | <Buffer>

返回 path 的内容。

详见同步版本的 API 文档：fs.readFile()。

如果指定了 encoding 选项，则该函数返回一个字符串，否则返回一个 buffer。

与 fs.readFile() 相似, 当路径是一个目录时，fs.readFileSync() 的行为与平台有关。

// 在 macOS、Linux 与 Windows 上：
fs.readFileSync('<directory>');
// => [Error: EISDIR: illegal operation on a directory, read <directory>]

// 在 FreeBSD 上：
fs.readFileSync('<directory>'); // => <data>

fs.readlink(path[, options], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

• callback <Function>

  • err <Error>
  • linkString <string> | <Buffer>

异步的 readlink(2)。 回调有两个参数 (err, linkString)。

可选的 options 参数用于传入回调的链接路径，它可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。 如果 encoding 设为 'buffer'，则返回的链接路径会被作为 Buffer 对象传入。

fs.readlinkSync(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

同步的 readlink(2)。 返回符号链接的字符串值。

可选的 options 参数用于传入回调的链接路径，它可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。 如果 encoding 设为 'buffer'，则返回的链接路径会被作为 Buffer 对象传入。

fs.readSync(fd, buffer, offset, length, position)#

查看英文版参与翻译

• fd <integer>
• buffer <Buffer> | <Uint8Array>
• offset <integer>
• length <integer>
• position <integer>

fs.read() 的同步版本。 返回 bytesRead 的数量。

fs.realpath(path[, options], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

异步的 realpath(3)。 callback 有两个参数 (err, resolvedPath)。 可以使用 process.cwd 解析相对路径。

只支持可转换成 UTF8 字符串的路径。

可选的 options 参数用于传入回调的路径，它可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。 如果 encoding 设为 'buffer'，则返回的路径会被作为 Buffer 对象传入。

注意: 如果路径解析到套接字或 pipe ，函数将返回与该对象相关的系统名称。

fs.realpath.native(path[, options], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Default: 'utf8'

• callback <Function>

  • err <Error>
  • resolvedPath <string> | <Buffer>

Asynchronous realpath(3).

The callback gets two arguments (err, resolvedPath).

Only paths that can be converted to UTF8 strings are supported.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the path passed to the callback. If the encoding is set to 'buffer', the path returned will be passed as a Buffer object.

On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on /proc in order for this function to work. Glibc does not have this restriction.

fs.realpathSync(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> 默认 = 'utf8'

同步的 realpath(3)。 返回解析的路径。

只支持可转换成 UTF8 字符串的路径。

可选的 options 参数用于传入回调的路径，它可以是一个字符串并指定一个字符编码，或是一个对象且由一个 encoding 属性指定使用的字符编码。 如果 encoding 设为 'buffer'，则返回的路径会被作为 Buffer 对象传入。

注意: 如果 path 解析成一个 socket 或者管道，该函数将返回包含系统相关名称的对象。

fs.realpathSync.native(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Default: 'utf8'
• Returns: <string> | <Buffer>

Synchronous realpath(3).

Only paths that can be converted to UTF8 strings are supported.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the path returned. If the encoding is set to 'buffer', the path returned will be passed as a Buffer object.

On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on /proc in order for this function to work. Glibc does not have this restriction.

fs.rename(oldPath, newPath, callback)#

查看英文版参与翻译

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

• callback <Function>

  • err <Error>

异步的 rename(2)。 完成回调只有一个可能的异常参数。

fs.renameSync(oldPath, newPath)#

查看英文版参与翻译

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>

同步的 rename(2)。返回 undefined。

fs.rmdir(path, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• callback <Function>

  • err <Error>

异步的 rmdir(2)。 完成回调只有一个可能的异常参数。

请注意: 在文件上（而不是目录上）使用fs.rmdir()，在Windows平台将会导致ENOENT错误，而在POSIX平台将会导致ENOTDIR错误。

fs.rmdirSync(path)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

同步的 rmdir(2)。返回 undefined。

请注意: 在文件上（而不是目录上）使用fs.rmdirSync()，在Windows平台将会导致ENOENT错误，而在POSIX平台将会导致ENOTDIR错误。

fs.stat(path[, options], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.

• callback <Function>

  • err <Error>
  • stats <fs.Stats>

Asynchronous stat(2). The callback gets two arguments (err, stats) where stats is an fs.Stats object.

In case of an error, the err.code will be one of Common System Errors.

Using fs.stat() to check for the existence of a file before calling fs.open(), fs.readFile() or fs.writeFile() is not recommended. Instead, user code should open/read/write the file directly and handle the error raised if the file is not available.

To check if a file exists without manipulating it afterwards, fs.access() is recommended.

fs.statSync(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.
• Returns: <fs.Stats>

Synchronous stat(2).

fs.symlink(target, path[, type], callback)#

查看英文版参与翻译

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> Default: 'file'

• callback <Function>

  • err <Error>

异步的 symlink(2)。 完成回调只有一个可能的异常参数。 type 参数可以设为 'dir'、'file' 或 'junction'（默认为 'file'），且仅在 Windows 上有效（在其他平台上忽略）。 注意，Windows 结点要求目标路径是绝对的。 当使用 'junction' 时，target 参数会被自动标准化为绝对路径。

例子：

fs.symlink('./foo', './new-port', callback);

它创建了一个名为 "new-port" 且指向 "foo" 的符号链接。

fs.symlinkSync(target, path[, type])#

查看英文版参与翻译

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> 默认值: 'file'

同步的 symlink(2)。返回 undefined。

fs.truncate(path[, len], callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• len <integer> 默认 = 0

• callback <Function>

  • err <Error>

异步的 truncate(2)。 完成回调只有一个可能的异常参数。 文件描述符也可以作为第一个参数传入，在这种情况下fs.ftruncate() 会被调用。

fs.truncateSync(path[, len])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• len <integer> 默认 = 0

同步的 truncate(2)。 返回 undefined。 文件描述符也可以作为第一个参数传入，在这种情况下，fs.ftruncateSync() 会被调用。

fs.unlink(path, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• callback <Function>

  • err <Error>

异步的 unlink(2)。 完成回调只有一个可能的异常参数。

fs.unlinkSync(path)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

同步的 unlink(2)。返回 undefined。

fs.unwatchFile(filename[, listener])#

查看英文版参与翻译

• filename <string> | <Buffer> | <URL>
• listener <Function> Optional, a listener previously attached using fs.watchFile()

停止监视 filename 文件的变化。 如果指定了 listener，则只移除特定的监听器。 否则，所有的监听器都会被移除，且已经有效地停止监视 filename。

调用 fs.unwatchFile() 且带上一个未被监视的文件名，将会是一个空操作，而不是一个错误。

注意：fs.watch() 比 fs.watchFile() 和 fs.unwatchFile() 更高效。 可能的话，应该使用 fs.watch() 而不是 fs.watchFile() 和 fs.unwatchFile()。

fs.utimes(path, atime, mtime, callback)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>

• callback <Function>

  • err <Error>

改变 path 所指向的对象的文件系统时间戳。

atime 参数和 mtime 参数遵循以下规则：

• 值可以是 Unix 时间戳数值、Date 对象、或数值字符串如 '123456789.0'。
• 如果值不能被转换为数值，或值是 NaN 、 Infinity 或 -Infinity，则会抛出错误。

fs.utimesSync(path, atime, mtime)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• atime <integer>
• mtime <integer>

fs.utimes() 的同步版本。返回 undefined。

fs.watch(filename[, options][, listener])#

查看英文版参与翻译

• filename <string> | <Buffer> | <URL>

• options <string> | <Object>

  • persistent <boolean> 指明如果文件正在被监视，进程是否应该继续运行。默认 = true
  • recursive <boolean> 指明是否全部子目录应该被监视，或只是当前目录。 适用于当一个目录被指定时，且只在支持的平台（详见 Caveats）。默认 = false
  • encoding <string> 指定用于传给监听器的文件名的字符编码。默认 = 'utf8'

• listener <Function> | <undefined> Default: undefined

  • eventType <string>
  • filename <string> | <Buffer>

监视 filename 的变化，filename 可以是一个文件或一个目录。 返回的对象是一个 fs.FSWatcher。

第二个参数是可选的。 如果提供的 options 是一个字符串，则它指定了 encoding。 否则 options 应该以一个对象传入。

监听器回调有两个参数 (eventType, filename)。 eventType 可以是 'rename' 或 'change'，filename 是触发事件的文件的名称。

注意，在大多数平台，当一个文件出现或消失在一个目录里时，'rename' 会被触发。

还需要注意，监听器回调是绑定在由 fs.FSWatcher 触发的 'change' 事件上，但它跟 eventType 的 'change' 值不是同一个东西。

说明#

查看英文版参与翻译

fs.watch API 不是 100％ 跨平台一致的，且在某些情况下不可用。

递归选项只支持 macOS 和 Windows。

可用性#

查看英文版参与翻译

该特性依赖于底层操作系统提供的一种方法来通知文件系统的变化。

• 在 Linux 系统中，使用 [inotify]。
• 在 BSD 系统中，使用 [kqueue]。
• 在 macOS 系统中，对文件使用 [kqueue]，对目录使用 FSEvents。
• 在 SunOS 系统（包括 Solaris 和 SmartOS）中，使用 event ports。
• 在 Windows 系统中，该特性依赖 ReadDirectoryChangesW。
• 在 Aix 系统中，该特性依赖 AHAFS 必须是启动的。

如果底层功能因某些原因不可用，则 fs.watch 也无法正常工作。 例如，当使用虚拟化软件如 Vagrant、Docker 等时，在网络文件系统（NFS、SMB 等）或主文件系统中监视文件或目录可能是不可靠的。

您仍然可以使用基于stat轮询的fs.watchFile()，但是这种方法更慢，可靠性也更低。

索引节点#

查看英文版参与翻译

在 Linux 或 macOS 系统中，fs.watch() 解析路径到一个索引节点，并监视该索引节点。 如果监视的路径被删除或重建，则它会被分配一个新的索引节点。 监视器会发出一个删除事件，但会继续监视原始的索引节点。 新建的索引节点的事件不会被触发。 这是正常的行为。

AIX 文件在文件的生命周期中保留相同的 inode。在 AIX 上保存并关闭监视的文件将触发两个通知（一个用于添加新内容，一共用于拦截）。

文件名参数#

查看英文版参与翻译

回调中提供的 filename 参数仅在 Linux、macOS、Windows、以及 AIX 系统上支持。 即使在支持的平台中，filename 也不能保证提供。 因此，不要以为 filename 参数总是在回调中提供，如果它是空的，需要有一定的后备逻辑。

fs.watch('somedir', (eventType, filename) => {
  console.log(`事件类型是: ${eventType}`);
  if (filename) {
    console.log(`提供的文件名: ${filename}`);
  } else {
    console.log('未提供文件名');
  }
});

fs.watchFile(filename[, options], listener)#

查看英文版参与翻译

• filename <string> | <Buffer> | <URL>

• options <Object>

  • persistent <boolean> Default: true
  • interval <integer> Default: 5007

• listener <Function>

  • current <fs.Stats>
  • previous <fs.Stats>

监视 filename 的变化。 回调 listener 会在每次访问文件时被调用。

options 参数可被省略。 如果提供的话，它应该是一个对象。 options 对象可能包含一个名为 persistent 的布尔值，表明当文件正在被监视时，进程是否应该继续运行。 options 对象可以指定一个 interval 属性，表示目标应该每隔多少毫秒被轮询。 默认值为 { persistent: true, interval: 5007 }。

listener 有两个参数，当前的状态对象和以前的状态对象：

fs.watchFile('message.text', (curr, prev) => {
  console.log(`the current mtime is: ${curr.mtime}`);
  console.log(`the previous mtime was: ${prev.mtime}`);
});

这里的状态对象是 fs.Stat 实例。

如果你想在文件被修改而不只是访问时得到通知，则需要比较 curr.mtime 和 prev.mtime。

注意：当一个 fs.watchFile 的运行结果是一个 ENOENT 错误时，它会调用监听器一次，且将所有字段置零（或将日期设为 Unix 纪元）。 在 Windows 中，blksize 和 blocks 字段会是 undefined 而不是零。 如果文件是在那之后创建的，则监听器会被再次调用，且带上最新的状态对象。 这是在 v0.10 版之后在功能上的变化。

注意：fs.watch() 比 fs.watchFile 和 fs.unwatchFile 更高效。 可能的话，应该使用 fs.watch 而不是 fs.watchFile 和 fs.unwatchFile。

注意: 当 fs.watchFile() 所监听的文件消失并重新出现时，第二个回调函数中返回的 previousstat (文件重新出现)将与第一个回调函数的 previousstat (消失)相同。

这种情况会发生在:

• 该文件被删除，然后又恢复
• 文件重命名两次 - 第二次重命名与其原名称相同

fs.write(fd, buffer[, offset[, length[, position]]], callback)#

查看英文版参与翻译

• fd <integer>
• buffer <Buffer> | <Uint8Array>
• offset <integer>
• length <integer>
• position <integer>

• callback <Function>

  • err <Error>
  • bytesWritten <integer>
  • buffer <Buffer> | <Uint8Array>

写入 buffer 到 fd 指定的文件。

offset 决定 buffer 中被写入的部分，length 是一个整数，指定要写入的字节数。

position 指向从文件开始写入数据的位置的偏移量。 如果 typeof position !== 'number'，则数据从当前位置写入。详见 pwrite(2)。

回调有三个参数 (err, bytesWritten, buffer)，其中 bytesWritten 指定从 buffer 写入了多少字节。

如果以 util.promisify() 的形式调用该方法，则会返回包含 bytesWritten 和 buffer 属性的 Promise 的对象。

注意，多次对同一文件使用 fs.write 且不等待回调，是不安全的。 对于这种情况，强烈推荐使用 fs.createWriteStream。

在 Linux 上，当文件以追加模式打开时，指定位置的写入是不起作用的。 内核会忽略位置参数，并总是将数据追加到文件的末尾。

fs.write(fd, string[, position[, encoding]], callback)#

查看英文版参与翻译

• fd <integer>
• string <string>
• position <integer>
• encoding <string>

• callback <Function>

  • err <Error>
  • written <integer>
  • string <string>

写入 string 到 fd 指定的文件。 如果 string 不是一个字符串，则该值将被强制转换为一个字符串。

position 指向从文件开始写入数据的位置的偏移量。 如果 typeof position !== 'number'，则数据从当前位置写入。详见 pwrite(2)。

encoding 是期望的字符串编码。

回调有三个参数 (err, written, string)，其中 written 指定传入的字符串被写入多少字节。 注意，写入的字节与字符串的字符是不同的。详见 Buffer.byteLength。

不同于写入 buffer，该方法整个字符串必须被写入。 不能指定子字符串。 这是因为结果数据的字节偏移量可能与字符串的偏移量不同。

注意，多次对同一文件使用 fs.write 且不等待回调，是不安全的。 对于这种情况，强烈推荐使用 fs.createWriteStream。

在 Linux 上，当文件以追加模式打开时，指定位置的写入是不起作用的。 内核会忽略位置参数，并总是将数据追加到文件的末尾。

fs.writeFile(file, data[, options], callback)#

查看英文版参与翻译

• file <string> | <Buffer> | <URL> | <integer> 文件名或文件描述符。
• data <string> | <Buffer> | <Uint8Array>

• options <Object> | <string>

  • encoding <string> | <null> 默认为 'utf8'。
  • mode <integer> 默认为 0o666。
  • flag <string> 详见支持的文件系统flag。默认为 'w'。

• callback <Function>

  • err <Error>

异步地写入数据到文件，如果文件已经存在，则覆盖文件。 data 可以是字符串或 buffer。

如果 data 是一个 buffer，则 encoding 选项无效。

例子：

fs.writeFile('文件名.txt', 'Node.js 中文网', (err) => {
  if (err) throw err;
  console.log('文件已保存！');
});

如果 options 是一个字符串，则它指定了字符编码。例子：

fs.writeFile('文件名.txt', 'Node.js 中文网', 'utf8', callback);

任何指定的文件描述符必须支持写入。

对同一文件多次使用 fs.writeFile 且不等待回调，是不安全的。 对于这种情况，建议使用 fs.createWriteStream。

如果 file 是一个文件描述符，则它不会被自动关闭。

fs.writeFileSync(file, data[, options])#

查看英文版参与翻译

• file <string> | <Buffer> | <URL> | <integer> 文件名或文件描述符。
• data <string> | <Buffer> | <Uint8Array>

• options <Object> | <string>

  • encoding <string> | <null> 默认为 'utf8'。
  • mode <integer> 默认为 0o666。
  • flag <string> 详见支持的文件系统flag。默认为 'w'。

返回 undefined。

详见同步版本的 API 文档：fs.writeFile()。

fs.writeSync(fd, buffer[, offset[, length[, position]]])#

查看英文版参与翻译

• fd <integer>
• buffer <Buffer> | <Uint8Array>
• offset <integer>
• length <integer>
• position <integer>
• Returns: <number>

fs.writeSync(fd, string[, position[, encoding]])#

查看英文版参与翻译

• fd <integer>
• string <string>
• position <integer>
• encoding <string>

fs.write() 的同步版本。返回写入的字节数。

fs Promises API#

查看英文版参与翻译

The fs.promises API provides an alternative set of asynchronous file system methods that return Promise objects rather than using callbacks. The API is accessible via require('fs').promises.

class: FileHandle#

查看英文版参与翻译

A FileHandle object is a wrapper for a numeric file descriptor. Instances of FileHandle are distinct from numeric file descriptors in that, if the FileHandle is not explicitly closed using the filehandle.close() method, they will automatically close the file descriptor and will emit a process warning, thereby helping to prevent memory leaks.

Instances of the FileHandle object are created internally by the fsPromises.open() method.

Unlike the callback-based API (fs.fstat(), fs.fchown(), fs.fchmod(), and so on), a numeric file descriptor is not used by the promise-based API. Instead, the promise-based API uses the FileHandle class in order to help avoid accidental leaking of unclosed file descriptors after a Promise is resolved or rejected.

filehandle.appendFile(data, options)#

查看英文版参与翻译

• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Default: 'utf8'
  • mode <integer> Default: 0o666
  • flag <string> See support of file system flags. Default: 'a'.
• Returns: <Promise>

Asynchronously append data to this file, creating the file if it does not yet exist. data can be a string or a Buffer. The Promise will be resolved with no arguments upon success.

If options is a string, then it specifies the encoding.

The FileHandle must have been opened for appending.

filehandle.chmod(mode)#

查看英文版参与翻译

• mode <integer>
• Returns: <Promise>

Modifies the permissions on the file. The Promise is resolved with no arguments upon success.

filehandle.chown(uid, gid)#

查看英文版参与翻译

• uid <integer>
• gid <integer>
• Returns: <Promise>

Changes the ownership of the file then resolves the Promise with no arguments upon success.

filehandle.close()#

查看英文版参与翻译

• Returns: <Promise> A Promise that will be resolved once the underlying file descriptor is closed, or will be rejected if an error occurs while closing.

Closes the file descriptor.

const fsPromises = require('fs').promises;
async function openAndClose() {
  let filehandle;
  try {
    filehandle = await fsPromises.open('thefile.txt', 'r');
  } finally {
    if (filehandle !== undefined)
      await filehandle.close();
  }
}

filehandle.datasync()#

查看英文版参与翻译

• Returns: <Promise>

Asynchronous fdatasync(2). The Promise is resolved with no arguments upon success.

filehandle.fd#

查看英文版参与翻译

• <number> The numeric file descriptor managed by the FileHandle object.

filehandle.read(buffer, offset, length, position)#

查看英文版参与翻译

• buffer <Buffer> | <Uint8Array>
• offset <integer>
• length <integer>
• position <integer>
• Returns: <Promise>

Read data from the file.

buffer is the buffer that the data will be written to.

offset is the offset in the buffer to start writing at.

length is an integer specifying the number of bytes to read.

position is an argument specifying where to begin reading from in the file. If position is null, data will be read from the current file position, and the file position will be updated. If position is an integer, the file position will remain unchanged.

Following successful read, the Promise is resolved with an object with a bytesRead property specifying the number of bytes read, and a buffer property that is a reference to the passed in buffer argument.

filehandle.readFile(options)#

查看英文版参与翻译

• options <Object> | <string>

  • encoding <string> | <null> Default: null
  • flag <string> See support of file system flags. Default: 'r'.
• Returns: <Promise>

Asynchronously reads the entire contents of a file.

The Promise is resolved with the contents of the file. If no encoding is specified (using options.encoding), the data is returned as a Buffer object. Otherwise, the data will be a string.

If options is a string, then it specifies the encoding.

When the path is a directory, the behavior of fsPromises.readFile() is platform-specific. On macOS, Linux, and Windows, the promise will be rejected with an error. On FreeBSD, a representation of the directory's contents will be returned.

The FileHandle has to support reading.

filehandle.stat([options])#

查看英文版参与翻译

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.
• Returns: <Promise>

Retrieves the fs.Stats for the file.

filehandle.sync()#

查看英文版参与翻译

• Returns: <Promise>

Asynchronous fsync(2). The Promise is resolved with no arguments upon success.

filehandle.truncate(len)#

查看英文版参与翻译

• len <integer> Default: 0
• Returns: <Promise>

Truncates the file then resolves the Promise with no arguments upon success.

If the file was larger than len bytes, only the first len bytes will be retained in the file.

For example, the following program retains only the first four bytes of the file:

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(4);
  } finally {
    if (filehandle) {
      // close the file if it is opened.
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints: Node
}

doTruncate().catch(console.error);

If the file previously was shorter than len bytes, it is extended, and the extended part is filled with null bytes ('\0'). For example,

const fs = require('fs');
const fsPromises = fs.promises;

console.log(fs.readFileSync('temp.txt', 'utf8'));
// Prints: Node.js

async function doTruncate() {
  let filehandle = null;
  try {
    filehandle = await fsPromises.open('temp.txt', 'r+');
    await filehandle.truncate(10);
  } finally {
    if (filehandle) {
      // close the file if it is opened.
      await filehandle.close();
    }
  }
  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints Node.js\0\0\0
}

doTruncate().catch(console.error);

The last three bytes are null bytes ('\0'), to compensate the over-truncation.

filehandle.utimes(atime, mtime)#

查看英文版参与翻译

• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Returns: <Promise>

Change the file system timestamps of the object referenced by the FileHandle then resolves the Promise with no arguments upon success.

This function does not work on AIX versions before 7.1, it will resolve the Promise with an error using code UV_ENOSYS.

filehandle.write(buffer, offset, length, position)#

查看英文版参与翻译

• buffer <Buffer> | <Uint8Array>
• offset <integer>
• length <integer>
• position <integer>
• Returns: <Promise>

Write buffer to the file.

The Promise is resolved with an object containing a bytesWritten property identifying the number of bytes written, and a buffer property containing a reference to the buffer written.

offset determines the part of the buffer to be written, and length is an integer specifying the number of bytes to write.

position refers to the offset from the beginning of the file where this data should be written. If typeof position !== 'number', the data will be written at the current position. See pwrite(2).

It is unsafe to use filehandle.write() multiple times on the same file without waiting for the Promise to be resolved (or rejected). For this scenario, fs.createWriteStream is strongly recommended.

On Linux, positional writes do not work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.

filehandle.writeFile(data, options)#

查看英文版参与翻译

• data <string> | <Buffer> | <Uint8Array>

• options <Object> | <string>

  • encoding <string> | <null> Default: 'utf8'
  • mode <integer> Default: 0o666
  • flag <string> See support of file system flags. Default: 'w'.
• Returns: <Promise>

Asynchronously writes data to a file, replacing the file if it already exists. data can be a string or a buffer. The Promise will be resolved with no arguments upon success.

The encoding option is ignored if data is a buffer.

If options is a string, then it specifies the encoding.

The FileHandle has to support writing.

It is unsafe to use filehandle.writeFile() multiple times on the same file without waiting for the Promise to be resolved (or rejected).

fsPromises.access(path[, mode])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer> Default: fs.constants.F_OK
• Returns: <Promise>

Tests a user's permissions for the file or directory specified by path. The mode argument is an optional integer that specifies the accessibility checks to be performed. Check File Access Constants for possible values of mode. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. fs.constants.W_OK | fs.constants.R_OK).

If the accessibility check is successful, the Promise is resolved with no value. If any of the accessibility checks fail, the Promise is rejected with an Error object. The following example checks if the file /etc/passwd can be read and written by the current process.

const fs = require('fs');
const fsPromises = fs.promises;

fsPromises.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK)
  .then(() => console.log('can access'))
  .catch(() => console.error('cannot access'));

Using fsPromises.access() to check for the accessibility of a file before calling fsPromises.open() is not recommended. Doing so introduces a race condition, since other processes may change the file's state between the two calls. Instead, user code should open/read/write the file directly and handle the error raised if the file is not accessible.

fsPromises.appendFile(path, data[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL> | <FileHandle> filename or FileHandle
• data <string> | <Buffer>

• options <Object> | <string>

  • encoding <string> | <null> Default: 'utf8'
  • mode <integer> Default: 0o666
  • flag <string> See support of file system flags. Default: 'a'.
• Returns: <Promise>

Asynchronously append data to a file, creating the file if it does not yet exist. data can be a string or a Buffer. The Promise will be resolved with no arguments upon success.

If options is a string, then it specifies the encoding.

The path may be specified as a FileHandle that has been opened for appending (using fsPromises.open()).

fsPromises.chmod(path, mode)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer>
• Returns: <Promise>

Changes the permissions of a file then resolves the Promise with no arguments upon succces.

fsPromises.chown(path, uid, gid)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Returns: <Promise>

Changes the ownership of a file then resolves the Promise with no arguments upon success.

fsPromises.copyFile(src, dest[, flags])#

查看英文版参与翻译

• src <string> | <Buffer> | <URL> source filename to copy
• dest <string> | <Buffer> | <URL> destination filename of the copy operation
• flags <number> modifiers for copy operation. Default: 0.
• Returns: <Promise>

Asynchronously copies src to dest. By default, dest is overwritten if it already exists. The Promise will be resolved with no arguments upon success.

Node.js makes no guarantees about the atomicity of the copy operation. If an error occurs after the destination file has been opened for writing, Node.js will attempt to remove the destination.

flags is an optional integer that specifies the behavior of the copy operation. It is possible to create a mask consisting of the bitwise OR of two or more values (e.g. fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE).

• fs.constants.COPYFILE_EXCL - The copy operation will fail if dest already exists.
• fs.constants.COPYFILE_FICLONE - The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then a fallback copy mechanism is used.
• fs.constants.COPYFILE_FICLONE_FORCE - The copy operation will attempt to create a copy-on-write reflink. If the platform does not support copy-on-write, then the operation will fail.

Example:

const fsPromises = require('fs').promises;

// destination.txt will be created or overwritten by default.
fsPromises.copyFile('source.txt', 'destination.txt')
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

If the third argument is a number, then it specifies flags, as shown in the following example.

const fs = require('fs');
const fsPromises = fs.promises;
const { COPYFILE_EXCL } = fs.constants;

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL)
  .then(() => console.log('source.txt was copied to destination.txt'))
  .catch(() => console.log('The file could not be copied'));

fsPromises.lchmod(path, mode)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer>
• Returns: <Promise>

Changes the permissions on a symbolic link then resolves the Promise with no arguments upon success. This method is only implemented on macOS.

fsPromises.lchown(path, uid, gid)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• Returns: <Promise>

Changes the ownership on a symbolic link then resolves the Promise with no arguments upon success.

fsPromises.link(existingPath, newPath)#

查看英文版参与翻译

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Returns: <Promise>

Asynchronous link(2). The Promise is resolved with no arguments upon success.

fsPromises.lstat(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.
• Returns: <Promise>

Asynchronous lstat(2). The Promise is resolved with the fs.Stats object for the given symbolic link path.

fsPromises.mkdir(path[, mode])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• mode <integer> Default: 0o777
• Returns: <Promise>

Asynchronously creates a directory then resolves the Promise with no arguments upon success.

fsPromises.mkdtemp(prefix[, options])#

查看英文版参与翻译

• prefix <string>

• options <string> | <Object>

  • encoding <string> Default: 'utf8'
• Returns: <Promise>

Creates a unique temporary directory and resolves the Promise with the created folder path. A unique directory name is generated by appending six random characters to the end of the provided prefix.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use.

fsPromises.mkdtemp(path.join(os.tmpdir(), 'foo-'))
  .catch(console.error);

The fsPromises.mkdtemp() method will append the six randomly selected characters directly to the prefix string. For instance, given a directory /tmp, if the intention is to create a temporary directory within /tmp, the prefix must end with a trailing platform-specific path separator (require('path').sep).

fsPromises.open(path, flags[, mode])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• flags <string> | <number> See support of file system flags.
• mode <integer> Default: 0o666 (readable and writable)
• Returns: <Promise>

Asynchronous file open that returns a Promise that, when resolved, yields a FileHandle object. See open(2).

mode sets the file mode (permission and sticky bits), but only if the file was created.

Some characters (< > : " / \ | ? *) are reserved under Windows as documented by Naming Files, Paths, and Namespaces. Under NTFS, if the filename contains a colon, Node.js will open a file system stream, as described by this MSDN page.

fsPromises.readdir(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Default: 'utf8'
• Returns: <Promise>

Reads the contents of a directory then resolves the Promise with an array of the names of the files in the directory excluding '.' and '..'.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the filenames. If the encoding is set to 'buffer', the filenames returned will be passed as Buffer objects.

fsPromises.readFile(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL> | <FileHandle> filename or FileHandle

• options <Object> | <string>

  • encoding <string> | <null> Default: null
  • flag <string> See support of file system flags. Default: 'r'.
• Returns: <Promise>

Asynchronously reads the entire contents of a file.

The Promise is resolved with the contents of the file. If no encoding is specified (using options.encoding), the data is returned as a Buffer object. Otherwise, the data will be a string.

If options is a string, then it specifies the encoding.

When the path is a directory, the behavior of fsPromises.readFile() is platform-specific. On macOS, Linux, and Windows, the promise will be rejected with an error. On FreeBSD, a representation of the directory's contents will be returned.

Any specified FileHandle has to support reading.

fsPromises.readlink(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Default: 'utf8'
• Returns: <Promise>

Asynchronous readlink(2). The Promise is resolved with the linkString upon success.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the link path returned. If the encoding is set to 'buffer', the link path returned will be passed as a Buffer object.

fsPromises.realpath(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <string> | <Object>

  • encoding <string> Default: 'utf8'
• Returns: <Promise>

Determines the actual location of path using the same semantics as the fs.realpath.native() function then resolves the Promise with the resolved path.

Only paths that can be converted to UTF8 strings are supported.

The optional options argument can be a string specifying an encoding, or an object with an encoding property specifying the character encoding to use for the path. If the encoding is set to 'buffer', the path returned will be passed as a Buffer object.

On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on /proc in order for this function to work. Glibc does not have this restriction.

fsPromises.rename(oldPath, newPath)#

查看英文版参与翻译

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• Returns: <Promise>

Renames oldPath to newPath and resolves the Promise with no arguments upon success.

fsPromises.rmdir(path)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• Returns: <Promise>

Removes the directory identified by path then resolves the Promise with no arguments upon success.

Using fsPromises.rmdir() on a file (not a directory) results in the Promise being rejected with an ENOENT error on Windows and an ENOTDIR error on POSIX.

fsPromises.stat(path[, options])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>

• options <Object>

  • bigint <boolean> Whether the numeric values in the returned fs.Stats object should be bigint. Default: false.
• Returns: <Promise>

The Promise is resolved with the fs.Stats object for the given path.

fsPromises.symlink(target, path[, type])#

查看英文版参与翻译

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> Default: 'file'
• Returns: <Promise>

Creates a symbolic link then resolves the Promise with no arguments upon success.

The type argument is only used on Windows platforms and can be one of 'dir', 'file', or 'junction'. Windows junction points require the destination path to be absolute. When using 'junction', the target argument will automatically be normalized to absolute path.

fsPromises.truncate(path[, len])#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• len <integer> Default: 0
• Returns: <Promise>

Truncates the path then resolves the Promise with no arguments upon success. The path must be a string or Buffer.

fsPromises.unlink(path)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• Returns: <Promise>

Asynchronous unlink(2). The Promise is resolved with no arguments upon success.

fsPromises.utimes(path, atime, mtime)#

查看英文版参与翻译

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• Returns: <Promise>

Change the file system timestamps of the object referenced by path then resolves the Promise with no arguments upon success.

The atime and mtime arguments follow these rules:

• Values can be either numbers representing Unix epoch time, Dates, or a numeric string like '123456789.0'.
• If the value can not be converted to a number, or is NaN, Infinity or -Infinity, an Error will be thrown.

fsPromises.writeFile(file, data[, options])#

查看英文版参与翻译

• file <string> | <Buffer> | <URL> | <FileHandle> filename or FileHandle
• data <string> | <Buffer> | <Uint8Array>

• options <Object> | <string>

  • encoding <string> | <null> Default: 'utf8'
  • mode <integer> Default: 0o666
  • flag <string> See support of file system flags. Default: 'w'.
• Returns: <Promise>

Asynchronously writes data to a file, replacing the file if it already exists. data can be a string or a buffer. The Promise will be resolved with no arguments upon success.

The encoding option is ignored if data is a buffer.

If options is a string, then it specifies the encoding.

Any specified FileHandle has to support writing.

It is unsafe to use fsPromises.writeFile() multiple times on the same file without waiting for the Promise to be resolved (or rejected).

fs 常量#

查看英文版参与翻译

以下常量由 fs.constants 输出。

注意：不是所有的常量在每一个操作系统上都是可用的。

文件访问常量#

查看英文版参与翻译

以下常量用于 fs.access()。

常量	描述
F_OK	该标志表明文件对于调用进程是可见的。
R_OK	该标志表明文件可被调用进程读取。
W_OK	该标志表明文件可被调用进程写入。
X_OK	该标志表明文件可被调用进程执行。

File Copy Constants#

查看英文版参与翻译

The following constants are meant for use with fs.copyFile().

Constant	Description
COPYFILE_EXCL	If present, the copy operation will fail with an error if the destination path already exists.
COPYFILE_FICLONE	If present, the copy operation will attempt to create a copy-on-write reflink. If the underlying platform does not support copy-on-write, then a fallback copy mechanism is used.
COPYFILE_FICLONE_FORCE	If present, the copy operation will attempt to create a copy-on-write reflink. If the underlying platform does not support copy-on-write, then the operation will fail with an error.

文件打开常量#

查看英文版参与翻译

以下常量用于 fs.open()。

常量	描述
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	该标志表明当可能时以非阻塞模式打开文件。

文件类型常量#

查看英文版参与翻译

以下常量用于 fs.Stats 对象中用于决定一个文件的类型的 mode 属性。

常量	描述
S_IFMT	用于提取文件类型码的位掩码。
S_IFREG	表示一个常规文件的文件类型常量。
S_IFDIR	表示一个目录的文件类型常量。
S_IFCHR	表示一个面向字符的设备文件的文件类型常量。
S_IFBLK	表示一个面向块的设备文件的文件类型常量。
S_IFIFO	表示一个 FIFO/pipe 的文件类型常量。
S_IFLNK	表示一个符号链接的文件类型常量。
S_IFSOCK	表示一个 socket 的文件类型常量。

文件模式常量#

查看英文版参与翻译

以下常量用于 fs.Stats 对象中用于决定一个文件访问权限的 mode 属性。

常量	描述
S_IRWXU	该文件模式表明可被所有者读取、写入、执行。
S_IRUSR	该文件模式表明可被所有者读取。
S_IWUSR	该文件模式表明可被所有者写入。
S_IXUSR	该文件模式表明可被所有者执行。
S_IRWXG	该文件模式表明可被群组读取、写入、执行。
S_IRGRP	该文件模式表明可被群组读取。
S_IWGRP	该文件模式表明可被群组写入。
S_IXGRP	该文件模式表明可被群组执行。
S_IRWXO	该文件模式表明可被其他人读取、写入、执行。
S_IROTH	该文件模式表明可被其他人读取。
S_IWOTH	该文件模式表明可被其他人写入。
S_IXOTH	该文件模式表明可被其他人执行。

文件系统 flag#

查看英文版参与翻译

以下 flag 用于接受字符串的 flag 选项：

• 'a' - 打开文件用于追加。如果文件不存在则创建文件。

• 'ax' - 类似 'a'，但如果文件存在则失败。

• 'a+' - 打开文件用于读取和追加。如果文件不存在则创建文件。

• 'ax+' - 类似 'a+'，但如果文件存在则失败。

• 'as' - 在同步模式中打开文件用于追加。如果文件不存在则创建文件。

• 'as+' - 在同步模式中打开文件用于读取和追加。如果文件不存在则创建文件。

• 'r' - 打开文件用于读取。如果文件不存在则抛出异常。

• 'r+' - 打开文件用于读取和写入。如果文件不存在则抛出异常。

• 'rs+' - 在同步模式中打开文件用于读取和写入。指示操作系统绕开本地文件系统缓存。

  这个主要用于在 NFS 挂载上打开文件，因为它允许跳过可能存在的本地缓存。 它对 I/O 性能有较大影响，除非需要否则不建议使用这个 flag。

  注意，它不会将 fs.open() 或 fsPromises.open() 变成同步的阻塞调用。 如果期望同步的操作，应该使用类似 fs.openSync() 的方法。

• 'w' - 打开文件用于写入。文件会被创建（如果不存在）或截断（如果存在）。

• 'wx' - 类似 'w'，但如果文件存在则失败。

• 'w+' - 打开文件用于读取和写入。文件会被创建（如果不存在）或截断（如果存在）。

• 'wx+' - 类似 'w+'，但如果文件存在则失败。

flag 也可以是一个数值，详见 open(2)。 常用的常量定义在 fs.constants。 在 Windows 上，flag 会被转换为等效的 flag，例如 O_WRONLY 转换为 FILE_GENERIC_WRITE、O_EXCL|O_CREAT 转换为 CREATE_NEW。

独有的 'x' flag（ open(2) 中的 O_EXCL flag）确保路径是新创建的。 在 POSIX 系统上，即使是指向不存在的文件的符号链接，路径也会被视为已存在。 这个 flag 在网络文件系统中可能无效。

在 Linux 上，当文件以追加模式打开时，指定位置的写入无效。 内核会忽视位置参数，且总是追加数据到文件的尾部。

若要修改文件而不是覆盖文件，则 flag 模式需要为 'r+' 而不是默认的 'w'。

一些 flag 的行为与平台有关。 例如，在 macOS 和 Linux 上，以 'a+' flag 打开一个目录会返回错误。 但在 Windows 和 FreeBSD 上，则返回一个文件描述符或 FileHandle。

// 在 macOS 和 Linux 上：
fs.open('<目录>', 'a+', (err, fd) => {
  // => [Error: EISDIR: illegal operation on a directory, open <directory>]
});

// 在 Windows 和 FreeBSD 上：
fs.open('<目录>', 'a+', (err, fd) => {
  // => null, <fd>
});

在 Windows 上，使用 'w' flag（无论是 fs.open() 或 fs.writeFile() 或 fsPromises.open()）打开一个现有的隐藏文件会抛出 EPERM 失败。 现有的隐藏文件可以使用 'r+' flag 打开用于写入。

调用 fs.ftruncate() 或 fsPromises.ftruncate() 可以用于重置文件内容。