Node.js v21.7.2 文件

承諾範例#

基於承諾的作業會傳回一個承諾，當非同步作業完成時，該承諾會兌現。

import { unlink } from 'node:fs/promises';

try {
  await unlink('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (error) {
  console.error('there was an error:', error.message);
}const { unlink } = require('node:fs/promises');

(async function(path) {
  try {
    await unlink(path);
    console.log(`successfully deleted ${path}`);
  } catch (error) {
    console.error('there was an error:', error.message);
  }
})('/tmp/hello');copy

回呼範例#

回呼表單將完成回呼函式作為其最後一個引數，並非同步呼叫作業。傳遞給完成回呼的引數取決於方法，但第一個引數總是保留給例外。如果作業已順利完成，則第一個引數為 null 或 undefined。

import { unlink } from 'node:fs';

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});const { unlink } = require('node:fs');

unlink('/tmp/hello', (err) => {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});copy

當需要最大效能（在執行時間和記憶體配置兩方面）時，建議使用 node:fs 模組 API 的基於回呼的版本，而不是使用承諾 API。

同步範例#

同步 API 會封鎖 Node.js 事件迴圈和進一步的 JavaScript 執行，直到作業完成。例外會立即擲出，可以使用 try…catch 處理，或允許其冒泡。

import { unlinkSync } from 'node:fs';

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}const { unlinkSync } = require('node:fs');

try {
  unlinkSync('/tmp/hello');
  console.log('successfully deleted /tmp/hello');
} catch (err) {
  // handle the error
}copy

承諾 API#

fs/promises API 提供會傳回承諾的非同步檔案系統方法。

承諾 API 使用底層 Node.js 執行緒池在事件迴圈執行緒之外執行檔案系統作業。這些作業未同步或執行緒安全。在對同一個檔案執行多個並發修改時，必須小心，否則可能會發生資料毀損。

類別：FileHandle#

<FileHandle> 物件是數字檔案描述符的物件包裝器。

<FileHandle> 物件的執行個體是由 fsPromises.open() 方法建立的。

所有 <FileHandle> 物件都是 <EventEmitter>。

如果 <FileHandle> 未使用 `filehandle.close()` 方法關閉，它會嘗試自動關閉檔案描述符並發出程序警告，有助於防止記憶體外洩。請勿依賴此行為，因為它可能不可靠，且檔案可能未關閉。相反地，請務必明確關閉 <FileHandle>。Node.js 可能會在未來變更此行為。

事件：'close'#

當 <FileHandle> 已關閉且無法再使用時，會發出 'close' 事件。

filehandle.appendFile(data[, options])#

• data <字串> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <物件> | <字串>
  • encoding <字串> | <null> 預設值： 'utf8'
  • flush <布林值> 如果為 true，則在關閉檔案描述子之前會先強制寫入。預設值： false。
• 傳回：<Promise> 成功時會以 undefined 完成。

filehandle.writeFile() 的別名。

對檔案處理程序進行操作時，無法變更模式，模式必須與使用 fsPromises.open() 設定的模式相同。因此，這等同於 filehandle.writeFile()。

filehandle.chmod(mode)#

• mode <整數> 檔案模式位元遮罩。
• 傳回：<Promise> 成功時會以 undefined 完成。

修改檔案的權限。請參閱 chmod(2)。

filehandle.chown(uid, gid)#

• uid <integer> 檔案的新擁有者的使用者 ID。
• gid <integer> 檔案的新群組的群組 ID。
• 傳回：<Promise> 成功時會以 undefined 完成。

變更檔案的所有權。用於包裝 chown(2)。

filehandle.close()#

• 傳回：<Promise> 成功時會以 undefined 完成。

在等待任何處理中的操作完成後關閉檔案處理序。

import { open } from 'node:fs/promises';

let filehandle;
try {
  filehandle = await open('thefile.txt', 'r');
} finally {
  await filehandle?.close();
} copy

filehandle.createReadStream([options])#

• options <Object>
  • encoding <string> 預設值： null
  • autoClose <boolean> 預設值： true
  • emitClose <boolean> 預設值： true
  • start <integer>
  • end <integer> 預設值： Infinity
  • highWaterMark <integer> 預設值： 64 * 1024
• 傳回：<fs.ReadStream>

與 <stream.Readable> 的預設 highWaterMark 16 KiB 不同，此方法傳回的串流有預設 highWaterMark 64 KiB。

options 可以包含 start 和 end 值，用來從檔案讀取某個範圍的位元組，而不是整個檔案。start 和 end 都是包含式，從 0 開始計算，允許的值範圍為 [0, Number.MAX_SAFE_INTEGER]。如果省略或未定義 start，filehandle.createReadStream() 會從目前的檔案位置開始順序讀取。encoding 可以是 <Buffer> 接受的編碼之一。

如果 FileHandle 指向僅支援封鎖讀取的字元裝置（例如鍵盤或音效卡），讀取作業會在資料可用前不會結束。這可能會阻止程序結束和串流自然關閉。

預設情況下，串流會在毀損後發出 'close' 事件。設定 emitClose 選項為 false 以變更此行為。

import { open } from 'node:fs/promises';

const fd = await open('/dev/input/event0');
// Create a stream from some character device.
const stream = fd.createReadStream();
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); copy

如果 autoClose 為 false，則即使有錯誤，檔案描述符也不會關閉。關閉檔案描述符並確保沒有檔案描述符外洩是應用程式的責任。如果 autoClose 設為 true（預設行為），則在 'error' 或 'end' 時，檔案描述符會自動關閉。

以下範例說明如何讀取長度為 100 位元組的檔案的最後 10 個位元組

import { open } from 'node:fs/promises';

const fd = await open('sample.txt');
fd.createReadStream({ start: 90, end: 99 }); copy

filehandle.createWriteStream([options])#

• options <Object>
  • 編碼 <字串> 預設值： 'utf8'
  • autoClose <boolean> 預設值： true
  • emitClose <boolean> 預設值： true
  • start <integer>
  • 高水位標記 <數字> 預設值： 16384
  • flush <布林值> 如果為 true，則在關閉檔案描述子之前會先強制寫入。預設值： false。
• 傳回： <fs.WriteStream>

選項 也可能包含 開始 選項，允許在檔案開頭後某個位置寫入資料，允許的值在 [0, Number.MAX_SAFE_INTEGER] 範圍內。修改檔案而不是取代檔案可能需要將 旗標 開啟 選項設定為 r+，而不是預設的 r。編碼 可以是 <Buffer> 接受的任何一個編碼。

如果在 '錯誤' 或 '完成' 時將 自動關閉 設定為 true（預設行為），檔案描述符將自動關閉。如果 自動關閉 為 false，則檔案描述符不會關閉，即使有錯誤也是如此。關閉檔案描述符並確保沒有檔案描述符外洩是應用程式的責任。

預設情況下，串流會在毀損後發出 'close' 事件。設定 emitClose 選項為 false 以變更此行為。

檔案處理常式.datasync()#

• 傳回：<Promise> 成功時會以 undefined 完成。

強制所有目前與檔案相關聯的排隊 I/O 作業轉到作業系統的同步 I/O 完成狀態。有關詳細資訊，請參閱 POSIX fdatasync(2) 文件。

與 檔案處理常式.sync 不同，此方法不會清除已修改的元資料。

檔案處理常式.fd#

• <數字> 由 <FileHandle> 物件管理的數字檔案描述符。

filehandle.read(buffer, offset, length, position)#

• buffer <Buffer> | <TypedArray> | <DataView> 將會填入讀取檔案資料的緩衝區。
• offset <整數> 開始填入緩衝區的位置。預設：0
• length <整數> 要讀取的位元組數。預設：buffer.byteLength - offset
• position <整數> | <bigint> | <null> 開始從檔案讀取資料的位置。如果是 null 或 -1，資料將從目前的檔案位置讀取，且位置會更新。如果 position 是非負整數，目前的檔案位置將保持不變。預設：: null
• 傳回：<Promise> 成功時會履行，並傳回一個具有兩個屬性的物件
  • bytesRead <整數> 讀取的位元組數
  • buffer <Buffer> | <TypedArray> | <DataView> 傳入的 buffer 參數的參考。

從檔案讀取資料並儲存在指定的緩衝區中。

如果檔案沒有同時修改，當讀取的位元組數為零時，表示已到檔案結尾。

filehandle.read([options])#

• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> 將填入已讀取檔案資料的緩衝區。預設值：Buffer.alloc(16384)
  • offset <整數> 開始填入緩衝區的位置。預設：0
  • length <整數> 要讀取的位元組數。預設：buffer.byteLength - offset
  • position <整數> | <bigint> | <null> 開始從檔案讀取資料的位置。如果是 null 或 -1，資料將從目前的檔案位置讀取，且位置會更新。如果 position 是非負整數，目前的檔案位置將保持不變。預設：: null
• 傳回：<Promise> 成功時會履行，並傳回一個具有兩個屬性的物件
  • bytesRead <整數> 讀取的位元組數
  • buffer <Buffer> | <TypedArray> | <DataView> 傳入的 buffer 參數的參考。

從檔案讀取資料並儲存在指定的緩衝區中。

如果檔案沒有同時修改，當讀取的位元組數為零時，表示已到檔案結尾。

filehandle.read(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView> 將會填入讀取檔案資料的緩衝區。
• options <Object>
  • offset <整數> 開始填入緩衝區的位置。預設：0
  • length <整數> 要讀取的位元組數。預設：buffer.byteLength - offset
  • position <整數> | <bigint> | <null> 開始從檔案讀取資料的位置。如果是 null 或 -1，資料將從目前的檔案位置讀取，且位置會更新。如果 position 是非負整數，目前的檔案位置將保持不變。預設：: null
• 傳回：<Promise> 成功時會履行，並傳回一個具有兩個屬性的物件
  • bytesRead <整數> 讀取的位元組數
  • buffer <Buffer> | <TypedArray> | <DataView> 傳入的 buffer 參數的參考。

從檔案讀取資料並儲存在指定的緩衝區中。

如果檔案沒有同時修改，當讀取的位元組數為零時，表示已到檔案結尾。

filehandle.readableWebStream([options])#

• options <Object>

  • type <string> | <undefined>是要開啟一般串流還是 'bytes' 串流。預設值：undefined

• 傳回：<ReadableStream>

傳回一個 ReadableStream，可用來讀取檔案資料。

如果此方法被呼叫超過一次，或者在 FileHandle 關閉或正在關閉後被呼叫，將會擲回錯誤。

import {
  open,
} from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const chunk of file.readableWebStream())
  console.log(chunk);

await file.close();const {
  open,
} = require('node:fs/promises');

(async () => {
  const file = await open('./some/file/to/read');

  for await (const chunk of file.readableWebStream())
    console.log(chunk);

  await file.close();
})();copy

雖然 ReadableStream 會將檔案讀取完畢，但它不會自動關閉 FileHandle。使用者程式碼仍必須呼叫 fileHandle.close() 方法。

filehandle.readFile(options)#

• options <物件> | <字串>
  • 編碼 <字串> | <null> 預設值： null
  • 訊號 <AbortSignal> 允許中斷進行中的 readFile
