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 操作接受字符串、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 路径也可以是相对的或绝对的。

支持 URL 对象

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

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

fs.readFileSync(fileUrl);

file: URL 必须是绝对路径。

文件描述符

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

注意：大多数操作系统会限制打开的文件描述符的数量，所以当操作完成时需关闭描述符。如果不这样做会导致内存泄漏，最终造成应用奔溃。

线程池的使用

略过。

常用方法汇总

fs.Stats 类

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

从 fs.stat()、fs.lstat() 和 fs.fstat() 及其同步版本返回的对象都是该类型。

返回的信息包含如下：

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,    //访问时间  （access time）显示的是文件中的数据最后被访问的时间，比如系统
                                           //的进程直接使用或通过一些命令和脚本间接使用。（执行一些可执行文件或脚本）

  mtime: Mon, 10 Oct 2011 23:24:11 GMT,    //修改时间  modify time）显示的是文件内容被修改的最后时间，比如用vi编辑
				                           //时就会被改变。（也就是Block的内容）

  ctime: Mon, 10 Oct 2011 23:24:11 GMT,    //改变时间  （change time）显示的是文件的权限、拥有者、所属的组、链接数发
						 				   //生改变时的时间。当然当内容改变时也会随之改变（即inode内容发生改变和Block内容
											//发生改变时）

  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }   //创建时间

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

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

stats.size 文件的字节大小。

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。

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

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

fs.appendFileSync(path, data[, options]) 同步方法

fs.chmod(path, mode, callback) 异步地改变文件的权限。完成回调只有一个可能的异常参数。

path <string> | <Buffer> | <URL>
mode <integer>
callback <Function>
- err <Error>

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.close(fd, callback) 关闭打开的文件，释放资源。

fd <integer>
callback <Function>
- err <Error>

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

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 已经存在，则会导致拷贝操作失败。

fs.constants返回一个包含常用文件系统操作的常量的对象。

fs.createReadStream(path[, options])

path<string> | <Buffer> | <URL>
options<string> | <Object>
- flags<string>
- encoding<string>
- fd<integer>
- mode<integer>
- autoClose<boolean>
- start<integer>
- end<integer>
- highWaterMark<integer>

返回一个新建的 ReadStream 对象。

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

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

const defaults = {
  flags: 'r',
  encoding: null,
  fd: null,
  mode: 0o666,
  autoClose: true,
  highWaterMark: 64 * 1024
};

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>
- encoding <string>
- fd <integer>
- mode <integer>
- autoClose <boolean>
- start <integer>

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

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

const defaults = {
  flags: 'w',
  encoding: 'utf8',
  fd: null,
  mode: 0o666,
  autoClose: true
};

options 也可以包括一个 start 选项，使其可以写入数据到文件某个位置。如果是修改一个文件而不是覆盖它，则需要flags 模式为 r+ 而不是默认的 w 模式。

其它和fs.createReadStream(path[, options])类似。

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

path <string> | <Buffer> | <URL>
mode <integer> Default: 0o777
callback <Function>
- err <Error>

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

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

path<string> | <Buffer> | <URL>
flags<string> | <number>
mode<integer>Default:0o666
callback<Function>
- err<Error>
- fd<integer>

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，可读写。

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>

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

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

path<string> | <Buffer> | <URL>
options<string> | <Object>
- encoding<string> 默认 = 'utf8'
callback<Function>
- err<Error>
- files<string[]> | <Buffer[]>

回调有两个参数 (err, files)，其中 files 是目录中不包括 '.' 和 '..' 的文件名的数组。

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

path <string> | <Buffer> | <URL> | <integer> 文件名或文件描述符。
options <Object> | <string>
- encoding <string> | <null> 默认为 null。
- flag <string> 默认为 'r'。
callback <Function>
- err <Error>
- data <string> | <Buffer>

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

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

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

注意：如果一个文件描述符被指定为 path，则它不会被自动关闭。

fs.rename(oldPath, newPath, callback)

oldPath <string> | <Buffer> | <URL>
newPath <string> | <Buffer> | <URL>
callback <Function>
- err <Error>

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

fs.rmdir(path, callback)

path<string> | <Buffer> | <URL>
callback<Function>
- err<Error>

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

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

fs.unlink(path, callback)

path <string> | <Buffer> | <URL>
callback <Function>
- err <Error>

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

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 不是一个字符串，则该值将被强制转换为一个字符串。