diff --git a/child_process/child_process_exec_command_options_callback.md b/child_process/child_process_exec_command_options_callback.md index 4ab4bd29..476dc3b0 100644 --- a/child_process/child_process_exec_command_options_callback.md +++ b/child_process/child_process_exec_command_options_callback.md @@ -66,7 +66,7 @@ exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => { 与 exec(3) 的 POSIX 系统调用不同， `child_process.exec()` 不会替换现有的进程，且使用 shell 来执行命令。 -如果调用此方法的 [`util.promisify()`] 版本，则返回的 `Promise` 会返回具有 `stdout` 属性和 `stderr` 属性的 `Object`。 +如果调用此方法的 [`util.promisify()`] 版本，则返回 `Promise`（会传入具有 `stdout` 属性和 `stderr` 属性的 `Object`）。 返回的 `ChildProcess` 实例会作为 `child` 属性附加到该 `Promise`。 如果出现错误（包括导致退出码不是 0 的任何错误），则返回被拒绝的 Promise，并带上与回调中相同的 `error` 对象，但是还有两个另外的属性 `stdout` 和 `stderr`。 diff --git a/child_process/child_process_execfile_file_args_options_callback.md b/child_process/child_process_execfile_file_args_options_callback.md index dacdbb0c..5db48c3b 100644 --- a/child_process/child_process_execfile_file_args_options_callback.md +++ b/child_process/child_process_execfile_file_args_options_callback.md @@ -52,7 +52,7 @@ const child = execFile('node', ['--version'], (error, stdout, stderr) => { `encoding` 选项可用于指定用于解码 stdout 和 stderr 输出的字符编码。 如果 `encoding` 是 `'buffer'` 或无法识别的字符编码，则传给回调的将会是 `Buffer` 对象。 -如果调用此方法的 [`util.promisify()`] 版本，则返回的 `Promise` 会返回具有 `stdout` 属性和 `stderr` 属性的 `Object`。 +如果调用此方法的 [`util.promisify()`] 版本，则返回 `Promise`（会传入具有 `stdout` 属性和 `stderr` 属性的 `Object`）。 返回的 `ChildProcess` 实例会作为 `child` 属性附加到该 `Promise`。 如果出现错误（包括导致退出码不是 0 的任何错误），则返回被拒绝的 Promise，并带上与回调中相同的 `error` 对象，但是还有两个另外的属性 `stdout` 和 `stderr`。 diff --git a/domain/class_domain.md b/domain/class_domain.md index be517535..458a7909 100644 --- a/domain/class_domain.md +++ b/domain/class_domain.md @@ -1,5 +1,5 @@ -* Extends: {EventEmitter} +* 继承自: {EventEmitter} The `Domain` class encapsulates the functionality of routing errors and uncaught exceptions to the active `Domain` object. diff --git a/errors/class_systemerror.md b/errors/class_systemerror.md index eae5008b..9d275e53 100644 --- a/errors/class_systemerror.md +++ b/errors/class_systemerror.md @@ -1,5 +1,5 @@ -* Extends: {errors.Error} +* 继承自: {errors.Error} Node.js generates system errors when exceptions occur within its runtime environment. These usually occur when an application violates an operating diff --git a/fs/class_fs_dir.md b/fs/class_fs_dir.md index 56857efe..8a7ae451 100644 --- a/fs/class_fs_dir.md +++ b/fs/class_fs_dir.md @@ -2,7 +2,7 @@ added: v12.12.0 --> -代表目录流的类。 +表示目录流的类。 由 [`fs.opendir()`]、[`fs.opendirSync()`] 或 [`fsPromises.opendir()`] 创建。 diff --git a/fs/class_fs_fswatcher.md b/fs/class_fs_fswatcher.md index 19164c75..4da577a9 100644 --- a/fs/class_fs_fswatcher.md +++ b/fs/class_fs_fswatcher.md @@ -4,7 +4,7 @@ added: v0.5.8 * 继承自 {EventEmitter} -成功调用 [`fs.watch()`] 方法将会返回一个新的 `fs.FSWatcher` 对象。 +成功调用 [`fs.watch()`] 方法会返回新建的 `fs.FSWatcher` 对象。 每当指定监视的文件被修改时，所有的 `fs.FSWatcher` 对象都会触发 `'change'` 事件。 diff --git a/fs/class_fs_readstream.md b/fs/class_fs_readstream.md index ee02542f..02e3f3c8 100644 --- a/fs/class_fs_readstream.md +++ b/fs/class_fs_readstream.md @@ -4,6 +4,6 @@ added: v0.1.93 * 继承自: {stream.Readable} -成功调用 `fs.createReadStream()` 将会返回一个新的 `fs.ReadStream` 对象。 +成功调用 `fs.createReadStream()` 会返回新建的 `fs.ReadStream` 对象。 diff --git a/fs/dir_close.md b/fs/dir_close.md index 825519ad..1118381f 100644 --- a/fs/dir_close.md +++ b/fs/dir_close.md @@ -5,7 +5,7 @@ added: v12.12.0 * 返回: {Promise} 异步地关闭目录的底层资源句柄。 -随后的读取将会导致错误。 +后续的读取会导致错误。 -返回一个 `Promise`，将会在关闭资源之后被解决。 +返回 `Promise`（在资源被关闭之后会被 resolve）。 diff --git a/fs/dir_close_callback.md b/fs/dir_close_callback.md index 0c47b40d..e0f0469b 100644 --- a/fs/dir_close_callback.md +++ b/fs/dir_close_callback.md @@ -6,7 +6,7 @@ added: v12.12.0 * `err` {Error} 异步地关闭目录的底层资源句柄。 -随后的读取将会导致错误。 +后续的读取会导致错误。 关闭资源句柄之后将会调用 `callback`。 diff --git a/fs/dir_closesync.md b/fs/dir_closesync.md index e33484c6..574c41d0 100644 --- a/fs/dir_closesync.md +++ b/fs/dir_closesync.md @@ -3,5 +3,5 @@ added: v12.12.0 --> 同步地关闭目录的底层资源句柄。 -随后的读取将会导致错误。 +后续的读取会导致错误。 diff --git a/fs/dir_read.md b/fs/dir_read.md index 134f06bf..85b5ba33 100644 --- a/fs/dir_read.md +++ b/fs/dir_read.md @@ -2,11 +2,11 @@ added: v12.12.0 --> -* 返回: {Promise} 包含 {fs.Dirent|null}。 +* 返回: 包含 {fs.Dirent|null} 的 {Promise} 通过 readdir(3) 异步地读取下一个目录项作为 [`fs.Dirent`]。 -读取完成之后，将会返回一个 `Promise`，它被解决时将会返回 [`fs.Dirent`] 或 `null`（如果没有更多的目录项要读取）。 +读取完成之后，则会返回 `Promise`（resolve 时会传入 [`fs.Dirent`] 或 `null`（如果读取不到目录项））。 此函数返回的目录项不遵循操作系统的底层目录机制所提供的特定顺序。 遍历目录时添加或删除的目录项可能会或可能不会包含在遍历的结果中。 diff --git a/fs/dir_read_callback.md b/fs/dir_read_callback.md index 0485f7fd..5e674da5 100644 --- a/fs/dir_read_callback.md +++ b/fs/dir_read_callback.md @@ -8,7 +8,7 @@ added: v12.12.0 通过 readdir(3) 异步地读取下一个目录项作为 [`fs.Dirent`]。 -读取完成之后，将会调用 `callback` 并传入 [`fs.Dirent`] 或 `null`（如果没有更多的目录项要读取）。 +读取完成之后，则会调用 `callback`（传入 [`fs.Dirent`] 或 `null`（如果读取不到目录项））。 此函数返回的目录项不遵循操作系统的底层目录机制所提供的特定顺序。 遍历目录时添加或删除的目录项可能会或可能不会包含在遍历的结果中。 diff --git a/fs/dir_readsync.md b/fs/dir_readsync.md index b973a273..b9d7f39a 100644 --- a/fs/dir_readsync.md +++ b/fs/dir_readsync.md @@ -6,7 +6,7 @@ added: v12.12.0 通过 readdir(3) 同步地读取下一个目录项作为 [`fs.Dirent`]。 -如果没有更多的目录项要读取，则将会返回 `null`。 +如果读取不到目录项，则将会返回 `null`。 此函数返回的目录项不遵循操作系统的底层目录机制所提供的特定顺序。 遍历目录时添加或删除的目录项可能会或可能不会包含在遍历的结果中。 diff --git a/fs/dirent_isfile.md b/fs/dirent_isfile.md index e952e301..28a5849a 100644 --- a/fs/dirent_isfile.md +++ b/fs/dirent_isfile.md @@ -4,5 +4,5 @@ added: v10.10.0 * 返回: {boolean} -如果 `fs.Dirent` 对象描述常规文件，则返回 `true`。 +如果 `fs.Dirent` 对象描述普通的文件，则返回 `true`。 diff --git a/fs/file_open_constants.md b/fs/file_open_constants.md index a6008010..01f3753f 100644 --- a/fs/file_open_constants.md +++ b/fs/file_open_constants.md @@ -32,7 +32,7 @@ O_TRUNC - 表明如果文件存在且是常规文件、并且文件成功打开以进行写入访问，则其长度应截断为零。 + 表明如果文件存在且是普通的文件、并且文件成功打开以进行写入访问，则其长度应截断为零。 O_APPEND diff --git a/fs/file_paths.md b/fs/file_paths.md index 9241ec67..1729fedb 100644 --- a/fs/file_paths.md +++ b/fs/file_paths.md @@ -1,15 +1,15 @@ -大多数 `fs` 操作接受的文件路径可以指定为字符串、[`Buffer`]、或使用 `file:` 协议的 [`URL`] 对象。 +大多数 `fs` 操作接受的文件路径可以指定为字符串、[`Buffer`]、或 [`URL`] 对象（使用 `file:` 协议）。 -字符串形式的路径被解析为标识绝对或相对文件名的 UTF-8 字符序列。 -相对路径将相对于 `process.cwd()` 指定的当前工作目录进行解析。 +字符串形式的路径会被解释为 UTF-8 字符序列（标识绝对或相对的文件名）。 +相对路径会相对于当前工作目录（由 `process.cwd()` 指定）进行处理。 在 POSIX 上使用绝对路径的示例： ```js const fs = require('fs'); -fs.open('/open/some/file.txt', 'r', (err, fd) => { +fs.open('/文件.txt', 'r', (err, fd) => { if (err) throw err; fs.close(fd, (err) => { if (err) throw err; @@ -20,7 +20,7 @@ fs.open('/open/some/file.txt', 'r', (err, fd) => { 在 POSIX 上使用相对路径（相对于 `process.cwd()`）的示例： ```js -fs.open('file.txt', 'r', (err, fd) => { +fs.open('文件.txt', 'r', (err, fd) => { if (err) throw err; fs.close(fd, (err) => { if (err) throw err; @@ -29,13 +29,13 @@ fs.open('file.txt', 'r', (err, fd) => { ``` 使用 [`Buffer`] 指定的路径主要用于将文件路径视为不透明字节序列的某些 POSIX 操作系统。 -在这样的系统上，单个文件路径可以包含使用多种字符编码的子序列。 -与字符串路径一样，`Buffer` 路径可以是相对路径或绝对路径： +在这些系统上，单个文件路径可以包含使用多种字符编码的子序列。 +与字符串路径一样，`Buffer` 路径也可以是相对或绝对的： 在 POSIX 上使用绝对路径的示例： ```js -fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => { +fs.open(Buffer.from('/文件.txt'), 'r', (err, fd) => { if (err) throw err; fs.close(fd, (err) => { if (err) throw err; @@ -43,8 +43,8 @@ fs.open(Buffer.from('/open/some/file.txt'), 'r', (err, fd) => { }); ``` -在 Windows 上，Node.js 遵循每个驱动器工作目录的概念。 +在 Windows 上，Node.js 遵循独立驱动器工作目录的概念。 当使用没有反斜杠的驱动器路径时，可以观察到此行为。 例如，`fs.readdirSync('C:\\')` 可能会返回与 `fs.readdirSync('C:')` 不同的结果。 -有关详细信息，参见[此 MSDN 页面][MSDN-Rel-Path]。 +详见[此 MSDN 页面][MSDN-Rel-Path]。 diff --git a/fs/file_system_flags.md b/fs/file_system_flags.md index eead974a..ce5f28dc 100644 --- a/fs/file_system_flags.md +++ b/fs/file_system_flags.md @@ -1,54 +1,63 @@ -当 `flag` 选项采用字符串时，可用以下标志： +当 `flag` 选项采用字符串时，则以下标志均可用： -* `'a'` - 打开文件用于追加。如果文件不存在，则创建该文件。 +* `'a'`: 打开文件用于追加。 + 如果文件不存在，则创建该文件。 -* `'ax'` - 与 `'a'` 相似，但如果路径已存在则失败。 +* `'ax'`: 类似于 `'a'`，但如果路径存在，则失败。 -* `'a+'` - 打开文件用于读取和追加。如果文件不存在，则创建该文件。 +* `'a+'`: 打开文件用于读取和追加。 + 如果文件不存在，则创建该文件。 -* `'ax+'` - 与 `'a+'` 相似，但如果路径已存在则失败。 +* `'ax+'`: 类似于 `'a+'`，但如果路径存在，则失败。 -* `'as'` - 以同步模式打开文件用于追加。如果文件不存在，则创建该文件。 +* `'as'`: 打开文件用于追加（在同步模式中）。 + 如果文件不存在，则创建该文件。 -* `'as+'` - 以同步模式打开文件用于读取和追加。如果文件不存在，则创建该文件。 +* `'as+'`: 打开文件用于读取和追加（在同步模式中）。 + 如果文件不存在，则创建该文件。 -* `'r'` - 打开文件用于读取。如果文件不存在，则出现异常。 +* `'r'`: 打开文件用于读取。 + 如果文件不存在，则会发生异常。 -* `'r+'` - 打开文件用于读取和写入。如果文件不存在，则出现异常。 +* `'r+'`: 打开文件用于读取和写入。 + 如果文件不存在，则会发生异常。 -* `'rs+'` - 以同步模式打开文件用于读取和写入。指示操作系统绕过本地的文件系统缓存。 +* `'rs+'`: 打开文件用于读取和写入（在同步模式中）。 + 指示操作系统绕过本地的文件系统缓存。 - 这对于在 NFS 挂载上打开文件时非常有用，因为它允许跳过可能过时的本地缓存。 - 它对 I/O 性能有非常实际的影响，因此除非需要，否则不建议使用此标志。 + 这对于在 NFS 挂载上打开文件时非常有用，因为它可以跳过可能过时的本地缓存。 + 它对 I/O 性能有非常实际的影响，因此不建议使用此标志（除非真的需要）。 - 这不会将 `fs.open()` 或 `fsPromises.open()` 转换为同步的阻塞调用。 + 这不会把 `fs.open()` 或 `fsPromises.open()` 变成同步的阻塞调用。 如果需要同步的操作，则应使用 `fs.openSync()` 之类的。 -* `'w'` - 打开文件用于写入。如果文件不存在则创建文件，如果文件已存在则截断文件。 +* `'w'`: 打开文件用于写入。 + 如果文件不存在则创建文件，如果文件存在则截断文件。 -* `'wx'` - 与 `'w'` 相似，但如果路径已存在则失败。 +* `'wx'`: 类似于 `'w'`，但如果路径存在，则失败。 -* `'w+'` - 打开文件用于读取和写入。如果文件不存在则创建文件，如果文件已存在则截断文件。 +* `'w+'`: 打开文件用于读取和写入。 + 如果文件不存在则创建文件，如果文件存在则截断文件。 -* `'wx+'` - 与 `'w+'` 相似，但如果路径已存在则失败。 +* `'wx+'`: 类似于 `'w+'`，但如果路径存在，则失败。 -`flag` 也可以是一个数字，参见 open(2) 文档。 +`flag` 也可以是数字，参见 open(2) 文档。 常用的常量可以从 `fs.constants` 获取。 -在 Windows 上，标志会被适当地转换为等效的标志，例如 `O_WRONLY` 转换为 `FILE_GENERIC_WRITE`、`O_EXCL|O_CREAT` 转换为能被 `CreateFileW` 接受的 `CREATE_NEW`。 +在 Windows 上，标志会被转换为合适的等效标志，例如 `O_WRONLY` 转换为 `FILE_GENERIC_WRITE`、`O_EXCL|O_CREAT` 转换为能被 `CreateFileW` 接受的 `CREATE_NEW`。 -特有的 `'x'` 标志（ open(2) 中的 `O_EXCL` 标志）可以确保路径是新创建的。 -在 POSIX 系统上，即使路径是一个符号链接且指向一个不存在的文件，它也会被视为已存在。 -该特有标志不一定适用于网络文件系统。 +排他性标志 `'x'`（ open(2) 中的 `O_EXCL` 标志）可以确保路径是新创建的。 +在 POSIX 系统上，即使路径是符号链接（指向不存在的文件），该路径也会被视为存在。 +排他性标志不一定适用于网络文件系统。 -在 Linux 上，当以追加模式打开文件时，写入无法指定位置。 -内核会忽略位置参数，并始终将数据追加到文件的末尾。 +在 Linux 上，当以追加模式打开文件时，则写入时无法指定位置。 +内核会忽略位置参数，并始终追加数据到文件的末尾。 如果要修改文件而不是覆盖文件，则 `flag` 选项需要被设置为 `'r+'` 而不是默认的 `'w'`。 -某些标志的行为是特定于平台的。 -例如，在 macOS 和 Linux 上使用 `'a+'` 标志打开目录（参见下面的示例）会返回一个错误。 -而在 Windows 和 FreeBSD 上，则返回一个文件描述符或 `FileHandle`。 +有些标志的行为是特定于平台的。 +例如，在 macOS 和 Linux 上使用 `'a+'` 标志打开目录会返回错误。 +但是，在 Windows 和 FreeBSD 上，则会返回文件描述符或 `FileHandle`。 ```js // 在 macOS 和 Linux 上： @@ -62,8 +71,8 @@ fs.open('<目录>', 'a+', (err, fd) => { }); ``` -在 Windows 上，使用 `'w'` 标志打开现存的隐藏文件（通过 `fs.open()`、`fs.writeFile()` 或 `fsPromises.open()`）会抛出 `EPERM`。 -现存的隐藏文件可以使用 `'r+'` 标志打开用于写入。 +在 Windows 上，使用 `'w'` 标志打开（通过 `fs.open()`、`fs.writeFile()` 或 `fsPromises.open()`）现有的隐藏文件，则会抛出 `EPERM`。 +现有的隐藏文件可以使用 `'r+'` 标志打开用于写入。 调用 `fs.ftruncate()` 或 `fsPromises.ftruncate()` 可以用于重置文件的内容。 diff --git a/fs/file_type_constants.md b/fs/file_type_constants.md index d8d1f35b..763832fa 100644 --- a/fs/file_type_constants.md +++ b/fs/file_type_constants.md @@ -12,7 +12,7 @@ S_IFREG - 表示常规文件。 + 表示普通的文件。 S_IFDIR diff --git a/fs/filehandle_read_buffer_offset_length_position.md b/fs/filehandle_read_buffer_offset_length_position.md index 04e0dbaf..1dea383d 100644 --- a/fs/filehandle_read_buffer_offset_length_position.md +++ b/fs/filehandle_read_buffer_offset_length_position.md @@ -13,11 +13,11 @@ added: v10.0.0 `offset` 是 buffer 中开始写入的偏移量。 -`length` 是一个整数，指定要读取的字节数。 +`length` 是整数，指定要读取的字节数。 `position` 参数指定从文件中开始读取的位置。 如果 `position` 为 `null`，则从当前文件位置读取数据，并更新文件位置。 -如果 `position` 是整数，则文件位置将保持不变。 +如果 `position` 是整数，则文件位置会保持不变。 成功读取之后，`Promise` 会被解决并带上一个对象，对象上有一个 `bytesRead` 属性（指定读取的字节数）和一个 `buffer` 属性（指向传入的 `buffer` 参数）。 diff --git a/fs/filehandle_write_buffer_offset_length_position.md b/fs/filehandle_write_buffer_offset_length_position.md index f3fa2bb3..08981078 100644 --- a/fs/filehandle_write_buffer_offset_length_position.md +++ b/fs/filehandle_write_buffer_offset_length_position.md @@ -12,19 +12,19 @@ changes: * `position` {integer} * 返回: {Promise} -将 `buffer` 写入到文件。 +写入 `buffer` 到文件。 `Promise` 会被解决并带上一个对象，对象包含一个 `bytesWritten` 属性（指定写入的字节数）和一个 `buffer` 属性（指向写入的 `buffer`）。 -`offset` 决定 buffer 中要被写入的部位，`length` 是一个整数，指定要写入的字节数。 +`offset` 决定 buffer 中要被写入的部位，`length` 是整数，指定要写入的字节数。 -`position` 指定文件开头的偏移量（数据应该被写入的位置）。 +`position` 指定文件开头的偏移量（数据要被写入的位置）。 如果 `typeof position !== 'number'`，则数据会被写入当前的位置。 参见 pwrite(2)。 在同一个文件上多次使用 `filehandle.write()` 且不等待 `Promise` 被解决（或被拒绝）是不安全的。 对于这种情况，建议使用 [`fs.createWriteStream()`]。 -在 Linux 上，当以追加模式打开文件时，写入无法指定位置。 -内核会忽略位置参数，并始终将数据追加到文件的末尾。 +在 Linux 上，当以追加模式打开文件时，则写入时无法指定位置。 +内核会忽略位置参数，并始终追加数据到文件的末尾。 diff --git a/fs/filehandle_write_string_position_encoding.md b/fs/filehandle_write_string_position_encoding.md index 225cd958..5a8f1b21 100644 --- a/fs/filehandle_write_string_position_encoding.md +++ b/fs/filehandle_write_string_position_encoding.md @@ -18,7 +18,7 @@ changes: `Promise` 会被解决并带上一个对象，对象包含一个 `bytesWritten` 属性（指定写入的字节数）和一个 `buffer` 属性（指向写入的 `string`）。 -`position` 指定文件开头的偏移量（数据应该被写入的位置）。 +`position` 指定文件开头的偏移量（数据要被写入的位置）。 如果 `position` 的类型不是一个 `number`，则数据会被写入当前的位置。 参见 pwrite(2)。 @@ -27,6 +27,6 @@ changes: 在同一个文件上多次使用 `filehandle.write()` 且不等待 `Promise` 被解决（或被拒绝）是不安全的。 对于这种情况，建议使用 [`fs.createWriteStream()`]。 -在 Linux 上，当以追加模式打开文件时，写入无法指定位置。 -内核会忽略位置参数，并始终将数据追加到文件的末尾。 +在 Linux 上，当以追加模式打开文件时，则写入时无法指定位置。 +内核会忽略位置参数，并始终追加数据到文件的末尾。 diff --git a/fs/filehandle_writev_buffers_position.md b/fs/filehandle_writev_buffers_position.md index 0855d19e..ac877bfd 100644 --- a/fs/filehandle_writev_buffers_position.md +++ b/fs/filehandle_writev_buffers_position.md @@ -10,11 +10,11 @@ added: v12.9.0 `Promise` 会被解决并带上一个对象，对象包含一个 `bytesWritten` 属性（表明写入的字节数）和一个 `buffers` 属性（指向 `buffers` 输入）。 -`position` 指定文件开头的偏移量（数据应该被写入的位置）。 +`position` 指定文件开头的偏移量（数据要被写入的位置）。 如果 `typeof position !== 'number'`，则数据会被写入当前的位置。 在同一文件上多次调用 `writev()` 且不等待前面的操作完成，这是不安全的。 -在 Linux 上，当以追加模式打开文件时，写入无法指定位置。 -内核会忽略位置参数，并始终将数据追加到文件的末尾。 +在 Linux 上，当以追加模式打开文件时，则写入时无法指定位置。 +内核会忽略位置参数，并始终追加数据到文件的末尾。 diff --git a/fs/fs_access_path_mode_callback.md b/fs/fs_access_path_mode_callback.md index 928908e9..fc2aa07f 100644 --- a/fs/fs_access_path_mode_callback.md +++ b/fs/fs_access_path_mode_callback.md @@ -7,12 +7,8 @@ changes: 该支持目前仍是实验的。 - version: v6.3.0 pr-url: https://github.com/nodejs/node/pull/6534 - description: The constants like `fs.R_OK`, etc which were present directly - on `fs` were moved into `fs.constants` as a soft deprecation. - Thus for Node.js `< v6.3.0` use `fs` - to access those constants, or - do something like `(fs.constants || fs).R_OK` to work with all - versions. + description: 直接存在于 `fs` 上的常数（如 `fs.R_OK` 等）已被移到 `fs.constants`（软弃用）。 + 因此，对于 Node.js `< v6.3.0`，可以使用 `fs` 访问这些常量，或类似 `(fs.constants || fs).R_OK` 的处理以兼容所有版本。 --> * `path` {string|Buffer|URL} @@ -22,17 +18,17 @@ changes: 测试用户对 `path` 指定的文件或目录的权限。 `mode` 参数是一个可选的整数，指定要执行的可访问性检查。 -`mode` 可选的值参见[文件可访问性的常量][File Access Constants]。 +查看[文件可访问性的常量][File Access Constants]了解 `mode` 的可选值。 可以创建由两个或更多个值按位或组成的掩码（例如 `fs.constants.W_OK | fs.constants.R_OK`）。 -最后一个参数 `callback` 是一个回调函数，调用时将传入可能的错误参数。 -如果可访问性检查失败，则错误参数将是 `Error` 对象。 -以下示例检查 `package.json` 是否存在，以及它是否可读或可写。 +最后一个参数 `callback` 是回调函数，调用时会传入可能的错误参数。 +如果任何可访问性检查失败，则错误参数会是 `Error` 对象。 +以下示例会检查 `package.json` 是否存在、以及是否可读或可写。 ```js const file = 'package.json'; -// 检查当前目录中是否存在该文件。 +// 检查文件是否存在于当前目录中。 fs.access(file, fs.constants.F_OK, (err) => { console.log(`${file} ${err ? '不存在' : '存在'}`); }); @@ -47,31 +43,31 @@ fs.access(file, fs.constants.W_OK, (err) => { console.log(`${file} ${err ? '不可写' : '可写'}`); }); -// 检查当前目录中是否存在该文件，以及该文件是否可写。 +// 检查文件是否存在于当前目录中、以及是否可写。 fs.access(file, fs.constants.F_OK | fs.constants.W_OK, (err) => { if (err) { console.error( `${file} ${err.code === 'ENOENT' ? '不存在' : '只可读'}`); } else { - console.log(`${file} 存在，且它是可写的`); + console.log(`${file} 存在，且可写`); } }); ``` 不建议在调用 `fs.open()`、`fs.readFile()` 或 `fs.writeFile()` 之前使用 `fs.access()` 检查文件的可访问性。 这样做会引入竞态条件，因为其他进程可能会在两个调用之间更改文件的状态。 -相反，应该直接打开、读取或写入文件，如果文件无法访问则处理引发的错误。 +而是，应该直接打开、读取或写入文件，并且当文件无法访问时处理引发的错误。 **写入（不推荐）** ```js -fs.access('myfile', (err) => { +fs.access('文件', (err) => { if (!err) { - console.error('myfile 已存在'); + console.error('文件已存在'); return; } - fs.open('myfile', 'wx', (err, fd) => { + fs.open('文件', 'wx', (err, fd) => { if (err) throw err; writeMyData(fd); }); @@ -81,10 +77,10 @@ fs.access('myfile', (err) => { **写入（推荐）** ```js -fs.open('myfile', 'wx', (err, fd) => { +fs.open('文件', 'wx', (err, fd) => { if (err) { if (err.code === 'EEXIST') { - console.error('myfile 已存在'); + console.error('文件已存在'); return; } @@ -98,17 +94,17 @@ fs.open('myfile', 'wx', (err, fd) => { **读取（不推荐）** ```js -fs.access('myfile', (err) => { +fs.access('文件', (err) => { if (err) { if (err.code === 'ENOENT') { - console.error('myfile 不存在'); + console.error('文件不存在'); return; } throw err; } - fs.open('myfile', 'r', (err, fd) => { + fs.open('文件', 'r', (err, fd) => { if (err) throw err; readMyData(fd); }); @@ -118,10 +114,10 @@ fs.access('myfile', (err) => { **读取（推荐）** ```js -fs.open('myfile', 'r', (err, fd) => { +fs.open('文件', 'r', (err, fd) => { if (err) { if (err.code === 'ENOENT') { - console.error('myfile 不存在'); + console.error('文件不存在'); return; } @@ -135,8 +131,8 @@ fs.open('myfile', 'r', (err, fd) => { 上面的“不推荐”示例会先检查可访问性，然后再使用文件。 “推荐”示例则更好，因为它们直接使用文件并处理错误（如果有错误的话）。 -通常，仅在不直接使用文件时才检查文件的可访问性，例如当其可访问性是来自其他进程的信号时。 +通常，仅在不直接使用文件时（例如当其可访问性是来自其他进程的信号时），才检查文件的可访问性。 在 Windows 上，目录上的访问控制策略（ACL）可能会限制对文件或目录的访问。 -但是，`fs.access()` 函数不检查 ACL，因此即使 ACL 限制用户读取或写入路径，也可能报告路径是可访问的。 +但是，`fs.access()` 函数不检查 ACL，因此即使 ACL 限制用户读取或写入，也可能报告路径是可访问的。 diff --git a/fs/fs_accesssync_path_mode.md b/fs/fs_accesssync_path_mode.md index 6abcbe28..4a758e6a 100644 --- a/fs/fs_accesssync_path_mode.md +++ b/fs/fs_accesssync_path_mode.md @@ -12,7 +12,7 @@ changes: 同步地测试用户对 `path` 指定的文件或目录的权限。 `mode` 参数是一个可选的整数，指定要执行的可访问性检查。 -`mode` 可选的值参见[文件可访问性的常量][File Access Constants]。 +查看[文件可访问性的常量][File Access Constants]了解 `mode` 的可选值。 可以创建由两个或更多个值按位或组成的掩码（例如 `fs.constants.W_OK | fs.constants.R_OK`）。 如果可访问性检查失败，则抛出 `Error`。 diff --git a/fs/fs_appendfile_path_data_options_callback.md b/fs/fs_appendfile_path_data_options_callback.md index f63aec03..4db8dd4d 100644 --- a/fs/fs_appendfile_path_data_options_callback.md +++ b/fs/fs_appendfile_path_data_options_callback.md @@ -26,27 +26,27 @@ changes: * `callback` {Function} * `err` {Error} -异步地将数据追加到文件，如果文件尚不存在则创建该文件。 +异步地追加数据到文件，如果文件尚不存在则创建文件。 `data` 可以是字符串或 [`Buffer`]。 ```js -fs.appendFile('message.txt', '追加的数据', (err) => { +fs.appendFile('文件.txt', '追加的数据', (err) => { if (err) throw err; - console.log('数据已追加到文件'); + console.log('数据已被追加到文件'); }); ``` 如果 `options` 是字符串，则它指定字符编码： ```js -fs.appendFile('message.txt', '追加的数据', 'utf8', callback); +fs.appendFile('文件.txt', '追加的数据', 'utf8', callback); ``` `path` 可以指定为已打开用于追加（使用 `fs.open()` 或 `fs.openSync()`）的数字型文件描述符。 文件描述符不会自动关闭。 ```js -fs.open('message.txt', 'a', (err, fd) => { +fs.open('文件.txt', 'a', (err, fd) => { if (err) throw err; fs.appendFile(fd, '追加的数据', 'utf8', (err) => { fs.close(fd, (err) => { diff --git a/fs/fs_appendfilesync_path_data_options.md b/fs/fs_appendfilesync_path_data_options.md index b38335da..a7ae838b 100644 --- a/fs/fs_appendfilesync_path_data_options.md +++ b/fs/fs_appendfilesync_path_data_options.md @@ -21,8 +21,8 @@ changes: ```js try { - fs.appendFileSync('message.txt', '追加的数据'); - console.log('数据已追加到文件'); + fs.appendFileSync('文件.txt', '追加的数据'); + console.log('数据已被追加到文件'); } catch (err) { /* 处理错误 */ } @@ -31,7 +31,7 @@ try { 如果 `options` 是字符串，则它指定字符编码： ```js -fs.appendFileSync('message.txt', '追加的数据', 'utf8'); +fs.appendFileSync('文件.txt', '追加的数据', 'utf8'); ``` `path` 可以指定为已打开用于追加（使用 `fs.open()` 或 `fs.openSync()`）的数字型文件描述符。 @@ -41,7 +41,7 @@ fs.appendFileSync('message.txt', '追加的数据', 'utf8'); let fd; try { - fd = fs.openSync('message.txt', 'a'); + fd = fs.openSync('文件.txt', 'a'); fs.appendFileSync(fd, '追加的数据', 'utf8'); } catch (err) { /* 处理错误 */ diff --git a/fs/fs_mkdir_path_options_callback.md b/fs/fs_mkdir_path_options_callback.md index 8045bd9b..a5a64e46 100644 --- a/fs/fs_mkdir_path_options_callback.md +++ b/fs/fs_mkdir_path_options_callback.md @@ -3,12 +3,10 @@ added: v0.1.8 changes: - version: v13.11.0 pr-url: https://github.com/nodejs/node/pull/31530 - description: In `recursive` mode, the callback now receives the first - created path as an argument. + description: 在 `recursive` 模式中，回调会接收创建的第一个路径作为参数。 - version: v10.12.0 pr-url: https://github.com/nodejs/node/pull/21875 - description: The second argument can now be an `options` object with - `recursive` and `mode` properties. + description: 第二个参数可以是 `options` 对象（具有 `recursive` 和 `mode` 属性）。 - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/12562 description: 参数 `callback` 不再是可选的。 @@ -26,24 +24,25 @@ changes: * `path` {string|Buffer|URL} * `options` {Object|integer} * `recursive` {boolean} **默认值:** `false`。 - * `mode` {string|integer} Windows 上不支持。**默认值:** `0o777`。 + * `mode` {string|integer} 在 Windows 上不支持。**默认值:** `0o777`。 * `callback` {Function} * `err` {Error} 异步地创建目录。 -回调会带上可能的异常，如果 `recursive` 为 `true`，则会带上创建的第一个目录的路径，`(err, [path])`。 +回调会传入可能的异常、以及创建的第一个目录的路径（如果 `recursive` 为 `true`），`(err, [path])`。 -可选的 `options` 参数可以是指定模式（权限和粘滞位）的整数，也可以是具有 `mode` 属性和 `recursive` 属性（指示是否应创建父目录）的对象。 +可选的 `options` 参数可以是整数（指定 `mode`（权限和粘滞位））、或对象（具有 `mode` 属性和 `recursive` 属性（指示是否要创建父目录））。 +当 `path` 是已存在的目录时，调用 `fs.mkdir()` 仅在 `recursive` 为 false 时才会导致错误。 ```js -// 创建 /tmp/a/apple 目录，无论是否存在 /tmp 和 /tmp/a 目录。 -fs.mkdir('/tmp/a/apple', { recursive: true }, (err) => { +// 创建 `/目录1/目录2/目录3`，不管 `/目录1` 和 `/目录1/目录2` 是否存在。 +fs.mkdir('/目录1/目录2/目录3', { recursive: true }, (err) => { if (err) throw err; }); ``` -在 Windows 上，在根目录上使用 `fs.mkdir()` （即使使用递归参数）也会导致错误： +在 Windows 上，对根目录使用 `fs.mkdir()`（即使使用遍历）也会导致错误： ```js fs.mkdir('/', { recursive: true }, (err) => { diff --git a/fs/fs_mkdirsync_path_options.md b/fs/fs_mkdirsync_path_options.md index 06b2a25f..d8f0c651 100644 --- a/fs/fs_mkdirsync_path_options.md +++ b/fs/fs_mkdirsync_path_options.md @@ -3,11 +3,10 @@ added: v0.1.21 changes: - version: v13.11.0 pr-url: https://github.com/nodejs/node/pull/31530 - description: In `recursive` mode, the first created path is returned now. + description: 在 `recursive` 模式中，会返回创建的第一个路径。 - version: v10.12.0 pr-url: https://github.com/nodejs/node/pull/21875 - description: The second argument can now be an `options` object with - `recursive` and `mode` properties. + description: 第二个参数可以是 `options` 对象（具有 `recursive` 和 `mode` 属性）。 - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 description: 参数 `path` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 @@ -17,12 +16,12 @@ changes: * `path` {string|Buffer|URL} * `options` {Object|integer} * `recursive` {boolean} **默认值:** `false`。 - * `mode` {string|integer} Windows 上不支持。**默认值:** `0o777`。 + * `mode` {string|integer} 在 Windows 上不支持。**默认值:** `0o777`。 * 返回: {string|undefined} 同步地创建目录。 -返回 `undefined`，或者如果 `recursive` 为 `true`，则返回创建的第一个目录的路径。 -[`fs.mkdir()`] 的同步版本。 +返回 `undefined`，或创建的第一个目录的路径（如果 `recursive` 为 `true`）。 +这是 [`fs.mkdir()`] 的同步版本。 也可参见 mkdir(2)。 diff --git a/fs/fs_open_path_flags_mode_callback.md b/fs/fs_open_path_flags_mode_callback.md index d4f2bff3..5e360547 100644 --- a/fs/fs_open_path_flags_mode_callback.md +++ b/fs/fs_open_path_flags_mode_callback.md @@ -3,10 +3,10 @@ added: v0.0.2 changes: - version: v11.1.0 pr-url: https://github.com/nodejs/node/pull/23767 - description: The `flags` argument is now optional and defaults to `'r'`. + description: 参数 `flags` 是可选的，并且默认为 `'r'`。 - version: v9.9.0 pr-url: https://github.com/nodejs/node/pull/18801 - description: The `as` and `as+` flags are supported now. + description: 支持 `as` 和 `as+` 标志。 - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 description: 参数 `path` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 @@ -14,13 +14,15 @@ changes: --> * `path` {string|Buffer|URL} -* `flags` {string|number} 参见[文件系统 `flag` 的支持][support of file system `flags`]。**默认值:** `'r'`。 +* `flags` {string|number} 参见[文件系统 `flag` 的支持][support of file system `flags`]。 + **默认值:** `'r'`。 * `mode` {string|integer} **默认值:** `0o666`（可读写）。 * `callback` {Function} * `err` {Error} * `fd` {integer} -异步地打开文件。参见 open(2)。 +异步地打开文件。 +参见 open(2)。 `mode` 用于设置文件模式（权限和粘滞位），但仅限于创建文件时。 在 Windows 上，只能操作写权限，参见 [`fs.chmod()`]。 @@ -28,7 +30,7 @@ changes: 回调有两个参数 `(err, fd)`。 有些字符 (`< > : " / \ | ? *`) 在 Windows 上是预留的，参见[命名文件、路径以及命名空间][Naming Files, Paths, and Namespaces]。 -在 NTFS 上，如果文件名包含冒号，则 Node.js 将打开文件系统流，参见[此 MSDN 页面][MSDN-Using-Streams]。 +在 NTFS 上，如果文件名包含冒号，则 Node.js 会打开文件系统流，参见[此 MSDN 页面][MSDN-Using-Streams]。 -基于 `fs.open()` 的函数也表现出以上行为，比如 `fs.writeFile()`、`fs.readFile()` 等。 +基于 `fs.open()` 的函数也会表现出以上行为，比如 `fs.writeFile()`、`fs.readFile()` 等。 diff --git a/fs/fs_opensync_path_flags_mode.md b/fs/fs_opensync_path_flags_mode.md index fd6fc575..571b7221 100644 --- a/fs/fs_opensync_path_flags_mode.md +++ b/fs/fs_opensync_path_flags_mode.md @@ -3,10 +3,10 @@ added: v0.1.21 changes: - version: v11.1.0 pr-url: https://github.com/nodejs/node/pull/23767 - description: The `flags` argument is now optional and defaults to `'r'`. + description: 参数 `flags` 是可选的，并且默认为 `'r'`。 - version: v9.9.0 pr-url: https://github.com/nodejs/node/pull/18801 - description: The `as` and `as+` flags are supported now. + description: 支持 `as` 和 `as+` 标志。 - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 description: 参数 `path` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 diff --git a/fs/fs_read_fd_buffer_offset_length_position_callback.md b/fs/fs_read_fd_buffer_offset_length_position_callback.md index 4874592a..e19af018 100644 --- a/fs/fs_read_fd_buffer_offset_length_position_callback.md +++ b/fs/fs_read_fd_buffer_offset_length_position_callback.md @@ -3,14 +3,13 @@ added: v0.0.2 changes: - version: v10.10.0 pr-url: https://github.com/nodejs/node/pull/22150 - description: The `buffer` parameter can now be any `TypedArray`, or a - `DataView`. + description: 参数 `buffer` 可以是任何 `TypedArray` 或 `DataView`。 - version: v7.4.0 pr-url: https://github.com/nodejs/node/pull/10382 - description: The `buffer` parameter can now be a `Uint8Array`. + description: 参数 `buffer` 可以是 `Uint8Array`。 - version: v6.0.0 pr-url: https://github.com/nodejs/node/pull/4518 - description: The `length` parameter can now be `0`. + description: 参数 `length` 可以为 `0`。 --> * `fd` {integer} @@ -25,17 +24,17 @@ changes: 从 `fd` 指定的文件中读取数据。 -`buffer` 是数据（从 fd 读取）将写入的缓冲区。 +`buffer` 是数据（从 fd 读取）要被写入的 buffer。 `offset` 是 buffer 中开始写入的偏移量。 -`length` 是一个整数，指定要读取的字节数。 +`length` 是整数，指定要读取的字节数。 `position` 参数指定从文件中开始读取的位置。 如果 `position` 为 `null`，则从当前文件位置读取数据，并更新文件位置。 -如果 `position` 是整数，则文件位置将保持不变。 +如果 `position` 是整数，则文件位置会保持不变。 回调有三个参数 `(err, bytesRead, buffer)`。 -如果调用此方法的 [`util.promisify()`] 版本，则返回的 `Promise` 会返回具有 `bytesRead` 属性和 `buffer` 属性的 `Object`。 +如果调用此方法的 [`util.promisify()`] 版本，则返回 `Promise`（会传入具有 `bytesRead` 属性和 `buffer` 属性的 `Object`）。 diff --git a/fs/fs_readdir_path_options_callback.md b/fs/fs_readdir_path_options_callback.md index 14eca0f1..41ecf9fe 100644 --- a/fs/fs_readdir_path_options_callback.md +++ b/fs/fs_readdir_path_options_callback.md @@ -3,7 +3,7 @@ added: v0.1.8 changes: - version: v10.10.0 pr-url: https://github.com/nodejs/node/pull/22020 - description: New option `withFileTypes` was added. + description: 添加新的选项 `withFileTypes`。 - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/12562 description: 参数 `callback` 不再是可选的。 @@ -18,7 +18,7 @@ changes: 如果不传入，则会触发弃用警告（id 为 DEP0013）。 - version: v6.0.0 pr-url: https://github.com/nodejs/node/pull/5616 - description: The `options` parameter was added. + description: 添加 `options` 参数。 --> * `path` {string|Buffer|URL} @@ -31,10 +31,10 @@ changes: 异步的 readdir(3)。 读取目录的内容。 -回调有两个参数 `(err, files)`，其中 `files` 是目录中的文件名的数组（不包括 `'.'` 和 `'..'`）。 +回调有两个参数 `(err, files)`，其中 `files` 是目录中文件的名称的数组（不包括 `'.'` 和 `'..'`）。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于传给回调的文件名的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的文件名是 `Buffer` 对象。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于传给回调的文件名的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的文件名会作为 `Buffer` 对象传入。 -如果 `options.withFileTypes` 设置为 `true`，则 `files` 数组将包含 [`fs.Dirent`] 对象。 +如果 `options.withFileTypes` 被设置为 `true`，则 `files` 数组会包含 [`fs.Dirent`] 对象。 diff --git a/fs/fs_readdirsync_path_options.md b/fs/fs_readdirsync_path_options.md index d327ba36..bd2f4070 100644 --- a/fs/fs_readdirsync_path_options.md +++ b/fs/fs_readdirsync_path_options.md @@ -3,7 +3,7 @@ added: v0.1.21 changes: - version: v10.10.0 pr-url: https://github.com/nodejs/node/pull/22020 - description: New option `withFileTypes` was added. + description: 添加新的选项 `withFileTypes`。 - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 description: 参数 `path` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 @@ -18,8 +18,8 @@ changes: 同步的 readdir(3)。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于传给回调的文件名的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的文件名是 `Buffer` 对象。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于返回的文件名的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的文件名会作为 `Buffer` 对象传入。 -如果 `options.withFileTypes` 设置为 `true`，则返回的结果将包含 [`fs.Dirent`] 对象。 +如果 `options.withFileTypes` 被设置为 `true`，则结果会包含 [`fs.Dirent`] 对象。 diff --git a/fs/fs_readlink_path_options_callback.md b/fs/fs_readlink_path_options_callback.md index cb80afd7..5bc84976 100644 --- a/fs/fs_readlink_path_options_callback.md +++ b/fs/fs_readlink_path_options_callback.md @@ -25,6 +25,6 @@ changes: 异步的 readlink(2)。 回调会传入两个参数 `(err, linkString)`。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于传递给回调的链接路径的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的链接路径将作为 `Buffer` 对象传入。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于传给回调的链接路径的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的链接路径会作为 `Buffer` 对象传入。 diff --git a/fs/fs_readlinksync_path_options.md b/fs/fs_readlinksync_path_options.md index c4492f68..8bbacd38 100644 --- a/fs/fs_readlinksync_path_options.md +++ b/fs/fs_readlinksync_path_options.md @@ -15,7 +15,7 @@ changes: 同步的 readlink(2)。 返回符号链接的字符串值。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于传递给回调的链接路径的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的链接路径将作为 `Buffer` 对象传入。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于返回的链接路径的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的链接路径会作为 `Buffer` 对象传入。 diff --git a/fs/fs_readsync_fd_buffer_offset_length_position.md b/fs/fs_readsync_fd_buffer_offset_length_position.md index 147c24b5..65b6b0a3 100644 --- a/fs/fs_readsync_fd_buffer_offset_length_position.md +++ b/fs/fs_readsync_fd_buffer_offset_length_position.md @@ -3,11 +3,10 @@ added: v0.1.21 changes: - version: v10.10.0 pr-url: https://github.com/nodejs/node/pull/22150 - description: The `buffer` parameter can now be any `TypedArray` or a - `DataView`. + description: 参数 `buffer` 可以是任何 `TypedArray` 或 `DataView`。 - version: v6.0.0 pr-url: https://github.com/nodejs/node/pull/4518 - description: The `length` parameter can now be `0`. + description: 参数 `length` 可以为 `0`。 --> * `fd` {integer} diff --git a/fs/fs_realpath_native_path_options_callback.md b/fs/fs_realpath_native_path_options_callback.md index 49b47a4f..c6c12b88 100644 --- a/fs/fs_realpath_native_path_options_callback.md +++ b/fs/fs_realpath_native_path_options_callback.md @@ -16,8 +16,8 @@ added: v9.2.0 仅支持可转换为 UTF8 字符串的路径。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于传递给回调的路径的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的路径将作为 `Buffer` 对象传入。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于传给回调的路径的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的路径会作为 `Buffer` 对象传入。 在 Linux 上，当 Node.js 与 musl libc 链接时，procfs 文件系统必须挂载在 `/proc` 上才能使此功能正常工作。 Glibc 没有这个限制。 diff --git a/fs/fs_realpath_path_options_callback.md b/fs/fs_realpath_path_options_callback.md index d1b3541f..410b8d38 100644 --- a/fs/fs_realpath_path_options_callback.md +++ b/fs/fs_realpath_path_options_callback.md @@ -48,8 +48,8 @@ changes: 仅支持可转换为 UTF8 字符串的路径。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于传递给回调的路径的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的路径将作为 `Buffer` 对象传入。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于传给回调的路径的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的路径会作为 `Buffer` 对象传入。 如果 `path` 解析为套接字或管道，则该函数将返回该对象的系统相关名称。 diff --git a/fs/fs_realpathsync_native_path_options.md b/fs/fs_realpathsync_native_path_options.md index 5f7144af..4129eaed 100644 --- a/fs/fs_realpathsync_native_path_options.md +++ b/fs/fs_realpathsync_native_path_options.md @@ -11,8 +11,8 @@ added: v9.2.0 仅支持可转换为 UTF8 字符串的路径。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于传递给回调的路径的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的路径将作为 `Buffer` 对象传入。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于返回的路径的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的路径会作为 `Buffer` 对象传入。 在 Linux 上，当 Node.js 与 musl libc 链接时，procfs 文件系统必须挂载在 `/proc` 上才能使此功能正常工作。 Glibc 没有这个限制。 diff --git a/fs/fs_rename_oldpath_newpath_callback.md b/fs/fs_rename_oldpath_newpath_callback.md index 4551fb7b..056ff99f 100644 --- a/fs/fs_rename_oldpath_newpath_callback.md +++ b/fs/fs_rename_oldpath_newpath_callback.md @@ -7,9 +7,8 @@ changes: 如果不传入，则在运行时会抛出 `TypeError`。 - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 - description: The `oldPath` and `newPath` parameters can be WHATWG `URL` - objects using `file:` protocol. Support is currently still - *experimental*. + description: 参数 `oldPath` 和 `newPath` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 + 该支持目前仍是实验的。 - version: v7.0.0 pr-url: https://github.com/nodejs/node/pull/7897 description: 参数 `callback` 不再是可选的。 @@ -21,7 +20,7 @@ changes: * `callback` {Function} * `err` {Error} -异步地将 `oldPath` 上的文件重命名为 `newPath` 提供的路径名。 +异步地把 `oldPath` 文件重命名为 `newPath` 提供的路径名。 如果 `newPath` 已存在，则覆盖它。 除了可能的异常，完成回调没有其他参数。 diff --git a/fs/fs_renamesync_oldpath_newpath.md b/fs/fs_renamesync_oldpath_newpath.md index e7c2d741..7b566827 100644 --- a/fs/fs_renamesync_oldpath_newpath.md +++ b/fs/fs_renamesync_oldpath_newpath.md @@ -3,9 +3,8 @@ added: v0.1.21 changes: - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 - description: The `oldPath` and `newPath` parameters can be WHATWG `URL` - objects using `file:` protocol. Support is currently still - *experimental*. + description: 参数 `oldPath` 和 `newPath` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 + 该支持目前仍是实验的。 --> * `oldPath` {string|Buffer|URL} diff --git a/fs/fs_rmdir_path_options_callback.md b/fs/fs_rmdir_path_options_callback.md index eb6bfa66..af03d978 100644 --- a/fs/fs_rmdir_path_options_callback.md +++ b/fs/fs_rmdir_path_options_callback.md @@ -5,42 +5,46 @@ changes: - v13.3.0 - v12.16.0 pr-url: https://github.com/nodejs/node/pull/30644 - description: The `maxBusyTries` option is renamed to `maxRetries`, and its - default is 0. The `emfileWait` option has been removed, and - `EMFILE` errors use the same retry logic as other errors. The - `retryDelay` option is now supported. `ENFILE` errors are now - retried. + description: 选项 `maxBusyTries` 被重命名为 `maxRetries`，并且默认值为 0。 + `emfileWait` 选项已被删除，并且 `EMFILE` 错误使用与其他错误相同的重试逻辑。 + 支持 `retryDelay` 选项。 + `ENFILE` 错误会被重试。 - version: v12.10.0 pr-url: https://github.com/nodejs/node/pull/29168 - description: The `recursive`, `maxBusyTries`, and `emfileWait` options are - now supported. + description: 支持 `recursive`、`maxBusyTries` 和 `emfileWait` 选项。 - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/12562 description: 参数 `callback` 不再是可选的。 如果不传入，则在运行时会抛出 `TypeError`。 - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 - description: The `path` parameters can be a WHATWG `URL` object using - `file:` protocol. Support is currently still *experimental*. + description: 参数 `path` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 + 该支持目前仍是实验的。 - version: v7.0.0 pr-url: https://github.com/nodejs/node/pull/7897 description: 参数 `callback` 不再是可选的。 如果不传入，则会触发弃用警告（id 为 DEP0013）。 --> -> 稳定性: 1 - 递归的删除是实验性的。 +> 稳定性: 1 - 递归的删除是实验的。 * `path` {string|Buffer|URL} * `options` {Object} - * `maxRetries` {integer} 如果遇到 `EBUSY`、`EMFILE`、`ENFILE`、`ENOTEMPTY` 或 `EPERM` 错误，则 Node.js 将会在每次尝试时以 `retryDelay` 毫秒的线性回退来重试该操作。 - 此选项表示重试的次数。如果 `recursive` 选项不为 `true`，则忽略此选项。**默认值:** `0`。 - * `recursive` {boolean} 如果为 `true`，则执行递归的目录删除。在递归模式中，如果 `path` 不存在则不报告错误，并且在失败时重试操作。**默认值:** `false`。 - * `retryDelay` {integer} 重试之间等待的时间（以毫秒为单位）。如果 `recursive` 选项不为 `true`，则忽略此选项。**默认值:** `100`。 + * `maxRetries` {integer} 如果遇到 `EBUSY`、`EMFILE`、`ENFILE`、`ENOTEMPTY` 或 `EPERM` 错误，则 Node.js 会重试该操作（每次尝试时使用 `retryDelay` 毫秒时长的线性回退等待）。 + 此选项表示重试的次数。 + 如果 `recursive` 选项不为 `true`，则此选项会被忽略。 + **默认值:** `0`。 + * `recursive` {boolean} 如果为 `true`，则执行递归的目录删除。 + 在递归模式中，错误不会被报告（如果 `path` 不存在），并且操作会被重试（当失败时）。 + **默认值:** `false`。 + * `retryDelay` {integer} 重试之间等待的时间（以毫秒为单位）。 + 如果 `recursive` 选项不为 `true`，则此选项会被忽略。 + **默认值:** `100`。 * `callback` {Function} * `err` {Error} 异步的 rmdir(2)。 除了可能的异常，完成回调没有其他参数。 -在文件（而不是目录）上使用 `fs.rmdir()` 会导致在 Windows 上出现 `ENOENT` 错误、在 POSIX 上出现 `ENOTDIR` 错误。 +对文件（而不是目录）使用 `fs.rmdir()` 会导致 `ENOENT` 错误（在 Windows 上）或 `ENOTDIR` 错误（在 POSIX 上）。 diff --git a/fs/fs_rmdirsync_path_options.md b/fs/fs_rmdirsync_path_options.md index 8a320328..68149570 100644 --- a/fs/fs_rmdirsync_path_options.md +++ b/fs/fs_rmdirsync_path_options.md @@ -5,32 +5,36 @@ changes: - v13.3.0 - v12.16.0 pr-url: https://github.com/nodejs/node/pull/30644 - description: The `maxBusyTries` option is renamed to `maxRetries`, and its - default is 0. The `emfileWait` option has been removed, and - `EMFILE` errors use the same retry logic as other errors. The - `retryDelay` option is now supported. `ENFILE` errors are now - retried. + description: 选项 `maxBusyTries` 被重命名为 `maxRetries`，并且默认值为 0。 + `emfileWait` 选项已被删除，并且 `EMFILE` 错误使用与其他错误相同的重试逻辑。 + 支持 `retryDelay` 选项。 + `ENFILE` 错误会被重试。 - version: v12.10.0 pr-url: https://github.com/nodejs/node/pull/29168 - description: The `recursive`, `maxBusyTries`, and `emfileWait` options are - now supported. + description: 支持 `recursive`、`maxBusyTries` 和 `emfileWait` 选项。 - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 - description: The `path` parameters can be a WHATWG `URL` object using - `file:` protocol. Support is currently still *experimental*. + description: 参数 `path` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 + 该支持目前仍是实验的。 --> > 稳定性: 1 - 递归的删除是实验性的。 * `path` {string|Buffer|URL} * `options` {Object} - * `maxRetries` {integer} 如果遇到 `EBUSY`、`EMFILE`、`ENFILE`、`ENOTEMPTY` 或 `EPERM` 错误，则 Node.js 将会在每次尝试时以 `retryDelay` 毫秒的线性回退来重试该操作。 - 此选项表示重试的次数。如果 `recursive` 选项不为 `true`，则忽略此选项。**默认值:** `0`。 - * `recursive` {boolean} 如果为 `true`，则执行递归的目录删除。在递归模式中，如果 `path` 不存在则不报告错误，并且在失败时重试操作。**默认值:** `false`。 - * `retryDelay` {integer} 重试之间等待的时间（以毫秒为单位）。如果 `recursive` 选项不为 `true`，则忽略此选项。**默认值:** `100`。 + * `maxRetries` {integer} 如果遇到 `EBUSY`、`EMFILE`、`ENFILE`、`ENOTEMPTY` 或 `EPERM` 错误，则 Node.js 会重试该操作（每次尝试时使用 `retryDelay` 毫秒时长的线性回退等待）。 + 此选项表示重试的次数。 + 如果 `recursive` 选项不为 `true`，则此选项会被忽略。 + **默认值:** `0`。 + * `recursive` {boolean} 如果为 `true`，则执行递归的目录删除。 + 在递归模式中，错误不会被报告（如果 `path` 不存在），并且操作会被重试（当失败时）。 + **默认值:** `false`。 + * `retryDelay` {integer} 重试之间等待的时间（以毫秒为单位）。 + 如果 `recursive` 选项不为 `true`，则此选项会被忽略。 + **默认值:** `100`。 同步的 rmdir(2)。 返回 `undefined`。 -在文件（而不是目录）上使用 `fs.rmdirSync()` 会导致在 Windows 上出现 `ENOENT` 错误、在 POSIX 上出现 `ENOTDIR` 错误。 +对文件（而不是目录）使用 `fs.rmdirSync()` 会导致 `ENOENT` 错误（在 Windows 上）或 `ENOTDIR` 错误（在 POSIX 上）。 diff --git a/fs/fs_unlink_path_callback.md b/fs/fs_unlink_path_callback.md index eda414a8..24d4b8ad 100644 --- a/fs/fs_unlink_path_callback.md +++ b/fs/fs_unlink_path_callback.md @@ -23,15 +23,15 @@ changes: 除了可能的异常，完成回调没有其他参数。 ```js -// 假设 'path/file.txt' 是常规文件。 -fs.unlink('path/file.txt', (err) => { +// 假设 '文件.txt' 是普通的文件。 +fs.unlink('文件.txt', (err) => { if (err) throw err; - console.log('文件已删除'); + console.log('文件已被删除'); }); ``` -`fs.unlink()` 不能用于目录。 -要删除目录，则使用 [`fs.rmdir()`]。 +`fs.unlink()` 对空或非空的目录均不起作用。 +若要删除目录，则使用 [`fs.rmdir()`]。 也可参见 unlink(2)。 diff --git a/fs/fs_unlinksync_path.md b/fs/fs_unlinksync_path.md index 47a1da4e..ed1acc72 100644 --- a/fs/fs_unlinksync_path.md +++ b/fs/fs_unlinksync_path.md @@ -9,5 +9,6 @@ changes: * `path` {string|Buffer|URL} -同步的 unlink(2)。返回 `undefined`。 +同步的 unlink(2)。 +返回 `undefined`。 diff --git a/fs/fs_watch_filename_options_listener.md b/fs/fs_watch_filename_options_listener.md index 8933d849..e916d7cb 100644 --- a/fs/fs_watch_filename_options_listener.md +++ b/fs/fs_watch_filename_options_listener.md @@ -3,8 +3,8 @@ added: v0.5.10 changes: - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 - description: The `filename` parameter can be a WHATWG `URL` object using - `file:` protocol. Support is currently still *experimental*. + description: 参数 `filename` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 + 该支持目前仍在实验的。 - version: v7.0.0 pr-url: https://github.com/nodejs/node/pull/7831 description: 传入的 `options` 对象无法再被修改。 diff --git a/fs/fs_watchfile_filename_options_listener.md b/fs/fs_watchfile_filename_options_listener.md index 38c47e1e..0383b681 100644 --- a/fs/fs_watchfile_filename_options_listener.md +++ b/fs/fs_watchfile_filename_options_listener.md @@ -6,8 +6,8 @@ changes: description: The `bigint` option is now supported. - version: v7.6.0 pr-url: https://github.com/nodejs/node/pull/10739 - description: The `filename` parameter can be a WHATWG `URL` object using - `file:` protocol. Support is currently still *experimental*. + description: 参数 `filename` 可以是 WHATWG `URL` 对象（使用 `file:` 协议）。 + 该支持目前仍在实验的。 --> * `filename` {string|Buffer|URL} diff --git a/fs/fs_write_fd_buffer_offset_length_position_callback.md b/fs/fs_write_fd_buffer_offset_length_position_callback.md index 697f8df3..50d7034f 100644 --- a/fs/fs_write_fd_buffer_offset_length_position_callback.md +++ b/fs/fs_write_fd_buffer_offset_length_position_callback.md @@ -3,22 +3,20 @@ added: v0.0.2 changes: - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/31030 - description: The `buffer` parameter won't coerce unsupported input to - strings anymore. + description: 参数 `buffer` 不再强制把不支持的输入转换为字符串。 - version: v10.10.0 pr-url: https://github.com/nodejs/node/pull/22150 - description: The `buffer` parameter can now be any `TypedArray` or a - `DataView` + description: 参数 `buffer` 可以是任何 `TypedArray` 或 `DataView`。 - version: v10.0.0 pr-url: https://github.com/nodejs/node/pull/12562 description: 参数 `callback` 不再是可选的。 如果不传入，则在运行时会抛出 `TypeError`。 - version: v7.4.0 pr-url: https://github.com/nodejs/node/pull/10382 - description: The `buffer` parameter can now be a `Uint8Array`. + description: 参数 `buffer` 可以是 `Uint8Array`。 - version: v7.2.0 pr-url: https://github.com/nodejs/node/pull/7856 - description: The `offset` and `length` parameters are optional now. + description: 参数 `offset` 和 `length` 是可选的。 - version: v7.0.0 pr-url: https://github.com/nodejs/node/pull/7897 description: 参数 `callback` 不再是可选的。 @@ -35,22 +33,22 @@ changes: * `bytesWritten` {integer} * `buffer` {Buffer|TypedArray|DataView} -将 `buffer` 写入到 `fd` 指定的文件。 +写入 `buffer` 到 `fd` 指定的文件。 -`offset` 决定 `buffer` 中要被写入的部位，`length` 是一个整数，指定要写入的字节数。 +`offset` 决定 buffer 中要被写入的部位，`length` 是整数，指定要写入的字节数。 -`position` 指定文件开头的偏移量（数据应该被写入的位置）。 +`position` 指定文件开头的偏移量（数据要被写入的位置）。 如果 `typeof position !== 'number'`，则数据会被写入当前的位置。 参见 pwrite(2)。 -回调有三个参数 `(err, bytesWritten, buffer)`，其中 `bytesWritten` 指定 `buffer` 中被写入的字节数。 +回调有三个参数 `(err, bytesWritten, buffer)`，其中 `bytesWritten` 指定从 `buffer` 中被写入的字节数。 -如果调用此方法的 [`util.promisify()`] 版本，则返回的 `Promise` 会返回具有 `bytesWritten` 和 `buffer` 属性的 `Object`。 +如果调用此方法的 [`util.promisify()`] 版本，则返回 `Promise`（会传入具有 `bytesWritten` 和 `buffer` 属性的 `Object`）。 不等待回调就对同一个文件多次使用 `fs.write()` 是不安全的。 对于这种情况，建议使用 [`fs.createWriteStream()`]。 -在 Linux 上，当以追加模式打开文件时，写入无法指定位置。 -内核会忽略位置参数，并始终将数据追加到文件的末尾。 +在 Linux 上，当以追加模式打开文件时，则写入时无法指定位置。 +内核会忽略位置参数，并始终追加数据到文件的末尾。 diff --git a/fs/fs_write_fd_string_position_encoding_callback.md b/fs/fs_write_fd_string_position_encoding_callback.md index 90d27462..4cbf5ebd 100644 --- a/fs/fs_write_fd_string_position_encoding_callback.md +++ b/fs/fs_write_fd_string_position_encoding_callback.md @@ -30,7 +30,7 @@ changes: 将 `string` 写入到 `fd` 指定的文件。 如果 `string` 不是一个字符串，则会抛出异常。 -`position` 指定文件开头的偏移量（数据应该被写入的位置）。 +`position` 指定文件开头的偏移量（数据要被写入的位置）。 如果 `typeof position !== 'number'`，则数据会被写入当前的位置。 参见 pwrite(2)。 @@ -43,8 +43,8 @@ changes: 不等待回调就对同一个文件多次使用 `fs.write()` 是不安全的。 对于这种情况，建议使用 [`fs.createWriteStream()`]。 -在 Linux 上，当以追加模式打开文件时，写入无法指定位置。 -内核会忽略位置参数，并始终将数据追加到文件的末尾。 +在 Linux 上，当以追加模式打开文件时，则写入时无法指定位置。 +内核会忽略位置参数，并始终追加数据到文件的末尾。 在 Windows 上，如果文件描述符连接到控制台（例如 `fd == 1` 或 `stdout`），则无论使用何种编码，包含非 ASCII 字符的字符串默认情况下都不会被正确地渲染。 通过使用 `chcp 65001` 命令更改活动的代码页，可以将控制台配置为正确地渲染 UTF-8。 diff --git a/fs/fs_writesync_fd_buffer_offset_length_position.md b/fs/fs_writesync_fd_buffer_offset_length_position.md index f207dbdf..f8525cdd 100644 --- a/fs/fs_writesync_fd_buffer_offset_length_position.md +++ b/fs/fs_writesync_fd_buffer_offset_length_position.md @@ -3,18 +3,16 @@ added: v0.1.21 changes: - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/31030 - description: The `buffer` parameter won't coerce unsupported input to - strings anymore. + description: 参数 `buffer` 不再强制把不支持的输入转换为字符串。 - version: v10.10.0 pr-url: https://github.com/nodejs/node/pull/22150 - description: The `buffer` parameter can now be any `TypedArray` or a - `DataView`. + description: 参数 `buffer` 可以是任何 `TypedArray` 或 `DataView`。 - version: v7.4.0 pr-url: https://github.com/nodejs/node/pull/10382 - description: The `buffer` parameter can now be a `Uint8Array`. + description: 参数 `buffer` 可以是 `Uint8Array`。 - version: v7.2.0 pr-url: https://github.com/nodejs/node/pull/7856 - description: The `offset` and `length` parameters are optional now. + description: 参数 `offset` 和 `length` 是可选的。 --> * `fd` {integer} diff --git a/fs/fs_writev_fd_buffers_position_callback.md b/fs/fs_writev_fd_buffers_position_callback.md index 68c73731..ee5c02ce 100644 --- a/fs/fs_writev_fd_buffers_position_callback.md +++ b/fs/fs_writev_fd_buffers_position_callback.md @@ -12,7 +12,7 @@ added: v12.9.0 使用 `writev()` 将一个 `ArrayBufferView` 数组写入 `fd` 指定的文件。 -`position` 指定文件开头的偏移量（数据应该被写入的位置）。 +`position` 指定文件开头的偏移量（数据要被写入的位置）。 如果 `typeof position !== 'number'`，则数据会被写入当前的位置。 回调有三个参数：`err`、`bytesWritten` 和 `buffers`。 @@ -24,6 +24,6 @@ added: v12.9.0 对于这种情况，建议使用 [`fs.createWriteStream()`]。 -在 Linux 上，当以追加模式打开文件时，写入无法指定位置。 -内核会忽略位置参数，并始终将数据追加到文件的末尾。 +在 Linux 上，当以追加模式打开文件时，则写入时无法指定位置。 +内核会忽略位置参数，并始终追加数据到文件的末尾。 diff --git a/fs/fspromises_access_path_mode.md b/fs/fspromises_access_path_mode.md index 0efbde89..f6487d13 100644 --- a/fs/fspromises_access_path_mode.md +++ b/fs/fspromises_access_path_mode.md @@ -8,7 +8,7 @@ added: v10.0.0 测试用户对 `path` 指定的文件或目录的权限。 `mode` 参数是一个可选的整数，指定要执行的可访问性检查。 -`mode` 可选的值参见[文件可访问性的常量][File Access Constants]。 +查看[文件可访问性的常量][File Access Constants]了解 `mode` 的可选值。 可以创建由两个或更多个值按位或组成的掩码（例如 `fs.constants.W_OK | fs.constants.R_OK`）。 如果可访问性检查成功，则 `Promise` 会被解决且不带值。 @@ -26,5 +26,5 @@ fsPromises.access('/etc/passwd', fs.constants.R_OK | fs.constants.W_OK) 不建议在调用 `fsPromises.open()` 之前使用 `fsPromises.access()` 检查文件的可访问性。 这样做会引入竞态条件，因为其他进程可能会在两个调用之间更改文件的状态。 -相反，应该直接打开、读取或写入文件，如果文件无法访问则处理引发的错误。 +而是，应该直接打开、读取或写入文件，并且当文件无法访问时处理引发的错误。 diff --git a/fs/fspromises_appendfile_path_data_options.md b/fs/fspromises_appendfile_path_data_options.md index 5faa7017..a181732b 100644 --- a/fs/fspromises_appendfile_path_data_options.md +++ b/fs/fspromises_appendfile_path_data_options.md @@ -10,7 +10,7 @@ added: v10.0.0 * `flag` {string} 参见[文件系统 `flag` 的支持][support of file system `flags`]。默认值: `'a'`。 * 返回: {Promise} -异步地将数据追加到文件，如果文件尚不存在则创建该文件。 +异步地追加数据到文件，如果文件尚不存在则创建文件。 `data` 可以是字符串或 [`Buffer`]。 `Promise` 将会在成功时解决，且不带参数。 diff --git a/fs/fspromises_mkdir_path_options.md b/fs/fspromises_mkdir_path_options.md index 3bd4e905..9652b106 100644 --- a/fs/fspromises_mkdir_path_options.md +++ b/fs/fspromises_mkdir_path_options.md @@ -5,11 +5,11 @@ added: v10.0.0 * `path` {string|Buffer|URL} * `options` {Object|integer} * `recursive` {boolean} **默认值:** `false`。 - * `mode` {string|integer} Windows 上不支持。**默认值:** `0o777`。 + * `mode` {string|integer} 在 Windows 上不支持。**默认值:** `0o777`。 * 返回: {Promise} -异步地创建目录，然后在成功时解决 `Promise`，且不带参数，或者如果 `recursive` 为 `true`，则带上创建的第一个目录的路径。 +异步地创建目录，然后在成功时解决 `Promise`，且不带参数，或者带上创建的第一个目录的路径（如果 `recursive` 为 `true`）。 -可选的 `options` 参数可以是指定 `mode`（权限和粘滞位）的整数，也可以是具有 `mode` 属性和 `recursive` 属性（指示是否应创建父目录）的对象。 -当 `path` 是一个已存在的目录时，调用 `fsPromises.mkdir()` 仅在 `recursive` 为 false 时才导致拒绝。 +可选的 `options` 参数可以是整数（指定 `mode`（权限和粘滞位））、或对象（具有 `mode` 属性和 `recursive` 属性（指示是否要创建父目录））。 +当 `path` 是已存在的目录时，调用 `fsPromises.mkdir()` 仅在 `recursive` 为 false 时才导致拒绝。 diff --git a/fs/fspromises_open_path_flags_mode.md b/fs/fspromises_open_path_flags_mode.md index 50f6a6a5..c56b760d 100644 --- a/fs/fspromises_open_path_flags_mode.md +++ b/fs/fspromises_open_path_flags_mode.md @@ -3,7 +3,7 @@ added: v10.0.0 changes: - version: v11.1.0 pr-url: https://github.com/nodejs/node/pull/23767 - description: The `flags` argument is now optional and defaults to `'r'`. + description: 参数 `flags` 是可选的，并且默认为 `'r'`。 --> * `path` {string|Buffer|URL} @@ -17,5 +17,5 @@ changes: `mode` 用于设置文件模式（权限和粘滞位），但仅限于创建文件时。 有些字符 (`< > : " / \ | ? *`) 在 Windows 上是预留的，参见[命名文件、路径以及命名空间][Naming Files, Paths, and Namespaces]。 -在 NTFS 上，如果文件名包含冒号，则 Node.js 将打开文件系统流，参见[此 MSDN 页面][MSDN-Using-Streams]。 +在 NTFS 上，如果文件名包含冒号，则 Node.js 会打开文件系统流，参见[此 MSDN 页面][MSDN-Using-Streams]。 diff --git a/fs/fspromises_opendir_path_options.md b/fs/fspromises_opendir_path_options.md index 231b58b4..571ba5c4 100644 --- a/fs/fspromises_opendir_path_options.md +++ b/fs/fspromises_opendir_path_options.md @@ -12,7 +12,7 @@ changes: * `options` {Object} * `encoding` {string|null} **默认值:** `'utf8'`。 * `bufferSize` {number} 当从目录读取时在内部缓冲的目录项的数量。值越高，则性能越好，但内存占用更高。**默认值:** `32`。 -* 返回: {Promise} 包含 {fs.Dir}。 +* 返回: 包含 {fs.Dir} 的 {Promise} 异步地打开目录。 参见 opendir(3)。 diff --git a/fs/fspromises_readdir_path_options.md b/fs/fspromises_readdir_path_options.md index 521eb202..20c02bd7 100644 --- a/fs/fspromises_readdir_path_options.md +++ b/fs/fspromises_readdir_path_options.md @@ -3,7 +3,7 @@ added: v10.0.0 changes: - version: v10.11.0 pr-url: https://github.com/nodejs/node/pull/22020 - description: New option `withFileTypes` was added. + description: 添加新的选项 `withFileTypes`。 --> * `path` {string|Buffer|URL} @@ -14,10 +14,10 @@ changes: 读取目录的内容，然后解决 `Promise` 并带上一个数组（包含目录中的文件的名称，但不包括 `'.'` 和 `'..'`）。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于文件名的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的文件名是 `Buffer` 对象。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于文件名的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的文件名会作为 `Buffer` 对象传入。 -如果 `options.withFileTypes` 设置为 `true`，则解决的数组将包含 [`fs.Dirent`] 对象。 +如果 `options.withFileTypes` 被设置为 `true`，则解决的数组会包含 [`fs.Dirent`] 对象。 ```js const fs = require('fs'); diff --git a/fs/fspromises_readlink_path_options.md b/fs/fspromises_readlink_path_options.md index b83e3fb1..faffbec2 100644 --- a/fs/fspromises_readlink_path_options.md +++ b/fs/fspromises_readlink_path_options.md @@ -10,6 +10,6 @@ added: v10.0.0 异步的 readlink(2)。 `Promise` 会在成功时解决，且带上 `linkString`。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于链接路径的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的链接路径将作为 `Buffer` 对象传入。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于链接路径的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的链接路径会作为 `Buffer` 对象传入。 diff --git a/fs/fspromises_realpath_path_options.md b/fs/fspromises_realpath_path_options.md index d7ee9418..0f490cba 100644 --- a/fs/fspromises_realpath_path_options.md +++ b/fs/fspromises_realpath_path_options.md @@ -11,8 +11,8 @@ added: v10.0.0 仅支持可转换为 UTF8 字符串的路径。 -可选的 `options` 参数可以是指定编码的字符串，也可以是具有 `encoding` 属性的对象，该属性指定用于路径的字符编码。 -如果 `encoding` 设置为 `'buffer'`，则返回的路径将作为 `Buffer` 对象传入。 +可选的 `options` 参数可以是字符串（指定字符编码）、或具有 `encoding` 属性（指定用于路径的字符编码）的对象。 +如果 `encoding` 被设置为 `'buffer'`，则返回的路径会作为 `Buffer` 对象传入。 在 Linux 上，当 Node.js 与 musl libc 链接时，procfs 文件系统必须挂载在 `/proc` 上才能使此功能正常工作。 Glibc 没有这个限制。 diff --git a/fs/fspromises_rmdir_path_options.md b/fs/fspromises_rmdir_path_options.md index c63cb0b2..f3c2e79c 100644 --- a/fs/fspromises_rmdir_path_options.md +++ b/fs/fspromises_rmdir_path_options.md @@ -5,11 +5,10 @@ changes: - v13.3.0 - v12.16.0 pr-url: https://github.com/nodejs/node/pull/30644 - description: The `maxBusyTries` option is renamed to `maxRetries`, and its - default is 0. The `emfileWait` option has been removed, and - `EMFILE` errors use the same retry logic as other errors. The - `retryDelay` option is now supported. `ENFILE` errors are now - retried. + description: 选项 `maxBusyTries` 被重命名为 `maxRetries`，并且默认值为 0。 + `emfileWait` 选项已被删除，并且 `EMFILE` 错误使用与其他错误相同的重试逻辑。 + 支持 `retryDelay` 选项。 + `ENFILE` 错误会被重试。 - version: v12.10.0 pr-url: https://github.com/nodejs/node/pull/29168 description: The `recursive`, `maxBusyTries`, and `emfileWait` options are @@ -20,13 +19,19 @@ changes: * `path` {string|Buffer|URL} * `options` {Object} - * `maxRetries` {integer} 如果遇到 `EBUSY`、`EMFILE`、`ENFILE`、`ENOTEMPTY` 或 `EPERM` 错误，则 Node.js 将会在每次尝试时以 `retryDelay` 毫秒的线性回退来重试该操作。 - 此选项表示重试的次数。如果 `recursive` 选项不为 `true`，则忽略此选项。**默认值:** `0`。 - * `recursive` {boolean} 如果为 `true`，则执行递归的目录删除。在递归模式中，如果 `path` 不存在则不报告错误，并且在失败时重试操作。**默认值:** `false`。 - * `retryDelay` {integer} 重试之间等待的时间（以毫秒为单位）。如果 `recursive` 选项不为 `true`，则忽略此选项。**默认值:** `100`。 + * `maxRetries` {integer} 如果遇到 `EBUSY`、`EMFILE`、`ENFILE`、`ENOTEMPTY` 或 `EPERM` 错误，则 Node.js 会重试该操作（每次尝试时使用 `retryDelay` 毫秒时长的线性回退等待）。 + 此选项表示重试的次数。 + 如果 `recursive` 选项不为 `true`，则此选项会被忽略。 + **默认值:** `0`。 + * `recursive` {boolean} 如果为 `true`，则执行递归的目录删除。 + 在递归模式中，错误不会被报告（如果 `path` 不存在），并且操作会被重试（当失败时）。 + **默认值:** `false`。 + * `retryDelay` {integer} 重试之间等待的时间（以毫秒为单位）。 + 如果 `recursive` 选项不为 `true`，则此选项会被忽略。 + **默认值:** `100`。 * 返回: {Promise} 删除 `path` 指定的目录，然后在成功时解决 `Promise` 且不带参数。 -在文件（而不是目录）上使用 `fsPromises.rmdir()` 会导致 `Promise` 被拒绝，在 Windows 上会带上 `ENOENT` 错误、在 POSIX 上会带上 `ENOTDIR` 错误。 +对文件（而不是目录）使用 `fsPromises.rmdir()` 会导致 `Promise` 被拒绝，在 Windows 上会带上 `ENOENT` 错误、在 POSIX 上会带上 `ENOTDIR` 错误。 diff --git a/fs/stats_isfile.md b/fs/stats_isfile.md index c92d6bc9..96372bc6 100644 --- a/fs/stats_isfile.md +++ b/fs/stats_isfile.md @@ -4,5 +4,5 @@ added: v0.1.10 * 返回: {boolean} -如果 `fs.Stats` 对象描述常规文件，则返回 `true`。 +如果 `fs.Stats` 对象描述普通的文件，则返回 `true`。 diff --git a/fs/url_object_support.md b/fs/url_object_support.md index d247c60c..59f4db7d 100644 --- a/fs/url_object_support.md +++ b/fs/url_object_support.md @@ -7,7 +7,7 @@ added: v7.6.0 ```js const fs = require('fs'); -const fileUrl = new URL('file:///tmp/hello'); +const fileUrl = new URL('file:///文件'); fs.readFileSync(fileUrl); ``` @@ -16,66 +16,66 @@ fs.readFileSync(fileUrl); 使用 WHATWG [`URL`] 对象可能会采用特定于平台的行为。 -在 Windows 上，带有主机名的 `file:` URL 转换为 UNC 路径，而带有驱动器号的 `file:` URL 转换为本地绝对路径。 -没有主机名和驱动器号的 `file:` URL 将导致抛出错误： +在 Windows 上，带有主机名的 `file:` URL 会转换为 UNC 路径，而带有驱动器号的 `file:` URL 会转换为本地的绝对路径。 +没有主机名和驱动器号的 `file:` URL 会导致抛出错误： ```js // 在 Windows 上： -// - 带有主机名的 WHATWG 文件的 URL 转换为 UNC 路径。 -// file://hostname/p/a/t/h/file => \\hostname\p\a\t\h\file -fs.readFileSync(new URL('file://hostname/p/a/t/h/file')); +// - 带有主机名的 WHATWG 文件的 URL 会转换为 UNC 路径。 +// file://主机名/文件 => \\主机名\文件 +fs.readFileSync(new URL('file://主机名/文件')); -// - 带有驱动器号的 WHATWG 文件的 URL 转换为绝对路径。 -// file:///C:/tmp/hello => C:\tmp\hello -fs.readFileSync(new URL('file:///C:/tmp/hello')); +// - 带有驱动器号的 WHATWG 文件的 URL 会转换为绝对路径。 +// file:///C:/文件 => C:\文件 +fs.readFileSync(new URL('file:///C:/文件')); // - 没有主机名的 WHATWG 文件的 URL 必须包含驱动器号。 -fs.readFileSync(new URL('file:///notdriveletter/p/a/t/h/file')); -fs.readFileSync(new URL('file:///c/p/a/t/h/file')); +fs.readFileSync(new URL('file:///无驱动器号/文件')); +fs.readFileSync(new URL('file:///文件')); // TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must be absolute ``` 带有驱动器号的 `file:` URL 必须使用 `:` 作为驱动器号后面的分隔符。 -使用其他分隔符将导致抛出错误。 +使用其他分隔符会导致抛出错误。 -在所有其他平台上，不支持带有主机名的 `file:` URL，使用时将导致抛出错误： +在所有其他平台上，不支持带有主机名的 `file:` URL，使用时会导致抛出错误： ```js // 在其他平台上： // - 不支持带有主机名的 WHATWG 文件的 URL。 -// file://hostname/p/a/t/h/file => throw! -fs.readFileSync(new URL('file://hostname/p/a/t/h/file')); +// file://主机名/文件 => 抛出错误! +fs.readFileSync(new URL('file://主机名/文件')); // TypeError [ERR_INVALID_FILE_URL_PATH]: must be absolute -// - WHATWG 文件的 URL 转换为绝对路径。 -// file:///tmp/hello => /tmp/hello -fs.readFileSync(new URL('file:///tmp/hello')); +// - WHATWG 文件的 URL 会转换为绝对路径。 +// file:///文件 => /文件 +fs.readFileSync(new URL('file:///文件')); ``` -包含编码后的斜杆字符（`%2F`）的 `file:` URL 在所有平台上都将导致抛出错误： +包含编码后的斜杆字符的 `file:` URL 在所有平台上都会导致抛出错误： ```js // 在 Windows 上： -fs.readFileSync(new URL('file:///C:/p/a/t/h/%2F')); -fs.readFileSync(new URL('file:///C:/p/a/t/h/%2f')); +fs.readFileSync(new URL('file:///C:/%2F')); +fs.readFileSync(new URL('file:///C:/%2f')); /* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded \ or / characters */ // 在 POSIX 上： -fs.readFileSync(new URL('file:///p/a/t/h/%2F')); -fs.readFileSync(new URL('file:///p/a/t/h/%2f')); +fs.readFileSync(new URL('file:///%2F')); +fs.readFileSync(new URL('file:///%2f')); /* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded / characters */ ``` -在 Windows 上，包含编码后的反斜杆字符（`%5C`）的 `file:` URL 将导致抛出错误： +在 Windows 上，包含编码后的反斜杆字符的 `file:` URL 会导致抛出错误： ```js // 在 Windows 上： -fs.readFileSync(new URL('file:///C:/path/%5C')); -fs.readFileSync(new URL('file:///C:/path/%5c')); +fs.readFileSync(new URL('file:///C:/%5C')); +fs.readFileSync(new URL('file:///C:/%5c')); /* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded \ or / characters */ ``` diff --git a/http2/class_http2_http2serverrequest.md b/http2/class_http2_http2serverrequest.md index b0d1a814..72e585c7 100644 --- a/http2/class_http2_http2serverrequest.md +++ b/http2/class_http2_http2serverrequest.md @@ -2,7 +2,7 @@ added: v8.4.0 --> -* Extends: {stream.Readable} +* 继承自: {stream.Readable} A `Http2ServerRequest` object is created by [`http2.Server`][] or [`http2.SecureServer`][] and passed as the first argument to the diff --git a/http2/class_http2_http2serverresponse.md b/http2/class_http2_http2serverresponse.md index c3f55cd8..45360fb8 100644 --- a/http2/class_http2_http2serverresponse.md +++ b/http2/class_http2_http2serverresponse.md @@ -2,7 +2,7 @@ added: v8.4.0 --> -* Extends: {Stream} +* 继承自: {Stream} This object is created internally by an HTTP server, not by the user. It is passed as the second parameter to the [`'request'`][] event. diff --git a/http2/class_http2secureserver.md b/http2/class_http2secureserver.md index 7501fba0..86716772 100644 --- a/http2/class_http2secureserver.md +++ b/http2/class_http2secureserver.md @@ -2,7 +2,7 @@ added: v8.4.0 --> -* Extends: {tls.Server} +* 继承自: {tls.Server} Instances of `Http2SecureServer` are created using the `http2.createSecureServer()` function. The `Http2SecureServer` class is not diff --git a/http2/class_http2server.md b/http2/class_http2server.md index 5a260236..aaed366c 100644 --- a/http2/class_http2server.md +++ b/http2/class_http2server.md @@ -2,7 +2,7 @@ added: v8.4.0 --> -* Extends: {net.Server} +* 继承自: {net.Server} Instances of `Http2Server` are created using the `http2.createServer()` function. The `Http2Server` class is not exported directly by the `http2` diff --git a/http2/class_http2stream.md b/http2/class_http2stream.md index 6ae1b819..95b66c0b 100644 --- a/http2/class_http2stream.md +++ b/http2/class_http2stream.md @@ -2,7 +2,7 @@ added: v8.4.0 --> -* Extends: {stream.Duplex} +* 继承自: {stream.Duplex} Each instance of the `Http2Stream` class represents a bidirectional HTTP/2 communications stream over an `Http2Session` instance. Any single `Http2Session` diff --git a/http2/class_serverhttp2session.md b/http2/class_serverhttp2session.md index d0f8790b..56d3067c 100644 --- a/http2/class_serverhttp2session.md +++ b/http2/class_serverhttp2session.md @@ -2,5 +2,5 @@ added: v8.4.0 --> -* Extends: {Http2Session} +* 继承自: {Http2Session} diff --git a/http2/class_serverhttp2stream.md b/http2/class_serverhttp2stream.md index 2e4b75af..cafe5b30 100644 --- a/http2/class_serverhttp2stream.md +++ b/http2/class_serverhttp2stream.md @@ -2,7 +2,7 @@ added: v8.4.0 --> -* Extends: {Http2Stream} +* 继承自: {Http2Stream} The `ServerHttp2Stream` class is an extension of [`Http2Stream`][] that is used exclusively on HTTP/2 Servers. `Http2Stream` instances on the server diff --git a/inspector/class_inspector_session.md b/inspector/class_inspector_session.md index c3492d59..b19a8f1e 100644 --- a/inspector/class_inspector_session.md +++ b/inspector/class_inspector_session.md @@ -1,5 +1,5 @@ -* Extends: {EventEmitter} +* 继承自: {EventEmitter} The `inspector.Session` is used for dispatching messages to the V8 inspector back-end and receiving message responses and notifications. diff --git a/path/windows_vs_posix.md b/path/windows_vs_posix.md index 024a761d..e1aa738f 100644 --- a/path/windows_vs_posix.md +++ b/path/windows_vs_posix.md @@ -36,8 +36,8 @@ path.posix.basename('/tmp/myfile.html'); // 返回: 'myfile.html' ``` -在 Windows 上，Node.js 遵循各自驱动器工作目录的理念。 +在 Windows 上，Node.js 遵循独立驱动器工作目录的概念。 当使用没有反斜杠的驱动器路径时，可以观察到此行为。 例如，`path.resolve('C:\\')` 可能会返回与 `path.resolve('C:')` 不同的结果。 -有关详细信息，参见[此 MSDN 页面][MSDN-Rel-Path]。 +详见[此 MSDN 页面][MSDN-Rel-Path]。 diff --git a/tls/class_tls_tlssocket.md b/tls/class_tls_tlssocket.md index dd3956e6..fa57b827 100644 --- a/tls/class_tls_tlssocket.md +++ b/tls/class_tls_tlssocket.md @@ -2,7 +2,7 @@ added: v0.11.4 --> -* Extends: {net.Socket} +* 继承自: {net.Socket} Performs transparent encryption of written data and all required TLS negotiation. diff --git a/vm/class_vm_sourcetextmodule.md b/vm/class_vm_sourcetextmodule.md index d9e9fdc8..94176a4d 100644 --- a/vm/class_vm_sourcetextmodule.md +++ b/vm/class_vm_sourcetextmodule.md @@ -7,7 +7,7 @@ added: v9.6.0 *This feature is only available with the `--experimental-vm-modules` command flag enabled.* -* Extends: {vm.Module} +* 继承自: {vm.Module} The `vm.SourceTextModule` class provides the [Source Text Module Record][] as defined in the ECMAScript specification. diff --git a/vm/class_vm_syntheticmodule.md b/vm/class_vm_syntheticmodule.md index d87459b4..970f62e5 100644 --- a/vm/class_vm_syntheticmodule.md +++ b/vm/class_vm_syntheticmodule.md @@ -9,7 +9,7 @@ added: *This feature is only available with the `--experimental-vm-modules` command flag enabled.* -* Extends: {vm.Module} +* 继承自: {vm.Module} The `vm.SyntheticModule` class provides the [Synthetic Module Record][] as defined in the WebIDL specification. The purpose of synthetic modules is to diff --git a/worker_threads/class_messageport.md b/worker_threads/class_messageport.md index 48b7f483..13f4a9af 100644 --- a/worker_threads/class_messageport.md +++ b/worker_threads/class_messageport.md @@ -2,7 +2,7 @@ added: v10.5.0 --> -* Extends: {EventEmitter} +* 继承自: {EventEmitter} Instances of the `worker.MessagePort` class represent one end of an asynchronous, two-way communications channel. It can be used to transfer