• 傳回： <Promise> 在成功讀取檔案內容後完成。如果未指定編碼（使用 options.encoding），資料會以 <Buffer> 物件傳回。否則，資料會是字串。

非同步讀取檔案的完整內容。

如果 options 是字串，則它會指定 編碼。

<FileHandle> 必須支援讀取。

如果對檔案控制代碼執行一個或多個 filehandle.read() 呼叫，然後執行 filehandle.readFile() 呼叫，資料會從目前位置讀取至檔案結尾。它並非總是從檔案開頭讀取。

filehandle.readLines([options])#

• options <Object>
  • encoding <string> 預設值： null
  • autoClose <boolean> 預設值： true
  • emitClose <boolean> 預設值： true
  • start <integer>
  • end <integer> 預設值： Infinity
  • highWaterMark <integer> 預設值： 64 * 1024
• 傳回： <readline.InterfaceConstructor>

建立 readline 介面並串流檔案的便利方法。請參閱 filehandle.createReadStream() 以取得選項。

import { open } from 'node:fs/promises';

const file = await open('./some/file/to/read');

for await (const line of file.readLines()) {
  console.log(line);
}const { open } = require('node:fs/promises');

(async () => {
  const file = await open('./some/file/to/read');

  for await (const line of file.readLines()) {
    console.log(line);
  }
})();copy

filehandle.readv(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> 從檔案開頭讀取資料的位移量。如果 position 不是 number，將從目前位置讀取資料。預設值：null
• 傳回：<Promise> 成功時會履行一個包含兩個屬性的物件
  • bytesRead <integer> 已讀取的位元組數
  • buffers <Buffer[]> | <TypedArray[]> | <DataView[]> 屬性，包含對 buffers 輸入的參考。

從檔案讀取並寫入 <ArrayBufferView> 陣列

filehandle.stat([options])#

• options <Object>
  • bigint <boolean> 傳回的 <fs.Stats> 物件中的數字值是否應為 bigint。預設值：false。
• 傳回：<Promise> 履行檔案的 <fs.Stats>。

filehandle.sync()#

• 傳回：<Promise> 成功時會以 undefined 完成。

要求將開啟檔案描述符的所有資料沖洗到儲存裝置。具體實作取決於作業系統和裝置。有關更多詳細資訊，請參閱 POSIX fsync(2) 文件。

filehandle.truncate(len)#

• len <整數> 預設： 0
• 傳回：<Promise> 成功時會以 undefined 完成。

截斷檔案。

如果檔案大於 len 位元組，則檔案中只會保留前 len 位元組。

以下範例只會保留檔案的前四個位元組

import { open } from 'node:fs/promises';

let filehandle = null;
try {
  filehandle = await open('temp.txt', 'r+');
  await filehandle.truncate(4);
} finally {
  await filehandle?.close();
} copy

如果檔案原本小於 len 位元組，則會將檔案延伸，並用空位元組 ('\0') 填滿延伸的部分

如果 len 為負數，則會使用 0。

filehandle.utimes(atime, mtime)#

• atime <數字> | <字串> | <Date>
• mtime <數字> | <字串> | <Date>
• 傳回： <Promise>

變更 <FileHandle> 所引用的物件檔案系統時間戳記，然後在成功時履行承諾，且無任何引數。

filehandle.write(buffer, offset[, length[, position]])#

• buffer <Buffer> | <TypedArray> | <DataView>
• offset <integer> 要寫入資料的 buffer 內部開始位置。
• length <integer> 要從 buffer 寫入的位元組數。預設：buffer.byteLength - offset
• position <integer> | <null> 應從 buffer 寫入資料的檔案開頭的位移量。如果 position 不是 number，資料將寫入目前位置。請參閱 POSIX pwrite(2) 文件以取得更多詳細資料。預設：null
• 傳回： <Promise>

將 buffer 寫入檔案。

承諾會履行，並包含兩個屬性的物件

• bytesWritten <integer> 已寫入的位元組數
• buffer <Buffer> | <TypedArray> | <DataView> 已寫入的 buffer 參考。

在未等待承諾完成（或拒絕）的情況下，對同一個檔案多次使用 filehandle.write() 是不安全的。對於這種情況，請使用 filehandle.createWriteStream()。

在 Linux 上，當檔案以追加模式開啟時，位置寫入無法運作。核心會忽略位置引數，並始終將資料附加到檔案的結尾。

filehandle.write(buffer[, options])#

• buffer <Buffer> | <TypedArray> | <DataView>
• options <Object>
  • offset <integer> 預設值： 0
  • length <integer> 預設值： buffer.byteLength - offset
  • position <integer> 預設值： null
• 傳回： <Promise>

將 buffer 寫入檔案。

與上述 filehandle.write 函式類似，此版本採用一個選用的 options 物件。如果未指定 options 物件，它將預設為上述值。

filehandle.write(string[, position[, encoding]])#

• string <string>
• position <整數> | <null> 從檔案開頭開始寫入資料的 string 的位移量。如果 position 不是 number，資料會寫入目前的位移量。請參閱 POSIX pwrite(2) 文件以取得更多詳細資訊。預設值：null
• encoding <字串> 預期的字串編碼。預設值：'utf8'
• 傳回： <Promise>

將 string 寫入檔案。如果 string 不是字串，承諾會因錯誤而遭到拒絕。

承諾會履行，並包含兩個屬性的物件

• bytesWritten <integer> 已寫入的位元組數
• buffer <字串> 寫入的 string 參考。

在未等待承諾完成（或拒絕）的情況下，對同一個檔案多次使用 filehandle.write() 是不安全的。對於這種情況，請使用 filehandle.createWriteStream()。

在 Linux 上，當檔案以追加模式開啟時，位置寫入無法運作。核心會忽略位置引數，並始終將資料附加到檔案的結尾。

filehandle.writeFile(data, options)#

• data <字串> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <物件> | <字串>
  • encoding <字串> | <null> 當 data 為字串時預期的字元編碼。預設值：'utf8'
• 傳回： <Promise>

非同步將資料寫入檔案，如果檔案已存在，則取代檔案。data 可以是字串、緩衝區、<AsyncIterable> 或 <Iterable> 物件。承諾在成功時以沒有參數的方式履行。

如果 options 是字串，則它會指定 編碼。

<FileHandle> 必須支援寫入。

在同一個檔案上多次使用 filehandle.writeFile() 而未等待承諾履行（或遭到拒絕）是不安全的。

如果對檔案處理呼叫一個或多個 filehandle.write()，然後呼叫 filehandle.writeFile()，資料會從目前的位移量寫入到檔案的結尾。它不會總是從檔案的開頭寫入。

filehandle.writev(buffers[, position])#

• buffers <Buffer[]> | <TypedArray[]> | <DataView[]>
• position <integer> | <null> 應從 buffers 寫入資料的檔案開頭偏移量。如果 position 不是 number，資料將會寫入目前位置。預設值：null
• 傳回： <Promise>

將 <ArrayBufferView> 陣列寫入檔案。

承諾會以包含兩個屬性的物件達成

• bytesWritten <integer> 已寫入的位元組數
• buffers <Buffer[]> | <TypedArray[]> | <DataView[]> buffers 輸入的參考。

在未等待承諾達成 (或拒絕) 前，對同一個檔案呼叫 writev() 多次是不安全的。

在 Linux 上，當檔案以附加模式開啟時，位置寫入無法運作。核心會忽略位置參數，並始終將資料附加到檔案結尾。

filehandle[Symbol.asyncDispose]()#

filehandle.close() 的別名。

fsPromises.access(path[, mode])#

• path <string> | <Buffer> | <URL>
• mode <integer> 預設值： fs.constants.F_OK
• 傳回：<Promise> 成功時會以 undefined 完成。

測試使用者對於由 path 指定的檔案或目錄的權限。mode 參數是一個可選的整數，用於指定要執行的存取檢查。mode 應為值 fs.constants.F_OK 或由 fs.constants.R_OK、fs.constants.W_OK 和 fs.constants.X_OK 的位元運算 OR 組成的遮罩（例如 fs.constants.W_OK | fs.constants.R_OK）。查看 檔案存取常數 以取得 mode 的可能值。

如果存取檢查成功，則承諾會以無值的方式履行。如果任何存取檢查失敗，則承諾會以 <Error> 物件拒絕。以下範例檢查目前程序是否可以讀取和寫入檔案 /etc/passwd。

import { access, constants } from 'node:fs/promises';

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK);
  console.log('can access');
} catch {
  console.error('cannot access');
} copy

不建議使用 fsPromises.access() 來檢查檔案的存取性，然後再呼叫 fsPromises.open()。這麼做會產生競爭條件，因為其他程序可能會在兩次呼叫之間變更檔案的狀態。相反地，使用者程式碼應該直接開啟/讀取/寫入檔案，並處理檔案無法存取時引發的錯誤。

fsPromises.appendFile(path, data[, options])#

• path <string> | <Buffer> | <URL> | <FileHandle> 檔案名稱或 <FileHandle>
• data <string> | <Buffer>
• options <物件> | <字串>
  • encoding <字串> | <null> 預設值： 'utf8'
  • mode <integer> 預設： 0o666
  • flag <string> 請參閱 檔案系統 flags 的支援。預設： 'a'。
  • flush <布林值> 如果為 true，則在關閉檔案描述子之前會先強制寫入。預設值： false。
• 傳回：<Promise> 成功時會以 undefined 完成。

非同步將資料附加到檔案，如果檔案不存在，則建立檔案。data 可以是字串或 <Buffer>。

如果 options 是字串，則它會指定 編碼。

mode 選項僅影響新建立的檔案。請參閱 fs.open() 以取得更多詳細資料。

path 可以指定為已開啟用於附加的 <FileHandle>（使用 fsPromises.open()）。

fsPromises.chmod(path, mode)#

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• 傳回：<Promise> 成功時會以 undefined 完成。

變更檔案的權限。

fsPromises.chown(path, uid, gid)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 傳回：<Promise> 成功時會以 undefined 完成。

變更檔案的所有權。

fsPromises.copyFile(src, dest[, mode])#

• src <string> | <Buffer> | <URL> 要複製的來源檔名
• dest <string> | <Buffer> | <URL> 複製作業的目標檔名
• mode <integer> 指定複製作業行為的選用修改器。可以建立由兩個或更多值按位元 OR 組成的遮罩（例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE）預設值：0。
  • fs.constants.COPYFILE_EXCL：如果 dest 已存在，複製操作將會失敗。
  • fs.constants.COPYFILE_FICLONE：複製操作將嘗試建立寫入時複製的 reflink。如果平台不支援寫入時複製，則會使用備用複製機制。
  • fs.constants.COPYFILE_FICLONE_FORCE：複製操作將嘗試建立寫入時複製的 reflink。如果平台不支援寫入時複製，則操作將會失敗。
• 傳回：<Promise> 成功時會以 undefined 完成。

非同步地將 src 複製到 dest。預設情況下，如果 dest 已存在，它將被覆寫。

不保證複製操作的原子性。如果在打開目標檔案進行寫入後發生錯誤，系統將嘗試移除目標檔案。

import { copyFile, constants } from 'node:fs/promises';

