文件系统标志


flag 选项采用字符串时,可用以下标志:

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

  • 'ax' - 与 'a' 相似,但如果路径已存在则失败。

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

  • 'ax+' - 与 'a+' 相似,但如果路径已存在则失败。

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

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

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

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

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

    这对于在 NFS 挂载上打开文件时非常有用,因为它允许跳过可能过时的本地缓存。 它对 I/O 性能有非常实际的影响,因此除非需要,否则不建议使用此标志。

    这不会将 fs.open()fsPromises.open() 转换为同步的阻塞调用。 如果需要同步的操作,则应使用 fs.openSync() 之类的。

  • 'w' - 打开文件用于写入。如果文件不存在则创建文件,如果文件已存在则截断文件。

  • 'wx' - 与 'w' 相似,但如果路径已存在则失败。

  • 'w+' - 打开文件用于读取和写入。如果文件不存在则创建文件,如果文件已存在则截断文件。

  • 'wx+' - 与 'w+' 相似,但如果路径已存在则失败。

flag 也可以是一个数字,参阅 open(2) 文档。 常用的常量可以从 fs.constants 获取。 在 Windows 上,标志会被适当地转换为等效的标志,例如 O_WRONLY 转换为 FILE_GENERIC_WRITEO_EXCL|O_CREAT 转换为能被 CreateFileW 接受的 CREATE_NEW

特有的 'x' 标志( open(2) 中的 O_EXCL 标志)可以确保路径是新创建的。 在 POSIX 系统上,即使路径是一个符号链接且指向一个不存在的文件,它也会被视为已存在。 该特有标志不一定适用于网络文件系统。

在 Linux 上,当以追加模式打开文件时,写入无法指定位置。 内核会忽略位置参数,并始终将数据追加到文件的末尾。

如果要修改文件而不是覆盖文件,则标志模式应为 'r+' 模式而不是默认的 'w' 模式。

某些标志的行为是特定于平台的。 例如,在 macOS 和 Linux 上使用 'a+' 标志打开目录(参阅下面的示例)会返回一个错误。 而在 Windows 和 FreeBSD 上,则返回一个文件描述符或 FileHandle

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

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

在 Windows 上,使用 'w' 标志打开现存的隐藏文件(通过 fs.open()fs.writeFile()fsPromises.open())会抛出 EPERM。 现存的隐藏文件可以使用 'r+' 标志打开用于写入。

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

The following flags are available wherever the flag option takes a string:

  • 'a' - Open file for appending. The file is created if it does not exist.

  • 'ax' - Like 'a' but fails if the path exists.

  • 'a+' - Open file for reading and appending. The file is created if it does not exist.

  • 'ax+' - Like 'a+' but fails if the path exists.

  • 'as' - Open file for appending in synchronous mode. The file is created if it does not exist.

  • 'as+' - Open file for reading and appending in synchronous mode. The file is created if it does not exist.

  • 'r' - Open file for reading. An exception occurs if the file does not exist.

  • 'r+' - Open file for reading and writing. An exception occurs if the file does not exist.

  • 'rs+' - Open file for reading and writing in synchronous mode. Instructs the operating system to bypass the local file system cache.

    This is primarily useful for opening files on NFS mounts as it allows skipping the potentially stale local cache. It has a very real impact on I/O performance so using this flag is not recommended unless it is needed.

    This doesn't turn fs.open() or fsPromises.open() into a synchronous blocking call. If synchronous operation is desired, something like fs.openSync() should be used.

  • 'w' - Open file for writing. The file is created (if it does not exist) or truncated (if it exists).

  • 'wx' - Like 'w' but fails if the path exists.

  • 'w+' - Open file for reading and writing. The file is created (if it does not exist) or truncated (if it exists).

  • 'wx+' - Like 'w+' but fails if the path exists.

flag can also be a number as documented by open(2); commonly used constants are available from fs.constants. On Windows, flags are translated to their equivalent ones where applicable, e.g. O_WRONLY to FILE_GENERIC_WRITE, or O_EXCL|O_CREAT to CREATE_NEW, as accepted by CreateFileW.

The exclusive flag 'x' (O_EXCL flag in open(2)) ensures that path is newly created. On POSIX systems, path is considered to exist even if it is a symlink to a non-existent file. The exclusive flag may or may not work with network file systems.

On Linux, positional writes don't 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.

Modifying a file rather than replacing it may require a flags mode of 'r+' rather than the default mode 'w'.

The behavior of some flags are platform-specific. As such, opening a directory on macOS and Linux with the 'a+' flag - see example below - will return an error. In contrast, on Windows and FreeBSD, a file descriptor or a FileHandle will be returned.

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

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

On Windows, opening an existing hidden file using the 'w' flag (either through fs.open() or fs.writeFile() or fsPromises.open()) will fail with EPERM. Existing hidden files can be opened for writing with the 'r+' flag.

A call to fs.ftruncate() or filehandle.truncate() can be used to reset the file contents.