方法和属性

fs.readdir(path, callback)

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

fs.readdirSync(path)

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

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

异步的 mkdir(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。mode 默认为 0o777。

fs.mkdirSync(path[, mode])

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

fs.rmdir(path, callback)

异步的 rmdir(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.rmdirSync(path)

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

fs.realpath(path[, cache], callback)

异步的 realpath(2)。callback 有两个参数 (err, resolvedPath)。可以使用 process.cwd 解析相对路径。cache 是一个对象字面映射路径可用于强制一个特定路径的解析或避免 fs.stat 对已知的真实路径的额外调用。

例子：

  1. var cache = {
  2.     '/etc': '/private/etc'
  3. };
  4. fs.realpath('/etc/passwd', cache, (err, resolvedPath) => {
  5.     if (err) throw err;
  6.     console.log(resolvedPath);
  7. });

fs.realpathSync(path[, cache])

同步的 realpath(2)。返回解析的路径。cache 是一个对象字面映射路径可用于强制一个特定路径的解析或避免 fs.stat 对已知的真实路径的额外调用。

fs.link(srcpath, dstpath, callback)

异步的 link(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.linkSync(srcpath, dstpath)

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

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

异步的 symlink(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。type 参数可以设置为 'dir'、'file' 或 'junction'（默认为 'file'）并且仅在 Windows 上可用（在其他平台上忽略）。请注意，Windows 交接点需要的目标路径是绝对的。当使用 'junction' 时，target 参数会被自动归到绝对路径。

这里有以下例子：

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

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

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

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

fs.readlink(path, callback)

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

fs.readlinkSync(path)

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

fs.unlink(path, callback)

异步的 unlink(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.unlinkSync(path)

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

fs.lchmod(path, mode, callback)

异步的 lchmod(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

仅在 Mac OS X 上有效。

fs.lchmodSync(path, mode)

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

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

异步的 lchown(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.lchownSync(path, uid, gid)

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

fs.lstat(path, callback)

异步的 lstat(2)。该回调函数带有两个参数 (err, stats)，其中 stats 是一个 fs.Stats 对象。lstat() 等同于 stat()，除非 path 是一个 symbolic 链接，那么自身就是该链接，它指向的并不是文件。

fs.lstatSync(path)

同步的 lstat(2)。返回一个 fs.Stats 实例。

fs.createReadStream(path[, options])

返回一个新的 ReadStream 对象（详见 可读流章节）。

要知道，不同于在一个可读流上设置的 highWaterMark 默认值（16 kb），此方法在相同参数下返回的流具有 64 kb 的默认值。

options 是一个对象或字符串带有以下默认值：

  1. {
  2.     flags: 'r',
  3.     encoding: null,
  4.     fd: null,
  5.     mode: 0o666,
  6.     autoClose: true
  7. }

options 可以包括 start 和 end 值，从文件而不是整个文件读取字节范围。start 和 end 都需要包括在内，并且起始值都是 0。encoding 可以是任何可以被 Buffer 接受的值。

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

如果 autoClose 是 false，那么文件描述符将不会被关闭，即使有错误。将其关闭是你的职责，并且需要确保没有文件描述符泄漏。如果 autoClose 被设置为 true（默认行为），在 error 或 end 时，文件描述符将被自动关闭。

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

一个例子来读取 100 字节长的文件的最后 10 个字节：

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

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

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

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

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

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

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

position 是一个整数，指定从该文件中开始读取的位置。如果 position 是 null，数据将从当前文件位置读取。

回调给出的三个参数 (err, bytesRead, buffer)。

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

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

fs.createWriteStream(path[, options])

返回一个新的 WriteStream 对象（详见 可写流章节）。

options 是一个对象或字符串带有以下默认值：

  1. {
  2.     flags: 'w',
  3.     defaultEncoding: 'utf8',
  4.     fd: null,
  5.     mode: 0o666,
  6.     autoClose: true
  7. }

options 也可以包括一个 start 选项以允许在以前的文件开头部分的位置写入数据。如果是修改文件而不是替换它的话可能需要 r+ 的 flags 模式而不是默认的 w 模式。defaultEncoding 可以是任何可以被 Buffer 接受的值。

如果 autoClose 被设置为 true（默认行为），在文件描述符发生 error 或 end 事件时，会被自动关闭。如果 autoClose 是 false，那么文件描述符将不会被关闭，即使有错误。将其关闭是你的职责，并且需要确保没有文件描述符泄漏。

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

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

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

写入 data 到由 fd 指定的文件。如果 data 不是一个 Buffer 实例，那么该值将被强制转换为字符串。

position 指向该数据应从哪里写入的文件的开头的偏移量。如果 typeof position !== 'number' 该数据将在当前位置被写入。详见 pwrite(2)。

encoding 是预期的字符串编码。

该回调将接收 (err, written, string) 参数，written 用于指定传递过来的字符串需要被写入多少字节。请注意，写入字节与字符串中的字符不同。详见 Buffer.byteLength。

与写入 buffer 不同，整个字符串必须写入。无子字符串可以指定。这是因为字节所得到的数据的偏移量可能与字符串的偏移量不同。

需要注意的是使用 fs.write 在不等待回调的情况下对同一文件进行多次写入，这是不安全的操作。对于这种情况，我们强烈推荐使用 fs.createWriteStream 方法。

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

fs.writeSync(fd, data[, position[, encoding]])

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

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

写入 buffer 到由 fd 指定的文件。

offset 和 length 确定该 buffer 被写入的部分。

position 指向该数据应从哪里写入的文件的开头的偏移量。如果 typeof position !== 'number' 该数据将在当前位置被写入。详见 pwrite(2)。

该回调会给出三个参数 (err, written, buffer)，written 用于指定从 buffer 中写入多少字节。

需要注意的是使用 fs.write 在不等待回调的情况下对同一文件进行多次写入，这是不安全的操作。对于这种情况，我们强烈推荐使用 fs.createWriteStream 方法。

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

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

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

fs.truncate(path, len, callback)

异步的 truncate(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。文件描述符也可以作为第一个参数传递。在这种情况下，fs.ftruncate() 被调用。

fs.truncateSync(path, len)

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

fs.stat(path, callback)

异步的 stat(2)。回调有两个参数 (err, stats)，其中 stats 是一个 fs.Stats 对象。详见 fs.Stats 章节了解更多信息。

fs.statSync(path)

同步的 stat(2)。返回一个 fs.Stats 实例。

fs.chmod(path, mode, callback)

异步的 chmod(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.chmodSync(path, mode)

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

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

异步的 chown(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.chownSync(path, uid, gid)

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

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

改变由 path 提供的路径所引用的文件的文件时间戳。

注意：atime 和 mtime 参数跟随的相关函数是否遵循以下规则：

  • 如果值是一个像 '123456789' 那样的可以数值化的字符串，该值会得到转换为对应的数值。

  • 如果值是 NaN 或 Infinity，该值将被转换为 Date.now()。

fs.utimesSync(path, atime, mtime)

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

fs.exists(path, callback)

稳定度：0 - 已废弃：使用 fs.stat() 或 fs.access() 代替。

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

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

在调用 fs.open() 前，fs.exists() 不应该被用于检测文件是否存在。这样做会形成一种竞争状态，因为其他进程可能会在两个调用之间改变文件的状态。反而，用户代码应直接调用 fs.open() 并处理如果该文件不存在引发的错误。

fs.existsSync(path)

稳定度：0 - 已废弃：使用 fs.statSync() 或 fs.accessSync() 代替。

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

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

异步打开文件。详见 open(2)。

flags 可以是：

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

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

  • 'rs' - 以同步读取模式打开文件。指示操作系统绕过本地文件系统的高速缓存。

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

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

  • 'rs+' - 以读写模式打开文件，告知操作系统同步打开。详见 'rs' 中的有关的注意点。

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

  • 'wx' - 类似于 'w'，但如果 path 存在，将会导致失败。

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

  • 'wx+' - 类似于 'w+'，但如果 path 存在，将会导致失败。

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

  • 'ax' - 类似于 'a'，但如果 path 存在，将会导致失败。

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

  • 'ax+' - 类似于 'a+'，但如果 path 存在，将会导致失败。

mode 设置文件模式（权限和粘滞位），但只有当文件被创建时有效。它默认为 0666，可读写。

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

独家标志 'x'（在 open(2) 中的 O_EXCL 标志）确保 path 是新创建的。在 POSIX 操作系统中，哪怕是一个符号链接到一个不存在的文件，path 也会被视为存在。独家标志有可能可以在网络文件系统中工作。

flags 也可以是一个记录在 open(2) 中的数字；常用的辅音可从 require('constants') 获取。在 Windows 中，标志被转换为它们等同的替代，可适用如 O_WRONLY 到 FILE_GENERIC_WRITE，或 O_EXCL|O_CREAT 到 CREATE_NEW 通过 CreateFileW 接受。

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

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

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

fs.close(fd, callback)

异步的 close(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.closeSync(fd)

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

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

测试由 path 指定的文件的用户权限。mode 是一个可选的整数，指定要执行的辅助检查。以下常量定义 mode 的可能值。有可能产生由位或和两个或更多个值组成的掩码。

  • fs.F_OK - 文件对调用进程可见。这在确定文件是否存在时很有用，但只字未提 rwx 权限。如果 mode 没被指定，默认为该值。

  • fs.R_OK - 文件可以通过调用进程读取。

  • fs.W_OK - 文件可以通过调用进程写入。

  • fs.X_OK - 文件可以通过调用进程执行。这对 Windows 没有影响（行为类似 fs.F_OK）。

最后一个参数 callback 是一个回调函数，调用时可能带有一个 error 参数。如果有任何辅助检查失败，错误参数将被填充。下面的例子将检查 /etc/passwd 文件是否可以被读取并被当前进程写入。

  1. fs.access('/etc/passwd', fs.R_OK | fs.W_OK, (err) => {
  2.     console.log(err ? 'no access!' : 'can read/write');
  3. });

fs.accessSync(path[, mode])

同步版的 fs.access()。如果有任何辅助检查失败将抛出错误，否则什么也不做。

fs.rename(oldPath, newPath, callback)

异步的 rename(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.renameSync(oldPath, newPath)

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

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

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

第二个参数是可选的。如果提供的话，options 应该是一个对象。支持的布尔成员是 persistent 和 recursive。persistent 表示当文件被监视时，该进程是否应该持续运行。recursive 表示所有子目录是否应该关注，或仅当前目录。只有在支持的平台（参见注意事项）上可以指定目录适用。

默认为 { persistent: true, recursive: false }。

该监听回调获得两个参数 (event, filename)。event 既可以是 'rename' 也可以是 'change'，并且 filename 是其中触发事件的文件的名称。

注意事项

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

递归选项只支持 OS X 和 Windows。

可用性

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

  • 在 Linux 系统中，使用 inotify。

  • 在 BSD 系统中，使用 kqueue。

  • 在 OS X 系统中，对文件使用 kqueue，对目录使用 'FSEvents'。

  • 在 SunOS 系统（包括 Solaris 和 SmartOS）中，使用 event ports。

  • 在 Windows 系统中，此功能取决于 ReadDirectoryChangesW。

如果底层功能出于某种原因不可用，那么 fs.watch 也将无法正常工作。例如，在网络文件系统（ZFS，SMB 等）中监视文件或目录往往并不可靠或都不可靠。

你可以仍然使用 fs.watchFile，它使用状态查询，但它较慢和不可靠。

索引节点

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

文件名参数

在回调中提供 filename 参数，仅在 Linux 和 Windows 系统上支持。即使在支持的平台中，filename 也不能保证提供。因此，不要以为 filename 参数总是在回调中提供，并在它是 null 的情况下，提供一定的后备逻辑。

  1. fs.watch('somedir', (event, filename) => {
  2.     console.log(`event is: ${event}`);
  3.     if (filename) {
  4.         console.log(`filename provided: ${filename}`);
  5.     } else {
  6.         console.log('filename not provided');
  7.     }
  8. });

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

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

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

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

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

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

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

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

注意：fs.watch() 比 fs.watchFile 和 fs.watchFile 更高效。可能的话，fs.watch 应当被用来代替 fs.watchFile 和 fs.unwatchFile。

fs.unwatchFile(filename[, listener])

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

带有一个没有被监视的文件名来调用 fs.unwatchFile() 是一个空操作，而不是一个错误。

注意：fs.watch() 比 fs.watchFile 和 fs.watchFile 更高效。可能的话，fs.watch 应当被用来代替 fs.watchFile 和 fs.unwatchFile。

fs.readFile(file[, options], callback)

  • file {String} | {Integer} 文件名或文件描述符

  • options {Object} | {String}

    • encoding {String} | {Null} 默认 = null

    • flag {String} 默认 = 'r'

  • callback {Function}

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

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

该回调传入两个参数 (err, data)，data 是文件的内容。

如果没有指定编码，则返回原始 buffer。

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

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

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

注意：指定的文件描述符不会被自动关闭。

fs.readFileSync(file[, options])

同步版的 fs.readFile。返回 file 的内容。

如果 encoding 参数被指定，则此函数返回一个字符串。否则，它返回一个 buffer。

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

  • file {String} | {Integer} 文件名或文件描述符

  • data {String} | {Buffer}

  • options {Object} | {String}

    • encoding {String} | {Null} 默认 = 'utf8'

    • mode {Number} 默认 = 0o666

    • flag {String} 默认 = 'w'

  • callback {Function}

异步将数据写入到文件，如果它已经存在，则替换该文件。data 可以是一个字符串或 buffer。

如果 data 是一个 buffer，则忽略 encoding 选项。它默认为 'utf8'。

例子：

  1. fs.writeFile('message.txt', 'Hello Node.js', (err) => {
  2.     if (err) throw err;
  3.     console.log('It\'s saved!');
  4. });

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

  1. fs.writeFile('message.txt', 'Hello Node.js', 'utf8', callback);

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

需要注意的是使用 fs.writeFile 在不等待回调的情况下对同一文件进行多次写入，这是不安全的操作。对于这种情况，我们强烈推荐使用 fs.createWriteStream 方法。

注意：指定的文件描述符不会被自动关闭。

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

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

fs.appendFile(file, data[, options], callback)

  • file {String} | {Number} 文件名或文件描述符

  • data {String} | {Buffer}

  • options {Object} | {String}

    • encoding {String} | {Null} 默认 = 'utf8'

    • mode {Number} 默认 = 0o666

    • flag {String} 默认 = 'a'

  • callback {Function}

异步追加数据到文件，如果它已经存在，则替换该文件。data 可以是一个字符串或 buffer。

例子：

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

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

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

任何指定的文件描述符必须为了追加而被打开。

注意：指定的文件描述符不会被自动关闭。

fs.appendFileSync(file, data[, options])

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

fs.ftruncate(fd, len, callback)

异步的 ftruncate(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.ftruncateSync(fd, len)

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

fs.fstat(fd, callback)

异步的 fstat(2)。该回调获得两个参数 (err, stats)，stats 是一个 fs.Stats 对象。fstat() 与 fs.stat() 类似，除了文件是通过指定的文件描述符 fd 来说明。

fs.fstatSync(fd)

同步的 fstat(2)。返回一个 fs.Stats 实例。

fs.fchmod(fd, mode, callback)

异步的 fchmod(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.fchmodSync(fd, mode)

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

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

异步的 fchown(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.fchownSync(fd, uid, gid)

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

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

改变由所提供的文件描述符所引用的文件的文件时间戳。

fs.futimesSync(fd, atime, mtime)

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

fs.fsync(fd, callback)

异步的 fsync(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.fsyncSync(fd)

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

fs.fdatasync(fd, callback)

异步的 fdatasync(2)。除了一个可能的异常参数外没有其他参数会给到完成时的回调。

fs.fdatasyncSync(fd)

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