try {
  await copyFile('source.txt', 'destination.txt');
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
}

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
try {
  await copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL);
  console.log('source.txt was copied to destination.txt');
} catch {
  console.error('The file could not be copied');
} copy

fsPromises.cp(src, dest[, options])#

• src <string> | <URL> 要複製的來源路徑。
• dest <string> | <URL> 要複製到的目標路徑。
• options <Object>
  • dereference <boolean> 取消符號連結的參考。預設值：false。
  • errorOnExist 當 force 為 false，且目標存在時，擲回錯誤。預設值：false。
  • filter <Function> 用於過濾複製檔案/目錄的函式。傳回 true 以複製項目，傳回 false 以略過項目。略過目錄時，其所有內容也會被略過。也可以傳回解析為 true 或 false 的 Promise。預設值：undefined。
    • src <string> 要複製的來源路徑。
    • dest <字串> 要複製到的目標路徑。
    • 傳回：<布林值> | <Promise>
  • force <布林值> 覆寫現有的檔案或目錄。如果您將此設定為 false，且目標已存在，複製作業將會忽略錯誤。使用 errorOnExist 選項來變更此行為。預設：true。
  • mode <整數> 複製作業的修改器。預設：0。請參閱 fsPromises.copyFile() 的 mode 旗標。
  • preserveTimestamps <布林值> 當 true 時，將保留來自 src 的時間戳記。預設：false。
  • recursive <布林值> 遞迴複製目錄預設：false
  • verbatimSymlinks <布林值> 當 true 時，將略過符號連結的的路徑解析。預設：false
• 傳回：<Promise> 成功時會以 undefined 完成。

非同步地將整個目錄結構從 src 複製到 dest，包括子目錄和檔案。

將目錄複製到另一個目錄時，不支援 glob，且行為類似於 cp dir1/ dir2/。

fsPromises.lchmod(path, mode)#

• path <string> | <Buffer> | <URL>
• mode <整數>
• 傳回：<Promise> 成功時會以 undefined 完成。

變更符號連結的權限。

此方法僅在 macOS 上實作。

fsPromises.lchown(path, uid, gid)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• 傳回：<Promise> 成功時會以 undefined 完成。

變更符號連結的所有權。

fsPromises.lutimes(path, atime, mtime)#

• path <string> | <Buffer> | <URL>
• atime <數字> | <字串> | <Date>
• mtime <數字> | <字串> | <Date>
• 傳回：<Promise> 成功時會以 undefined 完成。

變更檔案的存取和修改時間，方式與 fsPromises.utimes() 相同，不同之處在於如果路徑指向符號連結，則不會取消連結：而是變更符號連結本身的時間戳記。

fsPromises.link(existingPath, newPath)#

• existingPath <字串> | <Buffer> | <URL>
• newPath <字串> | <Buffer> | <URL>
• 傳回：<Promise> 成功時會以 undefined 完成。

從 existingPath 到 newPath 建立新的連結。請參閱 POSIX link(2) 文件以取得更多詳細資料。

fsPromises.lstat(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 傳回的 <fs.Stats> 物件中的數字值是否應為 bigint。預設值：false。
• 傳回：<Promise> 針對指定的符號連結 path，以 <fs.Stats> 物件完成。

等同於 fsPromises.stat()，除非 path 參照符號連結，否則會對連結本身執行 stat，而非其參照的檔案。請參閱 POSIX lstat(2) 文件以取得更多詳細資料。

fsPromises.mkdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 預設值： false
  • mode <string> | <integer> Windows 不支援。預設值： 0o777。
• 傳回：<Promise> 成功時，若 recursive 為 false，則以 undefined 完成；若 recursive 為 true，則以建立的第一個目錄路徑完成。

非同步建立目錄。

選用的 options 參數可以是指定 mode（權限和黏著位元）的整數，或是一個物件，其中具有 mode 屬性和 recursive 屬性，表示是否應建立父目錄。當 path 是已存在的目錄時，呼叫 fsPromises.mkdir() 僅在 recursive 為 false 時才會導致拒絕。

import { mkdir } from 'node:fs/promises';

try {
  const projectFolder = new URL('./test/project/', import.meta.url);
  const createDir = await mkdir(projectFolder, { recursive: true });

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}const { mkdir } = require('node:fs/promises');
const { join } = require('node:path');

async function makeDirectory() {
  const projectFolder = join(__dirname, 'test', 'project');
  const dirCreation = await mkdir(projectFolder, { recursive: true });

  console.log(dirCreation);
  return dirCreation;
}

makeDirectory().catch(console.error);copy

fsPromises.mkdtemp(prefix[, options])#

• prefix <字串> | <緩衝區> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
• 傳回：<承諾> 以包含新建立暫時目錄的檔案系統路徑的字串來完成。

建立唯一的暫時目錄。會在提供的 prefix 結尾加上六個隨機字元來產生唯一的目錄名稱。由於平台不一致，請避免在 prefix 中使用尾隨 X 字元。某些平台（特別是 BSD）可能會傳回超過六個隨機字元，並用隨機字元取代 prefix 中的尾隨 X 字元。

選用的 options 參數可以是指定編碼的字串，或是包含指定要使用的字元編碼的 encoding 屬性的物件。

import { mkdtemp } from 'node:fs/promises';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

try {
  await mkdtemp(join(tmpdir(), 'foo-'));
} catch (err) {
  console.error(err);
} copy

fsPromises.mkdtemp() 方法會將六個隨機選取的字元直接附加到 prefix 字串。例如，假設有一個目錄 /tmp，如果要建立一個位於 /tmp 內部的 暫時目錄，則 prefix 必須以尾隨的平台特定路徑分隔符號 (require('node:path').sep) 結尾。

fsPromises.open(path, flags[, mode])#

• path <string> | <Buffer> | <URL>
• flags <字串> | <數字> 請參閱 檔案系統 flags 的支援。預設： 'r'。
• mode <字串> | <整數> 如果建立檔案，則設定檔案模式（權限和黏著位元）。預設值：0o666（可讀寫）
• 傳回：<Promise> 以 <FileHandle> 物件完成。

開啟 <FileHandle>。

有關更多詳細資料，請參閱 POSIX open(2) 文件。

某些字元（< > : " / \ | ? *）在 Windows 中保留，如 命名檔案、路徑和命名空間 所述。在 NTFS 中，如果檔名包含冒號，Node.js 會開啟檔案系統串流，如 此 MSDN 頁面 所述。

fsPromises.opendir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <字串> | <null> 預設值： 'utf8'
  • bufferSize <數字> 從目錄讀取時在內部緩衝的目錄項目數。較高的值會提升效能，但會使用較多的記憶體。預設值：32
  • recursive <布林值> 已解析的 Dir 會是 <AsyncIterable>，其中包含所有子檔案和目錄。預設值：false
• 傳回：<Promise> 以 <fs.Dir> 完成。

非同步開啟目錄以進行反覆掃描。有關更多詳細資料，請參閱 POSIX opendir(3) 文件。

建立一個 <fs.Dir>，其中包含所有用於從目錄中讀取和清理的進一步功能。

encoding 選項在開啟目錄和後續讀取操作時設定 path 的編碼。

使用非同步反覆運算的範例

import { opendir } from 'node:fs/promises';

try {
  const dir = await opendir('./');
  for await (const dirent of dir)
    console.log(dirent.name);
} catch (err) {
  console.error(err);
} copy

使用非同步反覆運算器時，<fs.Dir> 物件在反覆運算器退出後將自動關閉。

fsPromises.readdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
  • withFileTypes <boolean> 預設值： false
  • recursive <boolean> 如果為 true，則遞迴讀取目錄的內容。在遞迴模式中，它將列出所有檔案、子檔案和目錄。預設值： false。
• 傳回：<Promise> 以目錄中檔案名稱的陣列為準，不包括 '.' 和 '..'。

讀取目錄的內容。

選用的 options 參數可以是指定編碼的字串，或是一個物件，其中包含指定用於檔案名稱的字元編碼的 encoding 屬性。如果 encoding 設定為 'buffer'，傳回的檔案名稱將傳遞為 <Buffer> 物件。

如果 options.withFileTypes 設定為 true，傳回的陣列將包含 <fs.Dirent> 物件。

import { readdir } from 'node:fs/promises';

try {
  const files = await readdir(path);
  for (const file of files)
    console.log(file);
} catch (err) {
  console.error(err);
} copy

fsPromises.readFile(path[, options])#

• path <string> | <Buffer> | <URL> | <FileHandle> 檔案名稱或 FileHandle
• options <物件> | <字串>
  • 編碼 <字串> | <null> 預設值： null
  • flag <string> 請參閱 檔案系統 flags 的支援。預設值： 'r'。
  • 訊號 <AbortSignal> 允許中斷進行中的 readFile
• 傳回： <Promise> 以檔案內容來達成。

非同步讀取檔案的完整內容。

如果未指定編碼（使用 options.encoding），資料會以 <Buffer> 物件傳回。否則，資料會是字串。

如果 options 是字串，則它會指定編碼。

當 path 是目錄時，fsPromises.readFile() 的行為取決於平台。在 macOS、Linux 和 Windows 上，承諾會因錯誤而遭到拒絕。在 FreeBSD 上，會傳回目錄內容的表示形式。

在執行程式碼的相同目錄中讀取 package.json 檔案的範例

import { readFile } from 'node:fs/promises';
try {
  const filePath = new URL('./package.json', import.meta.url);
  const contents = await readFile(filePath, { encoding: 'utf8' });
  console.log(contents);
} catch (err) {
  console.error(err.message);
}const { readFile } = require('node:fs/promises');
const { resolve } = require('node:path');
async function logFile() {
  try {
    const filePath = resolve('./package.json');
    const contents = await readFile(filePath, { encoding: 'utf8' });
    console.log(contents);
  } catch (err) {
    console.error(err.message);
  }
}
logFile();copy

可以使用 <AbortSignal> 中斷正在進行的 readFile。如果要求遭到中斷，傳回的承諾會因 AbortError 而遭到拒絕

import { readFile } from 'node:fs/promises';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const promise = readFile(fileName, { signal });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
} copy

中斷正在進行的要求並不會中斷個別作業系統要求，而是中斷 fs.readFile 執行的內部緩衝。

任何指定的 <FileHandle> 都必須支援讀取。

fsPromises.readlink(path[, options])#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
• 傳回：<Promise> 成功時履行 linkString。

讀取 path 參照的符號連結內容。有關更多詳細資訊，請參閱 POSIX readlink(2) 文件。成功時履行 linkString。

選擇性的 options 參數可以是指定編碼的字串，或是一個物件，其中 encoding 屬性指定要使用的連結路徑字元編碼。如果 encoding 設為 'buffer'，傳回的連結路徑會作為 <Buffer> 物件傳遞。

fsPromises.realpath(path[, options])#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
• 傳回：<Promise> 成功時履行已解析的路徑。

使用與 fs.realpath.native() 函數相同的語意來判斷 path 的實際位置。

僅支援可轉換為 UTF8 字串的路徑。

選擇性的 options 參數可以是指定編碼的字串，或是一個物件，其中 encoding 屬性指定要使用的路徑字元編碼。如果 encoding 設為 'buffer'，傳回的路徑會作為 <Buffer> 物件傳遞。

