Node.js 文件系统

2022-02-26 10:29 更新

Node.js官方文档对Node.js文件系统进行了详细的介绍。

稳定性: 3 - 稳定

Node.js文件系统模块是一个封装了标准的POSIX文件I/O操作的集合。通过require('fs')使用这个模块,其中所有的方法都有同步和异步两种模式。

异步方法最后一个参数都是回调函数,这个回调的参数取决于方法,不过第一个参数一般都是异常。如果操作成功,那么第一个参数就是nullundefined

当使用一个同步操作的时候,任意的异常都立即抛出,可以用try/catch来处理异常,使得程序正常运行。

以下是一个异步操作的例子:

var fs = require('fs');

fs.unlink('/tmp/hello', function (err) {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

以下是一个同步操作的例子:

var fs = require('fs');

fs.unlinkSync('/tmp/hello');
console.log('successfully deleted /tmp/hello');

异步方法不能保证操作顺序,因此下面的例子很容易出错:

fs.rename('/tmp/hello', '/tmp/world', function (err) {
  if (err) throw err;
  console.log('renamed complete');
});
fs.stat('/tmp/world', function (err, stats) {
  if (err) throw err;
  console.log('stats: ' + JSON.stringify(stats));
});

该例子出错的原因很可能是因为先执行了fs.stat方法,正确的方法如下:

fs.rename('/tmp/hello', '/tmp/world', function (err) {
  if (err) throw err;
  fs.stat('/tmp/world', function (err, stats) {
    if (err) throw err;
    console.log('stats: ' + JSON.stringify(stats));
  });
});

在繁忙的进程里,强烈建议使用异步方法。同步方法会阻塞整个进程,直到方法完成。

可能会用到相对路径,路径是相对process.cwd()来说的。

大部分fs函数会忽略回调参数,如果忽略,将会用默认函数抛出异常。如果想得到原调用点的堆栈信息,需要设置环境变量NODE_DEBUG:

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

$ env NODE_DEBUG=fs node script.js
fs.js:66
        throw err;
              ^
Error: EISDIR, read
    at rethrow (fs.js:61:21)
    at maybeCallback (fs.js:79:42)
    at Object.fs.readFile (fs.js:153:18)
    at bad (/path/to/script.js:2:17)
    at Object.<anonymous> (/path/to/script.js:5:1)
    <etc.>

fs.rename(oldPath, newPath, callback)

异步函数rename(2)。回调函数只有一个参数:可能出现的异常。

fs.renameSync(oldPath, newPath)

同步函数rename(2)。 返回undefined

fs.ftruncate(fd, len, callback)

异步函数ftruncate(2)。 回调函数只有一个参数:可能出现的异常。

fs.ftruncateSync(fd, len)

同步函数ftruncate(2)。 返回undefined

fs.truncate(path, len, callback)

异步函数truncate(2)。 回调函数只有一个参数:可能出现的异常。 文件描述符也可以作为第一个参数,如果这种情况,调用fs.ftruncate()

fs.truncateSync(path, len)

同步函数truncate(2)。 返回undefined

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

异步函数chown(2)。回调函数只有一个参数:可能出现的异常。

fs.chownSync(path, uid, gid)

同步函数chown(2)。返回undefined

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

异步函数fchown(2)。回调函数只有一个参数:可能出现的异常。

fs.fchownSync(fd, uid, gid)

同步函数 fchown(2)。返回undefined

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

异步函数lchown(2)。回调函数只有一个参数:可能出现的异常。

fs.lchownSync(path, uid, gid)

同步函数lchown(2)。返回undefined

fs.chmod(path, mode, callback)

异步函数chmod(2)。回调函数只有一个参数:可能出现的异常。

fs.chmodSync(path, mode)

同步函数chmod(2)。返回 undefined

fs.fchmod(fd, mode, callback)

异步函数fchmod(2)。回调函数只有一个参数:可能出现的异常。

fs.fchmodSync(fd, mode)

同步函数fchmod(2)。返回undefined

fs.lchmod(path, mode, callback)

异步函数 lchmod(2)。回调函数只有一个参数:可能出现的异常。

仅在Mac OS X可用。

fs.lchmodSync(path, mode)

同步函数lchmod(2)。返回undefined

fs.stat(path, callback)

异步函数stat(2)。回调函数有两个参数:(err, stats) ,其中stats是一个fs.Stats对象。 详情请参考fs.Stats。

fs.lstat(path, callback)

异步函数lstat(2)。回调函数有两个参数:(err, stats) ,其中stats是一个fs.Stats对象。lstat()stat()基本相同,区别在于,如果path是链接,读取的是链接本身,而不是它所链接到的文件。

fs.fstat(fd, callback)

异步函数fstat(2)。回调函数有两个参数: (err, stats),其中stats是一个fs.Stats对象。

fs.statSync(path)

同步函数stat(2)。返回fs.Stats实例。

fs.lstatSync(path)

同步函数lstat(2)。返回fs.Stats实例。

fs.fstatSync(fd)

同步函数fstat(2)。返回fs.Stats实例。

fs.link(srcpath, dstpath, callback)

异步函数link(2)。回调函数只有一个参数:可能出现的异常。

fs.linkSync(srcpath, dstpath)

同步函数link(2)。返回undefined

fs.symlink(srcpath, dstpath[, type], callback)

异步函数symlink(2)。回调函数只有一个参数:可能出现的异常。

type可能是'dir','file', 或'junction' (默认'file') ,仅在Windows(不考虑其他系统)有效。注意, Windows junction要求目的地址需要绝对的。当使用'junction'的时候,destination参数将会自动转换为绝对路径。

fs.symlinkSync(srcpath, dstpath[, type])

同步函数symlink(2)。 返回undefined

fs.readlink(path, callback)

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

fs.readlinkSync(path)

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

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

异步函数realpath(2)。回调函数有2个参数(err,resolvedPath)。可以使用process.cwd来解决相对路径问题。

例如:

var cache = {'/etc':'/private/etc'};
fs.realpath('/etc/passwd', cache, function (err, resolvedPath) {
  if (err) throw err;
  console.log(resolvedPath);
});

fs.realpathSync(path[, cache])

同步函数realpath(2)。返回解析出的路径。

fs.unlink(path, callback)

异步函数unlink(2)。回调函数只有一个参数:可能出现的异常.

fs.unlinkSync(path)

同步函数unlink(2)。返回undefined

fs.rmdir(path, callback)

异步函数rmdir(2)。回调函数只有一个参数:可能出现的异常.

fs.rmdirSync(path)

同步函数rmdir(2)。返回undefined

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

异步函数mkdir(2)。回调函数只有一个参数:可能出现的异常. mode默认为0777.

fs.mkdirSync(path[, mode])

同步函数mkdir(2)。返回undefined

fs.readdir(path, callback)

异步函数readdir(3)。读取文件夹的内容。回调有2个参数 (err, files)files是文件夹里除了名字为'.'和'..'之外的所有文件名。

fs.readdirSync(path)

同步函数readdir(3)。返回除了文件名为'.''..'之外的所有文件.

fs.close(fd, callback)

异步函数close(2)。回调函数只有一个参数:可能出现的异常.

fs.closeSync(fd)

同步函数close(2)。返回 undefined

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

异步函数file open. 参见open(2)。flags是:

  • 'r'- 以只读模式打开;如果文件不存在,抛出异常。

  • 'r+'-以读写模式打开;如果文件不存在,抛出异常。

  • 'rs'- 同步的,以只读模式打开;指令绕过操作系统直接使用本地文件系统缓存。这个功能主要用来打开NFS挂载的文件,因为它能让你跳过可能过时的本地缓存。如果对I/O性能很在乎,就不要使用这个标志位。

    这里不是调用fs.open()变成同步阻塞请求,如果你想要这样,可以调用fs.openSync()

  • 'rs+'- 同步模式下以读写方式打开文件。注意事项参见'rs'.

  • 'w'- 以只写模式打开。文件会被创建 (如果文件不存在) 或者覆盖 (如果存在)。

  • 'wx'- 和'w'类似,如果文件存储操作失败

  • 'w+'- 以可读写方式打开。文件会被创建 (如果文件不存在) 或者覆盖 (如果存在)

  • 'wx+'- 和'w+'类似,如果文件存储操作失败。

  • 'a'- 以附加的形式打开。如果文件不存在则创建一个。

  • 'ax'- 和'a'类似,如果文件存储操作失败。

  • 'a+'- 以只读和附加的形式打开文件.若文件不存在,则会建立该文件

  • 'ax+'- 和'a+'类似,如果文件存储操作失败.

如果文件存在,参数mode设置文件模式 (permission和sticky bits)。 默认是0666,可读写。

回调有2个参数(err, fd).

排除标记'x'(对应open(2)的O_EXCL标记) 保证path是新创建的。在POSIX系统里,即使文件不存在,也会被认定为文件存在。排除标记不能确定在网络文件系统中是否有效。

Linux系统里,无法对以追加模式打开的文件进行指定位置写。系统核心忽略了位置参数,每次把数据写到文件的最后。

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

fs.open()的同步版本. 返回整数形式的文件描述符。.

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

改变指定路径文件的时间戳。

fs.utimesSync(path, atime, mtime)

fs.utimes()的同步版本。返回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.write(fd, buffer, offset, length[, position], callback)

buffer写到fd指定的文件里。

参数offsetlength确定写哪个部分的缓存。

参数position是要写入的文件位置。如果typeof position !== 'number',将会在当前位置写入。参见pwrite(2)。

回调函数有三个参数(err, written, buffer)written指定buffer的多少字节用来写。

注意,如果fs.write 的回调还没执行,就多次调用fs.write,这样很不安全。因此,推荐使用fs.createWriteStream

Linux系统里,无法对以追加模式打开的文件进行指定位置写。系统核心忽略了位置参数,每次把数据写到文件的最后。

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

buffer写到fd指定的文件里。如果data不是buffer,那么它就会被强制转换为字符串。

参数position是要写入的文件位置。如果typeof position !== 'number',将会在当前位置写入。参见pwrite(2)。

参数encoding :字符串的编码方式.

回调函数有三个参数(err, written, buffer)written指定buffer的多少字节用来写。注意写入的字节(bytes)和字符(string characters)不同。参见Buffer.byteLength

和写入buffer不同,必须写入整个字符串,不能截取字符串。这是因为返回的字节的位移跟字符串的位移是不一样的。

注意,如果fs.write的回调还没执行,就多次调用fs.write,这样很不安全。因此,推荐使用fs.createWriteStream

Linux系统里,无法对以追加模式打开的文件进行指定位置写。系统核心忽略了位置参数,每次把数据写到文件的最后。

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

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

fs.write()的同步版本. 返回要写的bytes数.

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

读取fd指定文件的数据。

buffer是缓冲区,数据将会写入到这里.

offset写入的偏移量

length需要读的文件长度

position读取的文件起始位置,如果positionnull, 将会从当前位置读。

回调函数有3个参数,(err, bytesRead, buffer).

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

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

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

  • filename {String}
  • options {Object}
    • encoding {String | Null} 默认 = null
    • flag {String} 默认 = 'r'
  • callback {Function}

异步读取整个文件的内容。例如:

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

回调函数有2个参数(err, data),参数data是文件的内容。如果没有指定参数encoding,返回原生buffer

fs.readFileSync(filename[, options])

fs.readFile的同步版本. 返回整个文件的内容.

如果没有指定参数encoding,返回buffer。

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

  • filename {String}
  • data {String | Buffer}
  • options {Object}
    • encoding {String | Null} 默认 = 'utf8'
    • mode {Number} 默认 = 438 (aka 0666 in Octal)
    • flag {String} 默认 = 'w'
  • callback {Function}

异步写文件,如果文件已经存在则替换。data可以是缓存或者字符串。

如果参数data是buffer,会忽略参数encoding。默认值是'utf8'

列如:

fs.writeFile('message.txt', 'Hello Node', function (err) {
  if (err) throw err;
  console.log('It\'s saved!');
});

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

fs.writeFile的同步版本。返回undefined

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

  • filename {String}
  • data {String | Buffer}
  • options {Object}
    • encoding {String | Null} 默认 = 'utf8'
    • mode {Number} 默认 = 438 (aka 0666 in Octal)
    • flag {String} 默认 = 'a'
  • callback {Function}

异步的给文件添加数据,如果文件不存在,就创建一个。data可以是缓存或者字符串。

例如:

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

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

fs.appendFile的同步版本。返回undefined

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

稳定性: 2 - 不稳定。  尽可能的用 fs.watch 来替换。

监视filename文件的变化。每当文件被访问的时候都会调用listener

第二个参数可选。如果有,它必须包含两个boolean参数(persistentinterval)的对象。persistent指定文件被监视时进程是否继续运行。interval指定了查询文件的间隔,以毫秒为单位。缺省值为{ persistent: true, interval: 5007 }。

listener有两个参数,第一个为文件现在的状态,第二个为文件的前一个状态:

fs.watchFile('message.text', function (curr, prev) {
  console.log('the current mtime is: ' + curr.mtime);
  console.log('the previous mtime was: ' + prev.mtime);
});

listener中的文件状态对象类型为fs.Stat。

如果想修改文件时被通知,而不是访问的时候就通知,可以比较curr.mtimeprev.mtime

fs.unwatchFile(filename[, listener])

稳定性: 2 - 不稳定. 尽可能的用 fs.watch 来替换。

停止监视filename文件的变化。如果指定了listener,那只会移除这个listener。否则,移除所有的listener,并会停止监视filename

调用fs.unwatchFile()停止监视一个没被监视的文件,不会触发错误,而会发生一个no-op。

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

稳定性: 2 - 不稳定.

观察filename指定的文件或文件夹的改变。返回对象是 fs.FSWatcher

第二个参数可选。如果有,它必须是包含两个boolean参数(persistentrecursive)的对象。persistent指定文件被监视时进程是否继续运行。 recursive表明是监视所有的子文件夹还是当前文件夹,这个参数只有监视对象是文件夹时才有效,而且仅在支持的系统里有效(参见下面注意事项)。

默认值{ persistent: true, recursive: false }.

回调函数有2个参数(event, filename)eventrenamechangefilename是触发事件的文件名。

注意事项

fs.watchAPI 不是100%的跨平台兼容,可能在某些情况下不可用。

recursive参数仅在OS X上可用。仅FSEvents支持这个类型文件的监视,所以未来也不太可能有新的平台加入。

可用性

这些特性依赖于底层系统提供文件系统变动的通知。

  • Linux系统,使用inotify.
  • BSD系统,使用kqueue.
  • OS X,文件使用kqueue,文件夹使用FSEvents.
  • SunOS 系统(包括Solaris和SmartOS),使用event ports.
  • Windows系统,依赖与ReadDirectoryChangesW.

如果底层系统函数不可用,那么fs.watch就无法工作。例如,监视网络文件系统(NFS、 SMB等)经常不能用。你仍然可以用fs.watchFile查询,但是会比较慢,且不可靠。

文件名参数

回调函数中提供文件名参数,不是每个平台都能用(Linux和Windows就不行)。即使在可用的平台,也不能保证都能提供。所以不要假设回调函数中filename参数有效,要在代码里添加一些为空的逻辑判断。

fs.watch('somedir', function (event, filename) {
  console.log('event is: ' + event);
  if (filename) {
    console.log('filename provided: ' + filename);
  } else {
    console.log('filename not provided');
  }
});

fs.exists(path, callback)

判断文件是否存在,回调函数参数是bool值。例如:

fs.exists('/etc/passwd', function (exists) {
  util.debug(exists ? "it's there" : "no passwd!");
});

fs.exists()是老版本的函数,因此在代码里不要用。

另外,打开文件前判断是否存在有漏洞,在fs.exists()fs.open()调用中间,另外一个进程有可能已经移除了文件。最好用fs.open()来打开文件,根据回调函数来判断是否有错误。

fs.exists()未来会被移除。

fs.existsSync(path)

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

fs.existsSync()未来会被移除。

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

测试由参数path指向的文件的用户权限。可选参数mode为整数,它表示需要检查的权限。下面列出了所有值。mode可以是单个值,或者可以通过或运算,掩码运算实现多个权限检查。

  • fs.F_OK- 文件是对于进程可见,可以用来检查文件是否存在。参数mode的默认值。
  • fs.R_OK- 文件对于进程是否可读。
  • fs.W_OK- 文件对于进程是否可写。
  • fs.X_OK- 文件对于进程是否可执行。(Windows系统不可用,执行效果等同fs.F_OK

第三个参数是回调函数。如果检查失败,回调函数的参数就是响应的错误。下面的例子检查文件/etc/passwd是否能被当前的进程读写。

fs.access('/etc/passwd', fs.R_OK | fs.W_OK, function(err) {
  util.debug(err ? 'no access!' : 'can read/write');
});

fs.accessSync(path[, mode])

fs.access的同步版本. 如果发生错误抛出异常,否则不做任何事情。

类: fs.Stats

fs.stat(), fs.lstat()fs.fstat()以及同步版本的返回对象。

  • stats.isFile()
  • stats.isDirectory()
  • stats.isBlockDevice()
  • stats.isCharacterDevice()
  • stats.isSymbolicLink() (only valid with fs.lstat())
  • stats.isFIFO()
  • stats.isSocket()

对普通文件使用util.inspect(stats),返回的字符串和下面类似:

{ dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  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 }

atime, mtime, birthtime, 和ctime都是Date的实例,需要使用合适的方法来比较这些值。通常使用getTime()来获取时间戳(毫秒,从 1 January 1970 00:00:00 UTC开始算),这个整数基本能满足任何比较条件。也有一些其他方法来显示额外信息。更多参见MDN JavaScript Reference

Stat Time Values

状态对象(stat object)有以下语义:

  • atime访问时间 - 文件的最后访问时间. mknod(2), utimes(2), 和 read(2)等系统调用可以改变.
  • mtime修改时间 - 文件的最后修改时间. mknod(2), utimes(2), 和 write(2)等系统调用可以改变.
  • ctime改变时间 - 文件状态(inode)的最后修改时间. chmod(2), chown(2),link(2), mknod(2), rename(2), unlink(2), utimes(2), read(2), 和write(2)等系统调用可以改变.
  • birthtime"Birth Time" - 文件创建时间,文件创建时生成。 在一些不提供文件birthtime的文件系统中, 这个字段会使用ctime或1970-01-01T00:00Z (ie, unix epoch timestamp 0)来填充。在Darwin和其他FreeBSD系统变体中,也将atime显式地设置成比它现在的birthtime更早的一个时间值,这个过程使用了 utimes(2)系统调用。

在Node v0.12版本之前,Windows系统里ctime有birthtime值. 注意在v.0.12版本中, ctime不再是"creation time", 而且在Unix系统中,他一直都不是。

fs.createReadStream(path[, options])

返回可读流对象 (见Readable Stream)。

options默认值如下:

{ flags: 'r',
  encoding: null,
  fd: null,
  mode: 0666,
  autoClose: true
}

参数options提供startend位置来读取文件的特定范围内容,而不是整个文件。startend都在文件范围里,并从0开始,encoding'utf8', 'ascii''base64'

如果给了fd值,ReadStream将会忽略path参数,而使用文件描述,这样不会触发任何open事件。

如果autoClose为false,即使发生错误文件也不会关闭,需要你来负责关闭,避免文件描述符泄露。如果autoClose是true(默认值),遇到errorend,文件描述符将会自动关闭。

例如,从100个字节的文件里,读取最少10个字节:

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

Class: fs.ReadStream

ReadStreamReadable Stream

Event: 'open'

  • fd{Integer} ReadStream 所使用的文件描述符。

当创建文件的ReadStream时触发。

fs.createWriteStream(path[, options])

返回一个新的写对象 (参见 Writable Stream)。

options是一个对象,默认值:

{ flags: 'w',
  encoding: null,
  fd: null,
  mode: 0666 }

options也可以包含一个start选项,在指定文件中写入数据开始位置。 修改而不替换文件需要flags的模式指定为r+而不是默值的w。

和之前的ReadStream类似,如果fd不为空,WriteStream将会忽略path参数,转而使用文件描述,这样不会触发任何open事件。

类: fs.WriteStream

WriteStreamWritable Stream

Event: 'open'

  • fd{Integer} WriteStream所用的文件描述符

打开WriteStream file时触发。

file.bytesWritten

目前写入的字节数,不含等待写入的数据。

Class: fs.FSWatcher

fs.watch()返回的对象就是这个类.

watcher.close()

停止观察fs.FSWatcher对象中的更改。

Event: 'change'

  • event{String} fs改变的类型
  • filename{String} 改变的文件名 (if relevant/available)

当监听的文件或文件夹改变的时候触发,参见fs.watch

Event: 'error'

  • error{Error object}

错误发生时触发。

相关文章

JavaScript 错误 - throw、try 和 catch


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号