文件系统标志


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 转换为 CREATE_NEW

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

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

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

某些标志的行为是特定于平台的。 例如,使用 'a+' 标志打开 macOS 和 Linux 上的目录(参阅下面的示例)将返回错误。 而在 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' 标志(通过 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.