在 Linux 上，當 Node.js 與 musl libc 連結時，必須在 /proc 上掛載 procfs 檔案系統才能讓此函數運作。Glibc 沒有這個限制。

fsPromises.rename(oldPath, newPath)#

• oldPath <string> | <Buffer> | <URL>
• newPath <字串> | <Buffer> | <URL>
• 傳回：<Promise> 成功時會以 undefined 完成。

將 oldPath 重新命名為 newPath。

fsPromises.rmdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 錯誤，Node.js 會以線性遞增等待時間重試操作，每次嘗試增加 retryDelay 毫秒。此選項表示重試次數。如果 recursive 選項不是 true，則會忽略此選項。預設值：0。
  • recursive <boolean> 如果為 true，則執行遞迴目錄移除。在遞迴模式中，會在失敗時重試操作。預設值：false。已棄用。
  • retryDelay <整數> 重試之間等待的時間（毫秒）。如果 recursive 選項不是 true，則會忽略此選項。預設值：100。
• 傳回：<Promise> 成功時會以 undefined 完成。

移除由 path 識別的目錄。

在檔案（而非目錄）上使用 fsPromises.rmdir() 會導致承諾在 Windows 上被拒絕，並出現 ENOENT 錯誤，而在 POSIX 上則出現 ENOTDIR 錯誤。

若要獲得類似 Unix 指令 rm -rf 的行為，請使用 fsPromises.rm() 搭配選項 { recursive: true, force: true }。

