文件系统标志


以下标志在 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_WRONLYFILE_GENERIC_WRITE,或 O_EXCL|O_CREATCREATE_NEW,为 CreateFileW 所接受。

如果路径已经存在,则独占标志 'x'open(2) 中的 O_EXCL 标志)会导致操作返回错误。 在 POSIX 上,如果路径是符号链接,即使链接指向不存在的路径,使用 O_EXCL 也会返回错误。 独占标志可能不适用于网络文件系统。

在 Linux 上,以追加模式打开文件时,位置写入不起作用。 内核会忽略位置参数,并始终将数据追加到文件末尾。

修改文件而不是替换它可能需要将 flag 选项设置为 'r+' 而不是默认的 'w'

某些标志的行为是特定于平台的。 因此,在 macOS 和 Linux 上使用 'a+' 标志打开目录,如下例所示,将返回错误。 而在 Windows 和 FreeBSD 上,将返回文件描述符或 FileHandle

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

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

在 Windows 上,使用 'w' 标志(通过 fs.open()fs.writeFile()fsPromises.open())打开现有隐藏文件将失败并抛出 EPERM。 可以使用 'r+' 标志打开现有的隐藏文件进行写入。

调用 fs.ftruncate()filehandle.truncate() 可用于重置文件内容。

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)) causes the operation to return an error if the path already exists. On POSIX, if the path is a symbolic link, using O_EXCL returns an error even if the link is to a path that does not exist. The exclusive flag might 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 the flag option to be set to 'r+' rather than the default 'w'.

The behavior of some flags are platform-specific. As such, opening a directory on macOS and Linux with the 'a+' flag, as in the 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(), 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.