fsPromises.rm(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <布林> 當為 true 時，如果 path 不存在，則會忽略例外。預設值：false。
  • maxRetries <整數> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 錯誤，Node.js 會以線性遞減等待時間重試作業，每次嘗試會增加 retryDelay 毫秒。此選項表示重試次數。如果 recursive 選項不是 true，則會忽略此選項。預設值：0。
  • recursive <布林> 如果為 true，則執行遞迴目錄移除。在遞迴模式中，作業會在失敗時重試。預設值：false。
  • retryDelay <整數> 重試之間等待的時間（毫秒）。如果 recursive 選項不是 true，則會忽略此選項。預設值：100。
• 傳回：<Promise> 成功時會以 undefined 完成。

移除檔案和目錄（以標準 POSIX rm 工具為範本）。

fsPromises.stat(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 傳回的 <fs.Stats> 物件中的數字值是否應為 bigint。預設值：false。
• 傳回：<Promise> 使用給定 path 的 <fs.Stats> 物件達成承諾。

fsPromises.statfs(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 傳回的 <fs.StatFs> 物件中的數值是否應為 bigint。預設值：false。
• 傳回：<Promise> 以給定 path 的 <fs.StatFs> 物件達成。傳回。

fsPromises.symlink(target, path[, type])#

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> 預設值：null
• 傳回：<Promise> 成功時會以 undefined 完成。

建立符號連結。

type 參數僅用於 Windows 平台，且可以是 'dir'、'file' 或 'junction' 之一。如果 type 參數不是字串，Node.js 會自動偵測 target 類型，並使用 'file' 或 'dir'。如果 target 不存在，將會使用 'file'。Windows 交接點需要目標路徑為絕對路徑。使用 'junction' 時，target 參數會自動正規化為絕對路徑。NTFS 磁區上的交接點只能指向目錄。

fsPromises.truncate(path[, len])#

• path <string> | <Buffer> | <URL>
• len <整數> 預設： 0
• 傳回：<Promise> 成功時會以 undefined 完成。

將 path 中內容的長度截斷（縮短或延長）為 len 位元組。

fsPromises.unlink(path)#

• path <string> | <Buffer> | <URL>
• 傳回：<Promise> 成功時會以 undefined 完成。

如果 path 參照符號連結，則移除連結，而不影響連結所參照的檔案或目錄。如果 path 參照的檔案路徑不是符號連結，則刪除檔案。有關詳細資訊，請參閱 POSIX unlink(2) 文件。

fsPromises.utimes(path, atime, mtime)#

• path <string> | <Buffer> | <URL>
• atime <數字> | <字串> | <Date>
• mtime <數字> | <字串> | <Date>
• 傳回：<Promise> 成功時會以 undefined 完成。

變更 path 參照的物件的檔案系統時間戳記。

atime 和 mtime 參數遵循以下規則

• 值可以是表示 Unix 紀元時間的數字、Date 或數字字串，例如 '123456789.0'。
• 如果無法將值轉換為數字，或為 NaN、Infinity 或 -Infinity，則會擲回 Error。

fsPromises.watch(filename[, options])#

• filename <字串> | <Buffer> | <URL>
• options <字串> | <物件>
  • persistent <布林值> 指示處理程序是否應持續執行，只要檔案持續受到監控。預設：true。
  • recursive <boolean> 指示是否應監控所有子目錄，或僅監控目前目錄。當指定目錄時套用，且僅在受支援的平台上（請參閱 注意事項）。預設：false。
  • encoding <string> 指定要傳遞給監聽器的檔案名稱所使用的字元編碼。預設：'utf8'。
  • signal <AbortSignal> <AbortSignal> 用於發出訊號，表示監控器應停止。
• 傳回：<AsyncIterator> 具有下列屬性的物件
  • eventType <string> 變更類型
  • filename <string> | <Buffer> | <null> 已變更檔案的名稱。

傳回在 filename 上監控變更的非同步反覆運算器，其中 filename 是檔案或目錄。

const { watch } = require('node:fs/promises');

const ac = new AbortController();
const { signal } = ac;
setTimeout(() => ac.abort(), 10000);

(async () => {
  try {
    const watcher = watch(__filename, { signal });
    for await (const event of watcher)
      console.log(event);
  } catch (err) {
    if (err.name === 'AbortError')
      return;
    throw err;
  }
})(); copy

在大部分平台上，每當目錄中出現或消失檔案名稱時，就會發出 'rename'。

fs.watch() 的所有 注意事項 也適用於 fsPromises.watch()。

fsPromises.writeFile(file, data[, options])#

• file <string> | <Buffer> | <URL> | <FileHandle> 檔案名稱或 FileHandle
• data <字串> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <物件> | <字串>
  • encoding <字串> | <null> 預設值： 'utf8'
  • mode <integer> 預設： 0o666
  • flag <string> 請參閱 檔案系統 flags 的支援。預設：'w'。
  • flush <boolean> 如果所有資料都已成功寫入檔案，且 flush 為 true，則會使用 filehandle.sync() 來清除資料。預設值：false。
  • signal <AbortSignal> 允許中斷進行中的 writeFile
• 傳回：<Promise> 成功時會以 undefined 完成。

非同步將資料寫入檔案，如果檔案已存在，則會取代該檔案。data 可以是字串、緩衝區、<AsyncIterable> 或 <Iterable> 物件。

如果 data 是緩衝區，則會忽略指定的 <FileHandle>。

如果 options 是字串，則它會指定編碼。

mode 選項僅影響新建立的檔案。請參閱 fs.open() 以取得更多詳細資料。

任何指定的 <FileHandle> 都必須支援寫入。

在同一個檔案上多次使用 fsPromises.writeFile() 而未等到承諾解決是不安全的。

與 fsPromises.readFile 類似，fsPromises.writeFile 是一種便利的方法，會在內部執行多個 write 呼叫來寫入傳遞給它的緩衝區。對於效能敏感的程式碼，請考慮使用 fs.createWriteStream() 或 filehandle.createWriteStream()。

可以使用 <AbortSignal> 來取消 fsPromises.writeFile()。取消是「盡力而為」，而且仍有可能會寫入一些資料。

import { writeFile } from 'node:fs/promises';
import { Buffer } from 'node:buffer';

try {
  const controller = new AbortController();
  const { signal } = controller;
  const data = new Uint8Array(Buffer.from('Hello Node.js'));
  const promise = writeFile('message.txt', data, { signal });

  // Abort the request before the promise settles.
  controller.abort();

  await promise;
} catch (err) {
  // When a request is aborted - err is an AbortError
  console.error(err);
} copy

中斷正在進行的請求不會中斷個別作業系統請求，而是會中斷 fs.writeFile 執行的內部緩衝。

fsPromises.constants#

• <物件>

傳回包含檔案系統操作中常用的常數的物件。此物件與 fs.constants 相同。請參閱 FS 常數 以取得更多詳細資料。

回呼 API#

回呼 API 會非同步執行所有操作，而不會阻擋事件迴圈，然後在完成或發生錯誤時呼叫回呼函式。

回呼 API 使用底層 Node.js 執行緒池在事件迴圈執行緒之外執行檔案系統操作。這些操作並非同步或執行緒安全。在對同一個檔案執行多個並發修改時，必須小心，否則可能會發生資料毀損。

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

• path <string> | <Buffer> | <URL>
• mode <integer> 預設值： fs.constants.F_OK
• callback <函式>
  • err <錯誤>

測試使用者對於由 path 指定的檔案或目錄的權限。mode 參數是一個可選的整數，用於指定要執行的存取檢查。mode 應為值 fs.constants.F_OK 或由 fs.constants.R_OK、fs.constants.W_OK 和 fs.constants.X_OK 的位元運算 OR 組成的遮罩（例如 fs.constants.W_OK | fs.constants.R_OK）。查看 檔案存取常數 以取得 mode 的可能值。

最後一個參數 callback 是會呼叫可能的錯誤參數的回呼函式。如果任何可存取性檢查失敗，錯誤參數將會是 Error 物件。下列範例會檢查 package.json 是否存在，以及是否可讀或可寫。

import { access, constants } from 'node:fs';

const file = 'package.json';

// Check if the file exists in the current directory.
access(file, constants.F_OK, (err) => {
  console.log(`${file} ${err ? 'does not exist' : 'exists'}`);
});

// Check if the file is readable.
access(file, constants.R_OK, (err) => {
  console.log(`${file} ${err ? 'is not readable' : 'is readable'}`);
});

// Check if the file is writable.
access(file, constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not writable' : 'is writable'}`);
});

// Check if the file is readable and writable.
access(file, constants.R_OK | constants.W_OK, (err) => {
  console.log(`${file} ${err ? 'is not' : 'is'} readable and writable`);
}); copy

在呼叫 fs.open()、fs.readFile() 或 fs.writeFile() 之前，請勿使用 fs.access() 來檢查檔案的可存取性。這麼做會導致競爭條件，因為其他程序可能會在兩個呼叫之間變更檔案的狀態。相反地，使用者程式碼應該直接開啟/讀取/寫入檔案，並處理檔案無法存取時引發的錯誤。

撰寫（不建議）

import { access, open, close } from 'node:fs';

access('myfile', (err) => {
  if (!err) {
    console.error('myfile already exists');
    return;
  }

  open('myfile', 'wx', (err, fd) => {
    if (err) throw err;

    try {
      writeMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
}); copy

撰寫（建議）

import { open, close } from 'node:fs';

open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  try {
    writeMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

讀取（不建議）

import { access, open, close } from 'node:fs';
access('myfile', (err) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  open('myfile', 'r', (err, fd) => {
    if (err) throw err;

    try {
      readMyData(fd);
    } finally {
      close(fd, (err) => {
        if (err) throw err;
      });
    }
  });
}); copy

讀取（建議）

import { open, close } from 'node:fs';

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  try {
    readMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

上述「不建議」的範例會檢查可存取性，然後使用檔案；「建議」的範例較佳，因為它們直接使用檔案並處理錯誤（如果有）。

一般來說，僅當檔案不會直接使用時才檢查檔案的可存取性，例如當其可存取性是來自其他程序的訊號時。

在 Windows 上，目錄上的存取控制原則 (ACL) 可能會限制對檔案或目錄的存取。但是，fs.access() 函式不會檢查 ACL，因此即使 ACL 限制使用者讀取或寫入，它也可能會報告路徑可存取。

fs.appendFile(path, data[, options], callback)#

• path <string> | <Buffer> | <URL> | <number> 檔案名稱或檔案描述符
• data <string> | <Buffer>
• options <物件> | <字串>
  • encoding <字串> | <null> 預設值： 'utf8'
  • mode <integer> 預設： 0o666
  • flag <string> 請參閱 檔案系統 flags 的支援。預設： 'a'。
  • flush <布林值> 如果為 true，則在關閉檔案描述子之前會先強制寫入。預設值： false。
• callback <函式>
  • err <錯誤>

非同步將資料附加到檔案，如果檔案不存在，則建立檔案。data 可以是字串或 <Buffer>。

mode 選項僅影響新建立的檔案。請參閱 fs.open() 以取得更多詳細資料。

import { appendFile } from 'node:fs';

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

如果 options 是字串，則它會指定編碼

import { appendFile } from 'node:fs';

appendFile('message.txt', 'data to append', 'utf8', callback); copy

path 可以指定為已開啟用於追加的數字檔案描述符 (使用 fs.open() 或 fs.openSync())。檔案描述符不會自動關閉。

import { open, close, appendFile } from 'node:fs';

function closeFd(fd) {
  close(fd, (err) => {
    if (err) throw err;
  });
}

open('message.txt', 'a', (err, fd) => {
  if (err) throw err;

  try {
    appendFile(fd, 'data to append', 'utf8', (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    throw err;
  }
}); copy

fs.chmod(path, mode, callback)#

• path <string> | <Buffer> | <URL>
• mode <string> | <integer>
• callback <函式>
  • err <錯誤>

非同步變更檔案的權限。除了可能的例外情況外，不會向完成回呼提供其他引數。

請參閱 POSIX chmod(2) 文件以取得更多詳細資訊。

import { chmod } from 'node:fs';

chmod('my_file.txt', 0o775, (err) => {
  if (err) throw err;
  console.log('The permissions for file "my_file.txt" have been changed!');
}); copy

檔案模式#

在 fs.chmod() 和 fs.chmodSync() 方法中使用的 mode 引數是使用下列常數的邏輯 OR 建立的數字位元遮罩

建構 mode 的較簡單方法是使用三個八進位數字的序列（例如 765）。最左邊的數字（範例中的 7）指定檔案擁有者的權限。中間的數字（範例中的 6）指定群組的權限。最右邊的數字（範例中的 5）指定其他人的權限。

例如，八進位值 0o765 表示

• 擁有者可以讀取、寫入和執行檔案。
• 群組可以讀取和寫入檔案。
• 其他人可以讀取和執行檔案。

在預期檔案模式的地方使用原始數字時，任何大於 0o777 的值都可能導致特定於平台的行為，而這些行為無法一致地運作。因此，fs.constants 中不會公開常數，例如 S_ISVTX、S_ISGID 或 S_ISUID。

注意事項：在 Windows 上，只能變更寫入權限，而且群組、擁有者或其他人的權限區分並未實作。

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

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <函式>
  • err <錯誤>

非同步變更檔案的擁有者和群組。除了可能的例外情況之外，不會將任何參數傳送給完成回呼。

請參閱 POSIX chown(2) 文件以取得更多詳細資料。

fs.close(fd[, callback])#

• fd <整數>
• callback <函式>
  • err <錯誤>

關閉檔案描述符。除了可能的例外情況外，不會提供任何其他參數給完成回呼函式。

對任何目前透過任何其他 fs 操作使用中的檔案描述符 (fd) 呼叫 fs.close() 可能會導致未定義的行為。

請參閱 POSIX close(2) 文件以取得更多詳細資料。

fs.copyFile(src, dest[, mode], callback)#

• src <string> | <Buffer> | <URL> 要複製的來源檔名
• dest <string> | <Buffer> | <URL> 複製作業的目標檔名
• mode <整數> 複製操作的修改器。預設：0。
• callback <函式>

非同步地將 src 複製到 dest。預設情況下，如果 dest 已存在，則會覆寫它。除了可能的例外情況外，不會提供任何其他參數給回呼函式。Node.js 不保證複製操作的原子性。如果在開啟目的地檔案進行寫入後發生錯誤，Node.js 會嘗試移除目的地。

mode 是指定複製操作行為的選用整數。可以建立由兩個或多個值的按位元或組成的遮罩 (例如 fs.constants.COPYFILE_EXCL | fs.constants.COPYFILE_FICLONE)。

• fs.constants.COPYFILE_EXCL：如果 dest 已存在，複製操作將會失敗。
• fs.constants.COPYFILE_FICLONE：複製操作將嘗試建立寫入時複製的 reflink。如果平台不支援寫入時複製，則會使用備用複製機制。
• fs.constants.COPYFILE_FICLONE_FORCE：複製操作將嘗試建立寫入時複製的 reflink。如果平台不支援寫入時複製，則操作將會失敗。

import { copyFile, constants } from 'node:fs';

function callback(err) {
  if (err) throw err;
  console.log('source.txt was copied to destination.txt');
}

// destination.txt will be created or overwritten by default.
copyFile('source.txt', 'destination.txt', callback);

// By using COPYFILE_EXCL, the operation will fail if destination.txt exists.
copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback); copy

fs.cp(src, dest[, options], callback)#

• src <string> | <URL> 要複製的來源路徑。
• dest <string> | <URL> 要複製到的目標路徑。
• options <Object>
  • dereference <boolean> 取消符號連結的參考。預設值：false。
  • errorOnExist 當 force 為 false，且目標存在時，擲回錯誤。預設值：false。
  • filter <Function> 用於過濾複製檔案/目錄的函式。傳回 true 以複製項目，傳回 false 以略過項目。略過目錄時，其所有內容也會被略過。也可以傳回解析為 true 或 false 的 Promise。預設值：undefined。
    • src <string> 要複製的來源路徑。
    • dest <字串> 要複製到的目標路徑。
    • 傳回：<布林值> | <Promise>
  • force <布林值> 覆寫現有的檔案或目錄。如果您將此設定為 false，且目標已存在，複製作業將會忽略錯誤。使用 errorOnExist 選項來變更此行為。預設：true。
  • mode <整數> 複製操作的修改器。預設：0。請參閱 fs.copyFile() 的 mode 標記。
  • preserveTimestamps <布林值> 當 true 時，將保留來自 src 的時間戳記。預設：false。
  • recursive <布林值> 遞迴複製目錄預設：false
  • verbatimSymlinks <布林值> 當 true 時，將略過符號連結的的路徑解析。預設：false
• callback <函式>

非同步地將整個目錄結構從 src 複製到 dest，包括子目錄和檔案。

將目錄複製到另一個目錄時，不支援 glob，且行為類似於 cp dir1/ dir2/。

fs.createReadStream(path[, options])#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • flags <字串> 請參閱 檔案系統 flags 的支援。預設值： 'r'。
  • encoding <string> 預設值： null
  • fd <整數> | <FileHandle> 預設值： null
  • mode <integer> 預設： 0o666
  • autoClose <boolean> 預設值： true
  • emitClose <boolean> 預設值： true
  • start <integer>
  • end <integer> 預設值： Infinity
  • highWaterMark <integer> 預設值： 64 * 1024
  • fs <物件> | <null> 預設值： null
  • signal <AbortSignal> | <null> 預設值： null
• 傳回：<fs.ReadStream>

與 <stream.Readable> 的預設 highWaterMark 16 KiB 不同，此方法傳回的串流有預設 highWaterMark 64 KiB。

options 可包含 start 和 end 值，以從檔案中讀取某個位元組範圍，而不是整個檔案。start 和 end 都是包含在內的，並且從 0 開始計算，允許的值在 [0, Number.MAX_SAFE_INTEGER] 範圍內。如果指定了 fd，而省略了 start 或 undefined，則 fs.createReadStream() 會從目前的檔案位置順序讀取。encoding 可以是 <Buffer> 接受的任何編碼。

如果指定了 fd，ReadStream 會忽略 path 參數，並會使用指定的檔案描述符。這表示不會發出任何 'open' 事件。fd 應為封鎖；非封鎖 fd 應傳遞給 <net.Socket>。

如果 fd 指向僅支援封鎖讀取的字元裝置（例如鍵盤或音效卡），則讀取作業會在資料可用前不會完成。這可能會阻止程序退出，並阻止串流自然關閉。

預設情況下，串流會在毀損後發出 'close' 事件。設定 emitClose 選項為 false 以變更此行為。

透過提供 fs 選項，可以覆寫對應的 fs 實作，以進行 open、read 和 close。在提供 fs 選項時，需要覆寫 read。如果未提供 fd，則也需要覆寫 open。如果 autoClose 為 true，則也需要覆寫 close。

import { createReadStream } from 'node:fs';

// Create a stream from some character device.
const stream = createReadStream('/dev/input/event0');
setTimeout(() => {
  stream.close(); // This may not close the stream.
  // Artificially marking end-of-stream, as if the underlying resource had
  // indicated end-of-file by itself, allows the stream to close.
  // This does not cancel pending read operations, and if there is such an
  // operation, the process may still not be able to exit successfully
  // until it finishes.
  stream.push(null);
  stream.read(0);
}, 100); copy

如果 autoClose 為 false，則即使有錯誤，檔案描述符也不會關閉。關閉檔案描述符並確保沒有檔案描述符外洩是應用程式的責任。如果 autoClose 設為 true（預設行為），則在 'error' 或 'end' 時，檔案描述符會自動關閉。

mode 設定檔案模式（權限和黏著位元），但僅在建立檔案時才會設定。

以下範例說明如何讀取長度為 100 位元組的檔案的最後 10 個位元組

import { createReadStream } from 'node:fs';

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

如果 options 是字串，則它會指定編碼。

fs.createWriteStream(path[, options])#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • flags <string> 請參閱 檔案系統 flags 的支援。預設值： 'w'。
  • 編碼 <字串> 預設值： 'utf8'
  • fd <整數> | <FileHandle> 預設值： null
  • mode <integer> 預設： 0o666
  • autoClose <boolean> 預設值： true
  • emitClose <boolean> 預設值： true
  • start <integer>
  • fs <物件> | <null> 預設值： null
  • signal <AbortSignal> | <null> 預設值： null
  • 高水位標記 <數字> 預設值： 16384
  • flush <布林值> 如果為 true，則在關閉檔案描述子之前會先強制寫入。預設值： false。
• 傳回： <fs.WriteStream>

options 也可能包含一個 start 選項，允許在檔案開頭之後的某個位置寫入資料，允許的值在 [0, Number.MAX_SAFE_INTEGER] 範圍內。修改檔案而不是取代它可能需要將 flags 選項設定為 r+，而不是預設的 w。encoding 可以是 <Buffer> 接受的任何一個。

如果在 '錯誤' 或 '完成' 時將 自動關閉 設定為 true（預設行為），檔案描述符將自動關閉。如果 自動關閉 為 false，則檔案描述符不會關閉，即使有錯誤也是如此。關閉檔案描述符並確保沒有檔案描述符外洩是應用程式的責任。

預設情況下，串流會在毀損後發出 'close' 事件。設定 emitClose 選項為 false 以變更此行為。

透過提供 fs 選項，可以覆寫對應的 fs 實作，包括 open、write、writev 和 close。在沒有 writev() 的情況下覆寫 write() 可能會降低效能，因為某些最佳化（_writev()）將會停用。在提供 fs 選項時，至少需要覆寫 write 和 writev 其中之一。如果沒有提供 fd 選項，也需要覆寫 open。如果 autoClose 為 true，也需要覆寫 close。

如同 <fs.ReadStream>，如果指定了 fd，<fs.WriteStream> 將會忽略 path 參數，並使用指定的檔案描述符。這表示不會發出 'open' 事件。fd 應為封鎖的；非封鎖的 fd 應傳遞給 <net.Socket>。

如果 options 是字串，則它會指定編碼。

fs.exists(path, callback)#

• path <string> | <Buffer> | <URL>
• callback <函式>
  • exists <boolean>

透過檢查檔案系統來測試給定的路徑是否存在。然後以 true 或 false 呼叫 callback 參數

import { exists } from 'node:fs';

exists('/etc/passwd', (e) => {
  console.log(e ? 'it exists' : 'no passwd!');
}); copy

此回呼的參數與其他 Node.js 回呼不一致。一般來說，Node.js 回呼的第一個參數是 err 參數，後續可能會接續其他參數。fs.exists() 回呼只有一個布林值參數。這是建議使用 fs.access() 而非 fs.exists() 的原因之一。

不建議在呼叫 fs.open()、fs.readFile() 或 fs.writeFile() 之前使用 fs.exists() 檢查檔案是否存在。這麼做會產生競爭條件，因為其他程序可能會在這兩次呼叫之間變更檔案狀態。相反地，使用者程式碼應該直接開啟/讀取/寫入檔案，並處理檔案不存在時引發的錯誤。

撰寫（不建議）

import { exists, open, close } from 'node:fs';

exists('myfile', (e) => {
  if (e) {
    console.error('myfile already exists');
  } else {
    open('myfile', 'wx', (err, fd) => {
      if (err) throw err;

      try {
        writeMyData(fd);
      } finally {
        close(fd, (err) => {
          if (err) throw err;
        });
      }
    });
  }
}); copy

撰寫（建議）

import { open, close } from 'node:fs';
open('myfile', 'wx', (err, fd) => {
  if (err) {
    if (err.code === 'EEXIST') {
      console.error('myfile already exists');
      return;
    }

    throw err;
  }

  try {
    writeMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

讀取（不建議）

import { open, close, exists } from 'node:fs';

exists('myfile', (e) => {
  if (e) {
    open('myfile', 'r', (err, fd) => {
      if (err) throw err;

      try {
        readMyData(fd);
      } finally {
        close(fd, (err) => {
          if (err) throw err;
        });
      }
    });
  } else {
    console.error('myfile does not exist');
  }
}); copy

讀取（建議）

import { open, close } from 'node:fs';

open('myfile', 'r', (err, fd) => {
  if (err) {
    if (err.code === 'ENOENT') {
      console.error('myfile does not exist');
      return;
    }

    throw err;
  }

  try {
    readMyData(fd);
  } finally {
    close(fd, (err) => {
      if (err) throw err;
    });
  }
}); copy

上述「不建議」的範例會檢查是否存在，然後使用檔案；「建議」的範例較佳，因為它們會直接使用檔案並處理錯誤（如果有）。

一般來說，只有在不會直接使用檔案時才檢查檔案是否存在，例如當檔案的存在是來自另一個程序的訊號時。

fs.fchmod(fd, mode, callback)#

• fd <整數>
• mode <string> | <integer>
• callback <函式>
  • err <錯誤>

設定檔案的權限。除了可能的例外狀況外，不會提供其他參數給完成回呼。

有關更多詳細資料，請參閱 POSIX fchmod(2) 文件。

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

• fd <整數>
• uid <integer>
• gid <integer>
• callback <函式>
  • err <錯誤>

設定檔案的所有者。除了可能的例外狀況外，不會提供其他參數給完成回呼。

有關詳細資訊，請參閱 POSIX fchown(2) 文件。

fs.fdatasync(fd, callback)#

• fd <整數>
• callback <函式>
  • err <錯誤>

強制將所有目前與檔案相關聯的排隊 I/O 作業傳送至作業系統的同步 I/O 完成狀態。有關詳細資訊，請參閱 POSIX fdatasync(2) 文件。除了可能的例外情況外，不會提供任何其他引數給完成回呼函式。

fs.fstat(fd[, options], callback)#

• fd <整數>
• options <Object>
  • bigint <boolean> 傳回的 <fs.Stats> 物件中的數字值是否應為 bigint。預設值：false。
• callback <函式>
  • err <錯誤>
  • stats <fs.Stats>

使用檔案描述符的 <fs.Stats> 呼叫回呼函式。

有關詳細資訊，請參閱 POSIX fstat(2) 文件。

fs.fsync(fd, callback)#

• fd <整數>
• callback <函式>
  • err <錯誤>

要求將開啟檔案描述符的所有資料沖刷至儲存裝置。具體實作取決於作業系統和裝置。有關詳細資訊，請參閱 POSIX fsync(2) 文件。除了可能的例外情況外，不會提供任何其他引數給完成回呼函式。

fs.ftruncate(fd[, len], callback)#

• fd <整數>
• len <整數> 預設： 0
• callback <函式>
  • err <錯誤>

截斷檔案描述符。除了可能的例外情況外，不會提供任何其他引數給完成回呼函式。

有關詳細資訊，請參閱 POSIX ftruncate(2) 文件。

如果檔案描述符所引用的檔案大於 len 位元組，則檔案中只會保留前 len 位元組。

例如，下列程式只保留檔案的前四個位元組

import { open, close, ftruncate } from 'node:fs';

function closeFd(fd) {
  close(fd, (err) => {
    if (err) throw err;
  });
}

open('temp.txt', 'r+', (err, fd) => {
  if (err) throw err;

  try {
    ftruncate(fd, 4, (err) => {
      closeFd(fd);
      if (err) throw err;
    });
  } catch (err) {
    closeFd(fd);
    if (err) throw err;
  }
}); copy

如果檔案原本小於 len 位元組，則會將檔案延伸，並用空位元組 ('\0') 填滿延伸的部分

如果 len 為負數，則會使用 0。

fs.futimes(fd, atime, mtime, callback)#

• fd <整數>
• atime <數字> | <字串> | <Date>
• mtime <數字> | <字串> | <Date>
• callback <函式>
  • err <錯誤>

變更由提供的檔案描述符參照的物件的檔案系統時間戳記。請參閱 fs.utimes()。

fs.lchmod(path, mode, callback)#

• path <string> | <Buffer> | <URL>
• mode <整數>
• callback <函式>
  • err <Error> | <AggregateError>

變更符號連結的權限。除了可能的例外狀況外，不會提供其他引數給完成回呼。

此方法僅在 macOS 上實作。

請參閱 POSIX lchmod(2) 文件以取得更多詳細資料。

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

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <函式>
  • err <錯誤>

設定符號連結的所有者。除了可能的例外狀況外，不會提供其他引數給完成回呼。

請參閱 POSIX lchown(2) 文件以取得更多詳細資料。

fs.lutimes(path, atime, mtime, callback)#

• path <string> | <Buffer> | <URL>
• atime <數字> | <字串> | <Date>
• mtime <數字> | <字串> | <Date>
• callback <函式>
  • err <錯誤>

變更檔案的存取和修改時間，方式與 fs.utimes() 相同，但差異在於，如果路徑是指符號連結，則不會取消參照連結：而是變更符號連結本身的時間戳記。

除了可能的例外狀況外，不會提供其他引數給完成回呼。

fs.link(existingPath, newPath, callback)#

• existingPath <字串> | <Buffer> | <URL>
• newPath <字串> | <Buffer> | <URL>
• callback <函式>
  • err <錯誤>

從 existingPath 建立到 newPath 的新連結。有關詳細資訊，請參閱 POSIX link(2) 文件。除了可能的例外狀況外，不會提供任何其他引數給完成回呼函式。

fs.lstat(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 傳回的 <fs.Stats> 物件中的數字值是否應為 bigint。預設值：false。
• callback <函式>
  • err <錯誤>
  • stats <fs.Stats>

擷取路徑所指的符號連結的 <fs.Stats>。回呼函式會取得兩個引數 (err, stats)，其中 stats 是 <fs.Stats> 物件。lstat() 與 stat() 相同，但如果 path 是符號連結，則會對連結本身執行 stat，而不是它所指的文件。

有關詳細資訊，請參閱 POSIX lstat(2) 文件。

fs.mkdir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 預設值： false
  • mode <string> | <integer> Windows 不支援。預設值： 0o777。
• callback <函式>
  • err <錯誤>
  • 路徑 <字串> | <未定義> 僅在使用 遞迴 設定為 true 建立目錄時才會提供。

非同步建立目錄。

會提供給 callback 一個可能的例外，如果 遞迴 為 true，則會提供第一個建立的目錄路徑，(err[, 路徑])。如果未建立任何目錄（例如，如果先前已建立），則在 遞迴 為 true 時，路徑 仍可能為 未定義。

選用的 選項 引數可以是指定 模式（權限和黏著位元）的整數，或是一個具有 模式 屬性和 遞迴 屬性的物件，表示是否應建立父目錄。當 路徑 是存在的目錄時呼叫 fs.mkdir() 僅在 遞迴 為 false 時才會導致錯誤。如果 遞迴 為 false 且目錄存在，則會發生 EEXIST 錯誤。

import { mkdir } from 'node:fs';

// Create ./tmp/a/apple, regardless of whether ./tmp and ./tmp/a exist.
mkdir('./tmp/a/apple', { recursive: true }, (err) => {
  if (err) throw err;
}); copy

在 Windows 上，即使使用遞迴，對根目錄使用 fs.mkdir() 也會導致錯誤

import { mkdir } from 'node:fs';

mkdir('/', { recursive: true }, (err) => {
  // => [Error: EPERM: operation not permitted, mkdir 'C:\']
}); copy

請參閱 POSIX mkdir(2) 文件以取得更多詳細資料。

fs.mkdtemp(字首[, 選項], callback)#

• prefix <字串> | <緩衝區> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
• callback <函式>
  • err <錯誤>
  • 目錄 <字串>

建立一個唯一的暫時目錄。

產生六個隨機字元，附加在必要的 字首 後面，以建立一個唯一的暫時目錄。由於平台不一致，請避免在 字首 中使用尾隨 X 字元。一些平台，特別是 BSD，可能會傳回超過六個隨機字元，並用隨機字元取代 字首 中尾隨的 X 字元。

建立的目錄路徑會以字串傳遞給 callback 的第二個參數。

選用的 options 參數可以是指定編碼的字串，或是包含指定要使用的字元編碼的 encoding 屬性的物件。

import { mkdtemp } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';

mkdtemp(join(tmpdir(), 'foo-'), (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Prints: /tmp/foo-itXde2 or C:\Users\...\AppData\Local\Temp\foo-itXde2
}); copy

fs.mkdtemp() 方法會將六個隨機選取的字元直接附加到 prefix 字串。例如，假設有一個目錄 /tmp，如果是要在 /tmp 內部 建立暫時目錄，則 prefix 必須以平台特定的路徑分隔符號 (require('node:path').sep) 作結尾。

import { tmpdir } from 'node:os';
import { mkdtemp } from 'node:fs';

// The parent directory for the new temporary directory
const tmpDir = tmpdir();

// This method is *INCORRECT*:
mkdtemp(tmpDir, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmpabc123`.
  // A new temporary directory is created at the file system root
  // rather than *within* the /tmp directory.
});

// This method is *CORRECT*:
import { sep } from 'node:path';
mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
  if (err) throw err;
  console.log(directory);
  // Will print something similar to `/tmp/abc123`.
  // A new temporary directory is created within
  // the /tmp directory.
}); copy

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

• path <string> | <Buffer> | <URL>
• flags <字串> | <數字> 請參閱 檔案系統 flags 的支援。預設： 'r'。
• mode <字串> | <整數> 預設值： 0o666 (可讀寫)
• callback <函式>
  • err <錯誤>
  • fd <整數>

非同步檔案開啟。請參閱 POSIX open(2) 文件以取得更多詳細資料。

mode 設定檔案模式 (權限和黏著位元)，但僅限於檔案已建立的情況。在 Windows 上，只能控制寫入權限；請參閱 fs.chmod()。

回呼函式取得兩個引數 (err, fd)。

某些字元（< > : " / \ | ? *）在 Windows 中保留，如 命名檔案、路徑和命名空間 所述。在 NTFS 中，如果檔名包含冒號，Node.js 會開啟檔案系統串流，如 此 MSDN 頁面 所述。

基於 fs.open() 的函式也展現此行為：fs.writeFile()、fs.readFile() 等。

fs.openAsBlob(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • type <字串> blob 的選用 MIME 類型。
• 傳回：<Promise> 成功時以 <Blob> 兌現。

傳回一個 <Blob>，其資料由指定的檔案支援。

建立 <Blob> 後，不得修改檔案。任何修改都會導致讀取 <Blob> 資料時發生 DOMException 錯誤。在建立 Blob 時，同步檔案狀態操作，以及每次讀取前，以偵測檔案資料是否已在磁碟中修改。

import { openAsBlob } from 'node:fs';

const blob = await openAsBlob('the.file.txt');
const ab = await blob.arrayBuffer();
blob.stream();const { openAsBlob } = require('node:fs');

(async () => {
  const blob = await openAsBlob('the.file.txt');
  const ab = await blob.arrayBuffer();
  blob.stream();
})();copy

fs.opendir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <字串> | <null> 預設值： 'utf8'
  • bufferSize <數字> 從目錄讀取時在內部緩衝的目錄項目數。較高的值會提升效能，但會使用較多的記憶體。預設值：32
  • recursive <boolean> 預設值： false
• callback <函式>
  • err <錯誤>
  • dir <fs.Dir>

非同步開啟目錄。有關更多詳細資料，請參閱 POSIX opendir(3) 文件。

建立一個 <fs.Dir>，其中包含所有用於從目錄中讀取和清理的進一步功能。

encoding 選項在開啟目錄和後續讀取操作時設定 path 的編碼。

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

• fd <整數>
• buffer <Buffer> | <TypedArray> | <DataView> 將資料寫入的緩衝區。
• offset <integer> 將資料寫入 buffer 的位置。
• length <integer> 要讀取的位元組數。
• position <整數> | <bigint> | <null> 指定從檔案中開始讀取的位置。如果 position 為 null 或 -1 ，資料將從目前的檔案位置讀取，且檔案位置將更新。如果 position 為非負整數，檔案位置將保持不變。
• callback <函式>
  • err <錯誤>
  • bytesRead <整數>
  • buffer <Buffer>

從 fd 指定的檔案讀取資料。

回呼函數會收到三個引數，(err, bytesRead, buffer)。

如果檔案沒有同時修改，當讀取的位元組數為零時，表示已到檔案結尾。

如果此方法呼叫為其 util.promisify() 承諾版本，它會傳回一個承諾，其中包含具有 bytesRead 和 buffer 屬性的 Object。

fs.read(fd[, options], callback)#

• fd <整數>
• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> 預設值： Buffer.alloc(16384)
  • offset <integer> 預設值： 0
  • length <integer> 預設值： buffer.byteLength - offset
  • position <整數> | <bigint> | <null> 預設值： null
• callback <函式>
  • err <錯誤>
  • bytesRead <整數>
  • buffer <Buffer>

類似於 fs.read() 函數，此版本採用一個選用的 options 物件。如果未指定 options 物件，它將預設為上述值。

fs.read(fd, buffer[, options], callback)#

• fd <整數>
• buffer <Buffer> | <TypedArray> | <DataView> 將資料寫入的緩衝區。
• options <Object>
  • offset <integer> 預設值： 0
  • length <integer> 預設值： buffer.byteLength - offset
  • position <整數> | <大整數> 預設值： null
• callback <函式>
  • err <錯誤>
  • bytesRead <整數>
  • buffer <Buffer>

類似於 fs.read() 函數，此版本採用一個選用的 options 物件。如果未指定 options 物件，它將預設為上述值。

fs.readdir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
  • withFileTypes <boolean> 預設值： false
  • recursive <布林值> 如果為 true，則遞迴讀取目錄的內容。在遞迴模式下，它將列出所有檔案、子檔案和目錄。預設值： false。
• callback <函式>
  • err <錯誤>
  • files <字串[]> | <Buffer[]> | <fs.Dirent[]>

讀取目錄的內容。回呼取得兩個引數 (err, files)，其中 files 是目錄中檔案名稱的陣列，不包含 '.' 和 '..'。

請參閱 POSIX readdir(3) 文件以取得更多詳細資料。

選用的 options 引數可以是指定編碼的字串，或是包含 encoding 屬性的物件，用於指定傳遞給回呼的檔案名稱所使用的字元編碼。如果 encoding 設定為 'buffer'，傳回的檔案名稱將傳遞為 <Buffer> 物件。

如果 options.withFileTypes 設定為 true，則 files 陣列將包含 <fs.Dirent> 物件。

fs.readFile(path[, options], callback)#

• path <字串> | <Buffer> | <URL> | <整數> 檔案名稱或檔案描述子
• options <物件> | <字串>
  • 編碼 <字串> | <null> 預設值： null
  • flag <string> 請參閱 檔案系統 flags 的支援。預設值： 'r'。
  • 訊號 <AbortSignal> 允許中斷進行中的 readFile
• callback <函式>
  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

非同步讀取檔案的完整內容。

import { readFile } from 'node:fs';

readFile('/etc/passwd', (err, data) => {
  if (err) throw err;
  console.log(data);
}); copy

callback 傳遞兩個參數 (err, data)，其中 data 是檔案的內容。

如果未指定編碼，則傳回原始緩衝區。

如果 options 是字串，則它會指定編碼

import { readFile } from 'node:fs';

readFile('/etc/passwd', 'utf8', callback); copy

當路徑為目錄時，fs.readFile() 和 fs.readFileSync() 的行為取決於平台。在 macOS、Linux 和 Windows 上，將傳回錯誤。在 FreeBSD 上，將傳回目錄內容的表示形式。

import { readFile } from 'node:fs';

// macOS, Linux, and Windows
readFile('<directory>', (err, data) => {
  // => [Error: EISDIR: illegal operation on a directory, read <directory>]
});

//  FreeBSD
readFile('<directory>', (err, data) => {
  // => null, <data>
}); copy

可以使用 AbortSignal 中止正在進行的請求。如果請求被中止，則會以 AbortError 呼叫 callback。

import { readFile } from 'node:fs';

const controller = new AbortController();
const signal = controller.signal;
readFile(fileInfo[0].name, { signal }, (err, buf) => {
  // ...
});
// When you want to abort the request
controller.abort(); copy

fs.readFile() 函式會將整個檔案緩衝。為將記憶體成本降至最低，在可能的情況下，建議透過 fs.createReadStream() 串流。

中斷正在進行的要求並不會中斷個別作業系統要求，而是中斷 fs.readFile 執行的內部緩衝。

檔案描述子#

1. 任何指定的檔案描述子都必須支援讀取。
2. 如果將檔案描述子指定為 path，則不會自動關閉它。
3. 讀取將從目前位置開始。例如，如果檔案已經有 'Hello World' 且使用檔案描述子讀取六個位元組，則使用相同檔案描述子呼叫 fs.readFile() 會傳回 'World'，而不是 'Hello World'。

效能考量#

fs.readFile() 方法會非同步地將檔案內容讀入記憶體，每次讀取一個區塊，讓事件迴圈在每個區塊之間轉換。這讓讀取作業對其他可能使用底層 libuv 執行緒池的活動影響較小，但這也表示將完整檔案讀入記憶體會花費較長的時間。

額外的讀取負擔會在不同的系統上大幅變動，而且取決於所讀取的檔案類型。如果檔案類型不是一般檔案（例如：管線），而且 Node.js 無法判斷實際檔案大小，每個讀取作業將會載入 64 KiB 的資料。對於一般檔案，每個讀取作業將會處理 512 KiB 的資料。

對於需要盡可能快速讀取檔案內容的應用程式，最好直接使用 fs.read()，並讓應用程式程式碼管理讀取檔案本身的完整內容。

Node.js GitHub 問題 #25741 提供了更多資訊，以及針對不同 Node.js 版本中多個檔案大小的 fs.readFile() 效能進行詳細分析。

fs.readlink(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
• callback <函式>
  • err <錯誤>
  • linkString <string> | <Buffer>

讀取 path 所指的符號連結內容。回呼函式會取得兩個參數 (err, linkString)。

請參閱 POSIX readlink(2) 文件以取得更多詳細資料。

選用的 options 參數可以是指定編碼的字串，或是包含 encoding 屬性的物件，用來指定傳遞給回呼函式的連結路徑所使用的字元編碼。如果 encoding 設為 'buffer'，傳回的連結路徑將會傳遞為 <Buffer> 物件。

fs.readv(fd, buffers[, position], callback)#

• fd <整數>
• buffers <ArrayBufferView[]>
• position <integer> | <null> 預設值：null
• callback <函式>
  • err <錯誤>
  • bytesRead <整數>
  • buffers <ArrayBufferView[]>

從由 fd 指定的檔案中讀取並使用 readv() 寫入至 ArrayBufferView 陣列。

position 是從檔案開頭開始計算的偏移量，資料應從該偏移量開始讀取。如果 typeof position !== 'number'，資料將從目前位置開始讀取。

回呼函式將傳入三個參數：err、bytesRead 和 buffers。bytesRead 是從檔案中讀取的位元組數。

如果這個方法作為其 util.promisify() 承諾版本呼叫，它會傳回一個承諾，其內容為具備 bytesRead 和 buffers 屬性的 Object。

fs.realpath(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
• callback <函式>
  • err <錯誤>
  • resolvedPath <string> | <Buffer>

非同步計算標準路徑名稱，方法是解析 .、.. 和符號連結。

標準路徑名稱不一定是唯一的。硬連結和繫結掛載可以透過許多路徑名稱公開檔案系統實體。

這個函式會像 realpath(3) 一樣運作，但有一些例外：

1. 在不分大小寫的檔案系統上不會執行大小寫轉換。

2. 符號連結的最大數量與平台無關，而且通常（遠）高於原生 realpath(3) 實作支援的數量。

callback 會取得兩個引數 (err, resolvedPath)。可以使用 process.cwd 來解析相對路徑。

僅支援可轉換為 UTF8 字串的路徑。

選用的 options 引數可以是指定編碼的字串，或是一個物件，其中包含指定要傳遞給 callback 的路徑所使用的字元編碼的 encoding 屬性。如果 encoding 設為 'buffer'，傳回的路徑會傳遞為 <Buffer> 物件。

如果 path 解析為 socket 或管線，函式會傳回該物件的系統相依名稱。

fs.realpath.native(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <字串> | <物件>
  • 編碼 <字串> 預設值： 'utf8'
• callback <函式>
  • err <錯誤>
  • resolvedPath <string> | <Buffer>

非同步 realpath(3)。

callback 會取得兩個引數 (err, resolvedPath)。

僅支援可轉換為 UTF8 字串的路徑。

選用的 options 引數可以是指定編碼的字串，或是一個物件，其中包含指定要傳遞給 callback 的路徑所使用的字元編碼的 encoding 屬性。如果 encoding 設為 'buffer'，傳回的路徑會傳遞為 <Buffer> 物件。

在 Linux 上，當 Node.js 與 musl libc 連結時，必須在 /proc 上掛載 procfs 檔案系統才能讓此函數運作。Glibc 沒有這個限制。

fs.rename(oldPath, newPath, callback)#

• oldPath <string> | <Buffer> | <URL>
• newPath <字串> | <Buffer> | <URL>
• callback <函式>
  • err <錯誤>

非同步將 oldPath 的檔案重新命名為 newPath 提供的路徑名稱。如果 newPath 已存在，將會覆寫它。如果 newPath 有目錄，將會產生錯誤。除了可能的例外狀況外，不會將其他引數傳遞給完成 callback。

另請參閱：rename(2)。

import { rename } from 'node:fs';

rename('oldFile.txt', 'newFile.txt', (err) => {
  if (err) throw err;
  console.log('Rename complete!');
}); copy

fs.rmdir(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • maxRetries <integer> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 錯誤，Node.js 會以線性遞增等待時間重試操作，每次嘗試增加 retryDelay 毫秒。此選項表示重試次數。如果 recursive 選項不是 true，則會忽略此選項。預設值：0。
  • recursive <boolean> 如果為 true，則執行遞迴目錄移除。在遞迴模式中，會在失敗時重試操作。預設值：false。已棄用。
  • retryDelay <整數> 重試之間等待的時間（毫秒）。如果 recursive 選項不是 true，則會忽略此選項。預設值：100。
• callback <函式>
  • err <錯誤>

非同步 rmdir(2)。除了可能的例外情況外，不會提供其他引數給完成回呼函式。

在檔案（而非目錄）上使用 fs.rmdir() 會在 Windows 上產生 ENOENT 錯誤，在 POSIX 上產生 ENOTDIR 錯誤。

若要獲得類似 Unix 指令 rm -rf 的行為，請使用 fs.rm()，並搭配選項 { recursive: true, force: true }。

fs.rm(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <布林> 當為 true 時，如果 path 不存在，則會忽略例外。預設值：false。
  • maxRetries <整數> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 錯誤，Node.js 會以線性遞減等待時間重試作業，每次嘗試會增加 retryDelay 毫秒。此選項表示重試次數。如果 recursive 選項不是 true，則會忽略此選項。預設值：0。
  • recursive <boolean> 如果為 true，則執行遞迴移除。在遞迴模式中，操作會在失敗時重試。預設值：false。
  • retryDelay <整數> 重試之間等待的時間（毫秒）。如果 recursive 選項不是 true，則會忽略此選項。預設值：100。
• callback <函式>
  • err <錯誤>

非同步移除檔案和目錄（仿照標準 POSIX rm 實用程式）。除了可能的例外情況外，不會提供其他引數給完成回呼函式。

fs.stat(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 傳回的 <fs.Stats> 物件中的數字值是否應為 bigint。預設值：false。
• callback <函式>
  • err <錯誤>
  • stats <fs.Stats>

非同步 stat(2)。回呼函式會取得兩個引數 (err, stats)，其中 stats 是 <fs.Stats> 物件。

如果發生錯誤，err.code 將會是 常見系統錯誤 之一。

fs.stat() 會追蹤符號連結。使用 fs.lstat() 來查看連結本身。

不建議使用 fs.stat() 來檢查檔案是否存在，然後再呼叫 fs.open()、fs.readFile() 或 fs.writeFile()。相反地，使用者程式碼應該直接開啟/讀取/寫入檔案，並處理檔案不存在時引發的錯誤。

若要檢查檔案是否存在而不進行後續操作，建議使用 fs.access()。

例如，假設有以下目錄結構

- txtDir
-- file.txt
- app.js copy

下一個程式會檢查給定路徑的統計資料

import { stat } from 'node:fs';

const pathsToCheck = ['./txtDir', './txtDir/file.txt'];

for (let i = 0; i < pathsToCheck.length; i++) {
  stat(pathsToCheck[i], (err, stats) => {
    console.log(stats.isDirectory());
    console.log(stats);
  });
} copy

產生的輸出將類似於

true
Stats {
  dev: 16777220,
  mode: 16877,
  nlink: 3,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214262,
  size: 96,
  blocks: 0,
  atimeMs: 1561174653071.963,
  mtimeMs: 1561174614583.3518,
  ctimeMs: 1561174626623.5366,
  birthtimeMs: 1561174126937.2893,
  atime: 2019-06-22T03:37:33.072Z,
  mtime: 2019-06-22T03:36:54.583Z,
  ctime: 2019-06-22T03:37:06.624Z,
  birthtime: 2019-06-22T03:28:46.937Z
}
false
Stats {
  dev: 16777220,
  mode: 33188,
  nlink: 1,
  uid: 501,
  gid: 20,
  rdev: 0,
  blksize: 4096,
  ino: 14214074,
  size: 8,
  blocks: 8,
  atimeMs: 1561174616618.8555,
  mtimeMs: 1561174614584,
  ctimeMs: 1561174614583.8145,
  birthtimeMs: 1561174007710.7478,
  atime: 2019-06-22T03:36:56.619Z,
  mtime: 2019-06-22T03:36:54.584Z,
  ctime: 2019-06-22T03:36:54.584Z,
  birthtime: 2019-06-22T03:26:47.711Z
} copy

fs.statfs(path[, options], callback)#

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 傳回的 <fs.StatFs> 物件中的數值是否應為 bigint。預設值：false。
• callback <函式>
  • err <錯誤>
  • stats <fs.StatFs>

非同步 statfs(2)。傳回包含 path 的已掛載檔案系統的資訊。callback 會取得兩個參數 (err, stats)，其中 stats 是 <fs.StatFs> 物件。

如果發生錯誤，err.code 將會是 常見系統錯誤 之一。

fs.symlink(target, path[, type], callback)#

• target <string> | <Buffer> | <URL>
• path <string> | <Buffer> | <URL>
• type <string> | <null> 預設值：null
• callback <函式>
  • err <錯誤>

建立名為 path 的連結，指向 target。除了可能的例外狀況之外，不會將其他參數傳遞給完成 callback。

請參閱 POSIX symlink(2) 文件以取得更多詳細資訊。

type 參數僅在 Windows 上可用，且在其他平台上會被忽略。它可以設定為 'dir'、'file' 或 'junction'。如果 type 參數不是字串，Node.js 將自動偵測 target 類型並使用 'file' 或 'dir'。如果 target 不存在，將使用 'file'。Windows 交接點需要目標路徑為絕對路徑。使用 'junction' 時，target 參數會自動標準化為絕對路徑。NTFS 磁碟區上的交接點只能指向目錄。

相對目標相對於連結的父目錄。

import { symlink } from 'node:fs';

symlink('./mew', './mewtwo', callback); copy

上述範例會建立一個符號連結 mewtwo，指向同一個目錄中的 mew

$ tree .
.
├── mew
└── mewtwo -> ./mew copy

fs.truncate(path[, len], callback)#

• path <string> | <Buffer> | <URL>
• len <整數> 預設： 0
• callback <函式>
  • err <Error> | <AggregateError>

截斷檔案。除了可能的例外情況外，不會將其他參數傳遞給完成回呼。也可以將檔案描述符傳遞為第一個參數。在這種情況下，會呼叫 fs.ftruncate()。

import { truncate } from 'node:fs';
// Assuming that 'path/file.txt' is a regular file.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was truncated');
});const { truncate } = require('node:fs');
// Assuming that 'path/file.txt' is a regular file.
truncate('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was truncated');
});copy

傳遞檔案描述符已不建議使用，未來可能會導致發生錯誤。

請參閱 POSIX truncate(2) 文件以取得更多詳細資訊。

fs.unlink(path, callback)#

• path <string> | <Buffer> | <URL>
• callback <函式>
  • err <錯誤>

非同步移除檔案或符號連結。除了可能的例外情況外，不會將其他參數傳遞給完成回呼。

import { unlink } from 'node:fs';
// Assuming that 'path/file.txt' is a regular file.
unlink('path/file.txt', (err) => {
  if (err) throw err;
  console.log('path/file.txt was deleted');
}); copy

fs.unlink() 無法在目錄上執行，無論目錄是否為空。若要移除目錄，請使用 fs.rmdir()。

請參閱 POSIX unlink(2) 文件以取得更多詳細資訊。

fs.unwatchFile(filename[, listener])#

• filename <字串> | <Buffer> | <URL>
• listener <函數> 選擇性，先前使用 fs.watchFile() 附加的監聽器

停止監控 filename 的變更。如果指定 listener，則只移除該特定監聽器。否則，將移除所有監聽器，有效停止監控 filename。

使用未受監控的檔案名稱呼叫 fs.unwatchFile() 是一項無操作，而不是錯誤。

使用 fs.watch() 比 fs.watchFile() 和 fs.unwatchFile() 更有效率。如果可能，應使用 fs.watch() 取代 fs.watchFile() 和 fs.unwatchFile()。

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

• path <string> | <Buffer> | <URL>
• atime <數字> | <字串> | <Date>
• mtime <數字> | <字串> | <Date>
• callback <函式>
  • err <錯誤>

變更 path 參照的物件的檔案系統時間戳記。

atime 和 mtime 參數遵循以下規則

• 值可以是表示 Unix 紀元時間（秒）的數字、Date 或數字字串，例如 '123456789.0'。
• 如果無法將值轉換為數字，或為 NaN、Infinity 或 -Infinity，則會擲回 Error。

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