Node.js v25.0.0 文件

類: FileHandle#

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

<FileHandle> 物件的例項由 fsPromises.open() 方法建立。

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

如果一個 <FileHandle> 沒有使用 filehandle.close() 方法關閉，它將嘗試自動關閉檔案描述符併發出一個程序警告，以幫助防止記憶體洩漏。請不要依賴此行為，因為它可能不可靠，檔案可能不會被關閉。相反，請始終顯式關閉 <FileHandle>s。Node.js 將來可能會更改此行為。

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

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

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

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

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

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

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

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

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 中任意一個或多個的按位或組成的掩碼（例如 fs.constants.W_OK | fs.constants.R_OK）。請檢查檔案訪問常量以瞭解 mode 的可能值。

如果可訪問性檢查成功，Promise 將兌現為無值。如果任何可訪問性檢查失敗，Promise 將被拒絕並帶有一個 <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.open() 之前使用 fsPromises.access() 檢查檔案的可訪問性。這樣做會引入競態條件，因為其他程序可能會在兩次呼叫之間更改檔案的狀態。相反，使用者程式碼應該直接開啟/讀取/寫入檔案，並處理檔案不可訪問時引發的錯誤。

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

• path <string> | <Buffer> | <URL> | <FileHandle> 檔名或 <FileHandle>
• data <string> | <Buffer>
• options <Object> | <string>
  • encoding <string> | <null> 預設: 'utf8'
  • mode <integer> 預設: 0o666
  • flag <string> 參見檔案系統 flags 的支援。預設: 'a'。
  • flush <boolean> 如果為 true，則在關閉底層檔案描述符之前將其重新整理。預設: false。
• 返回: <Promise> 成功時兌現為 undefined。

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

如果 options 是一個字串，則它指定了 encoding。

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> 指定複製操作行為的可選修飾符。可以透過兩個或多個值的按位或來建立一個掩碼（例如 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 <boolean> 當 force 為 false 且目標存在時，丟擲錯誤。預設: false。
  • filter <Function> 用於過濾複製的檔案/目錄的函式。返回 true 以複製該項，返回 false 以忽略它。當忽略一個目錄時，其所有內容也將被跳過。也可以返回一個解析為 true 或 false 的 Promise。預設: undefined。
    • src <string> 要複製的源路徑。
    • dest <string> 要複製到的目標路徑。
    • 返回: <boolean> | <Promise> 一個可以強制轉換為 boolean 的值或一個兌現為此類值的 Promise。
  • force <boolean> 覆蓋現有的檔案或目錄。如果將此設定為 false 且目標存在，複製操作將忽略錯誤。使用 errorOnExist 選項來更改此行為。預設: true。
  • mode <integer> 複製操作的修飾符。預設: 0。參見 fsPromises.copyFile() 的 mode 標誌。
  • preserveTimestamps <boolean> 當為 true 時，將保留 src 的時間戳。預設: false。
  • recursive <boolean> 遞迴複製目錄 預設: false
  • verbatimSymlinks <boolean> 當為 true 時，將跳過符號連結的路徑解析。預設: false
• 返回: <Promise> 成功時兌現為 undefined。

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

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

fsPromises.glob(pattern[, options])#

• pattern <string> | <string[]>
• options <Object>
  • cwd <string> | <URL> 當前工作目錄。預設: process.cwd()
  • exclude <Function> | <string[]> 用於過濾檔案/目錄的函式或要排除的 glob 模式列表。如果提供函式，返回 true 表示排除該項，返回 false 表示包含。預設: undefined。如果提供字串陣列，則每個字串都應為指定要排除路徑的 glob 模式。注意：不支援否定模式（例如 `!foo.js`）。
  • withFileTypes <boolean> 如果 glob 應返回 Dirents 形式的路徑，則為 true，否則為 false。預設: false。
• 返回: <AsyncIterator> 一個 AsyncIterator，它產生與模式匹配的檔案路徑。

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

for await (const entry of glob('**/*.js'))
  console.log(entry);const { glob } = require('node:fs/promises');

(async () => {
  for await (const entry of glob('**/*.js'))
    console.log(entry);
})();copy

fsPromises.lchmod(path, mode)#

• path <string> | <Buffer> | <URL>
• mode <integer>
• 返回: <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 <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 返回: <Promise> 成功時兌現為 undefined。

以與 fsPromises.utimes() 相同的方式更改檔案的訪問和修改時間，不同之處在於如果路徑引用一個符號連結，則該連結不會被解引用：而是更改符號連結本身的時間戳。

fsPromises.link(existingPath, newPath)#

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <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 引用一個符號連結，在這種情況下，統計的是連結本身，而不是它引用的檔案。有關更多詳細資訊，請參閱 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 <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• 返回: <Promise> 兌現一個包含新建立的臨時目錄檔案系統路徑的字串。

建立一個唯一的臨時目錄。透過在提供的 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.mkdtempDisposable(prefix[, options])#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• 返回: <Promise> 兌現一個非同步可處置物件的 Promise
  • path <string> 建立的目錄的路徑。
  • remove <AsyncFunction> 一個刪除已建立目錄的函式。
  • [Symbol.asyncDispose] <AsyncFunction> 與 remove 相同。

生成的 Promise 持有一個非同步可處置物件，其 path 屬性儲存了建立的目錄路徑。當該物件被處置時，如果目錄仍然存在，它及其內容將被非同步刪除。如果目錄無法刪除，處置將丟擲錯誤。該物件有一個非同步的 remove() 方法，它將執行相同的任務。

此函式和結果物件上的處置函式都是非同步的，因此應與 await + await using 一起使用，如 await using dir = await fsPromises.mkdtempDisposable('prefix')。

有關詳細資訊，請參閱 fsPromises.mkdtemp() 的文件。

可選的 options 引數可以是一個指定編碼的字串，或一個帶有 encoding 屬性的物件，指定要使用的字元編碼。

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

• path <string> | <Buffer> | <URL>
• flags <string> | <number> 參見檔案系統 flags 的支援。預設: 'r'。
• mode <string> | <integer> 如果檔案被建立，則設定檔案模式（許可權和粘滯位）。預設: 0o666 (可讀可寫)
• 返回: <Promise> 兌現一個 <FileHandle> 物件。

開啟一個 <FileHandle>。

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

某些字元 (< > : " / \ | ? *) 在 Windows 下是保留的，如 命名檔案、路徑和名稱空間 所述。在 NTFS 下，如果檔名包含冒號，Node.js 將開啟一個檔案系統流，如 此 MSDN 頁面 所述。

fsPromises.opendir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • encoding <string> | <null> 預設: 'utf8'
  • bufferSize <number> 從目錄讀取時內部緩衝的目錄條目數。較高的值會導致更好的效能，但記憶體使用量也更高。預設: 32
  • recursive <boolean> 解析的 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 <string> | <Object>
  • encoding <string> 預設值： 'utf8'
  • withFileTypes <boolean> 預設: false
  • recursive <boolean> 如果為 true，則遞迴讀取目錄的內容。在遞迴模式下，它將列出所有檔案、子檔案和目錄。預設: false。
• 返回: <Promise> 兌現一個包含目錄中檔名陣列的 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 <Object> | <string>
  • encoding <string> | <null> 預設: null
  • flag <string> 參見檔案系統 flags 的支援。預設: 'r'。
  • signal <AbortSignal> 允許中止正在進行的 readFile 操作
• 返回: <Promise> 兌現檔案的內容。

非同步讀取檔案的全部內容。

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

如果 options 是一個字串，則它指定了編碼。

當 path 是一個目錄時，fsPromises.readFile() 的行為是平臺特定的。在 macOS、Linux 和 Windows 上，Promise 將被拒絕並帶有一個錯誤。在 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。如果請求被中止，返回的 Promise 將被拒絕並帶有一個 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 <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• 返回: <Promise> 成功後兌現 linkString。

讀取 path 所引用的符號連結的內容。有關更多詳細資訊，請參閱 POSIX readlink(2) 文件。成功後，Promise 將兌現 linkString。

可選的 options 引數可以是一個指定編碼的字串，或一個帶有 encoding 屬性的物件，指定用於返回的連結路徑的字元編碼。如果 encoding 設定為 'buffer'，返回的連結路徑將作為 <Buffer> 物件傳遞。

fsPromises.realpath(path[, options])#

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• 返回: <Promise> 成功後兌現解析的路徑。

使用與 fs.realpath.native() 函式相同的語義來確定 path 的實際位置。

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

可選的 options 引數可以是一個指定編碼的字串，或一個帶有 encoding 屬性的物件，指定用於路徑的字元編碼。如果 encoding 設定為 'buffer'，返回的路徑將作為 <Buffer> 物件傳遞。

在 Linux 上，當 Node.js 連結到 musl libc 時，procfs 檔案系統必須掛載在 /proc 上才能使此函式正常工作。Glibc 沒有此限制。

fsPromises.rename(oldPath, newPath)#

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• 返回: <Promise> 成功時兌現為 undefined。

將 oldPath 重新命名為 newPath。

fsPromises.rmdir(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object> 目前沒有公開的選項。以前曾有用於 recursive、maxBusyTries 和 emfileWait 的選項，但它們已被棄用和移除。為了向後相容，仍然接受 options 引數，但不會使用它。
• 返回: <Promise> 成功時兌現為 undefined。

移除由 path 標識的目錄。

在檔案（而不是目錄）上使用 fsPromises.rmdir() 會導致在 Windows 上 promise 被拒絕並返回 ENOENT 錯誤，在 POSIX 上則返回 ENOTDIR 錯誤。

要獲得類似於 Unix 命令 rm -rf 的行為，請使用 fsPromises.rm() 並設定選項 { recursive: true, force: true }。

fsPromises.rm(path[, options])#

• path <string> | <Buffer> | <URL>
• options <Object>
  • force <boolean> 當為 true 時，如果 path 不存在，異常將被忽略。預設值：false。
  • maxRetries <integer> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 錯誤，Node.js 將在每次嘗試時以 retryDelay 毫秒的線性退避等待時間重試操作。此選項表示重試次數。如果 recursive 選項不為 true，則此選項將被忽略。預設值：0。
  • recursive <boolean> 如果為 true，則執行遞迴目錄刪除。在遞迴模式下，操作失敗時會重試。預設值：false。
  • retryDelay <integer> 兩次重試之間等待的時間（以毫秒為單位）。如果 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 引數為 null，Node.js 將自動檢測 target 型別並使用 'file' 或 'dir'。如果 target 不存在，將使用 'file'。Windows 目錄連線點要求目標路徑是絕對路徑。使用 'junction' 時，target 引數將自動規範化為絕對路徑。NTFS 捲上的目錄連線點只能指向目錄。

fsPromises.truncate(path[, len])#

• path <string> | <Buffer> | <URL>
• len <integer> 預設: 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 <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• 返回: <Promise> 成功時兌現為 undefined。

更改 path 所引用物件的檔案系統時間戳。

atime 和 mtime 引數遵循以下規則

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

fsPromises.watch(filename[, options])#

• filename <string> | <Buffer> | <URL>
• options <string> | <Object>
  • persistent <boolean> 指示只要檔案被監視，程序是否應繼續執行。預設值：true。
  • recursive <boolean> 指示是否應監視所有子目錄，或僅監視當前目錄。這在指定目錄時適用，並且僅在受支援的平臺上有效（請參閱注意事項）。預設值：false。
  • encoding <string> 指定用於傳遞給監聽器的檔名的字元編碼。預設值：'utf8'。
  • signal <AbortSignal> 一個 <AbortSignal>，用於發出監視器應停止的訊號。
  • maxQueue <number> 指定在返回的 <AsyncIterator> 的迭代之間要排隊的事件數量。預設值：2048。
  • overflow <string> 當有比 maxQueue 允許的更多事件要排隊時，可以是 'ignore' 或 'throw'。'ignore' 表示溢位事件被丟棄併發出警告，而 'throw' 表示丟擲異常。預設值：'ignore'。
• 返回：<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 <string> | <Buffer> | <TypedArray> | <DataView> | <AsyncIterable> | <Iterable> | <Stream>
• options <Object> | <string>
  • encoding <string> | <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 是緩衝區，則忽略 encoding 選項。

如果 options 是一個字串，則它指定了編碼。

mode 選項僅影響新建立的檔案。有關更多詳細資訊，請參見 fs.open()。

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

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

與 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#

• 型別：<Object>

返回一個包含檔案系統操作常用常量的物件。該物件與 fs.constants 相同。有關更多詳細資訊，請參閱 FS 常量。

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

• path <string> | <Buffer> | <URL>
• mode <integer> 預設: fs.constants.F_OK
• callback <Function>
  • err <Error>

測試使用者對 path 指定的檔案或目錄的許可權。mode 引數是一個可選的整數，指定要執行的可訪問性檢查。mode 應該是值 fs.constants.F_OK 或由 fs.constants.R_OK、fs.constants.W_OK 和 fs.constants.X_OK 中任意一個或多個的按位或組成的掩碼（例如 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 <Object> | <string>
  • encoding <string> | <null> 預設: 'utf8'
  • mode <integer> 預設: 0o666
  • flag <string> 參見檔案系統 flags 的支援。預設: 'a'。
  • flush <boolean> 如果為 true，則在關閉底層檔案描述符之前將其重新整理。預設: false。
• callback <Function>
  • err <Error>

非同步地將資料追加到檔案中，如果檔案尚不存在則建立檔案。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 <Function>
  • err <Error>

非同步地更改檔案的許可權。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

有關更多詳細資訊，請參閱 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.chown(path, uid, gid, callback)#

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

非同步地更改檔案的所有者和使用者組。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

fs.close(fd[, callback])#

• fd <integer>
• callback <Function>
  • err <Error>

關閉檔案描述符。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

在任何其他 fs 操作正在使用的檔案描述符 (fd) 上呼叫 fs.close() 可能會導致未定義的行為。

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

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

• src <string> | <Buffer> | <URL> 要複製的原始檔名
• dest <string> | <Buffer> | <URL> 複製操作的目標檔名
• mode <integer> 複製操作的修飾符。預設值：0。
• callback <Function>
  • err <Error>

非同步地將 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 <boolean> 當 force 為 false 且目標存在時，丟擲錯誤。預設: false。
  • filter <Function> 用於過濾複製的檔案/目錄的函式。返回 true 以複製該項，返回 false 以忽略它。當忽略一個目錄時，其所有內容也將被跳過。也可以返回一個解析為 true 或 false 的 Promise。預設: undefined。
    • src <string> 要複製的源路徑。
    • dest <string> 要複製到的目標路徑。
    • 返回: <boolean> | <Promise> 一個可以強制轉換為 boolean 的值或一個兌現為此類值的 Promise。
  • force <boolean> 覆蓋現有的檔案或目錄。如果將此設定為 false 且目標存在，複製操作將忽略錯誤。使用 errorOnExist 選項來更改此行為。預設: true。
  • mode <integer> 複製操作的修飾符。預設值：0。請參閱 fs.copyFile() 的 mode 標誌。
  • preserveTimestamps <boolean> 當為 true 時，將保留 src 的時間戳。預設: false。
  • recursive <boolean> 遞迴複製目錄 預設: false
  • verbatimSymlinks <boolean> 當為 true 時，將跳過符號連結的路徑解析。預設: false
• callback <Function>
  • err <Error>

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

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

fs.createReadStream(path[, options])#

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

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 選項，可以覆蓋 open、read 和 close 對應的 fs 實現。當提供 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 <string> | <Object>
  • flags <string> 請參閱對檔案系統 flags 的支援。預設值：'w'。
  • encoding <string> 預設值： 'utf8'
  • fd <integer> | <FileHandle> 預設值：null
  • mode <integer> 預設: 0o666
  • autoClose <boolean> 預設: true
  • emitClose <boolean> 預設: true
  • start <integer>
  • fs <Object> | <null> 預設值：null
  • signal <AbortSignal> | <null> 預設值：null
  • highWaterMark <number> 預設: 16384
  • flush <boolean> 如果為 true，則在關閉底層檔案描述符之前將其重新整理。預設: false。
• 返回: <fs.WriteStream>

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

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

預設情況下，流在被銷燬後會發出 'close' 事件。將 emitClose 選項設定為 false 以更改此行為。

透過提供 fs 選項，可以覆蓋 open、write、writev 和 close 對應的 fs 實現。覆蓋 write() 而不覆蓋 writev() 會降低效能，因為一些最佳化 (_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 <Function>
  • exists <boolean>

透過檢查檔案系統來測試給定 path 處的元素是否存在。然後用 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() 的原因之一。

如果 path 是一個符號連結，它會被跟隨。因此，如果 path 存在但指向一個不存在的元素，回撥函式將接收到值 false。

不建議在呼叫 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 <integer>
• mode <string> | <integer>
• callback <Function>
  • err <Error>

設定檔案的許可權。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

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

• fd <integer>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

設定檔案的所有者。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

fs.fdatasync(fd, callback)#

• fd <integer>
• callback <Function>
  • err <Error>

強制所有與檔案關聯的當前排隊的 I/O 操作進入作業系統的同步 I/O 完成狀態。詳情請參閱 POSIX fdatasync(2) 文件。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

• fd <integer>
• options <Object>
  • bigint <boolean> 返回的 <fs.Stats> 物件中的數值是否應為 bigint。預設: false。
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

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

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

fs.fsync(fd, callback)#

• fd <integer>
• callback <Function>
  • err <Error>

請求將開啟的檔案描述符的所有資料重新整理到儲存裝置。具體實現是作業系統和裝置特定的。詳情請參閱 POSIX fsync(2) 文件。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

• fd <integer>
• len <integer> 預設: 0
• callback <Function>
  • err <Error>

截斷檔案描述符。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

有關更多詳細資訊，請參閱 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 <integer>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

更改所提供的檔案描述符引用的物件的檔案系統時間戳。請參閱 fs.utimes()。

fs.glob(pattern[, options], callback)#

• pattern <string> | <string[]>

• options <Object>

  • cwd <string> | <URL> 當前工作目錄。預設: process.cwd()
  • exclude <Function> | <string[]> 用於過濾檔案/目錄的函式，或要排除的 glob 模式列表。如果提供函式，返回 true 以排除專案，返回 false 以包含專案。預設值：undefined。
  • withFileTypes <boolean> 如果 glob 應返回 Dirents 形式的路徑，則為 true，否則為 false。預設: false。

• callback <Function>

  • err <Error>

• 檢索與指定模式匹配的檔案。

import { glob } from 'node:fs';

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});const { glob } = require('node:fs');

glob('**/*.js', (err, matches) => {
  if (err) throw err;
  console.log(matches);
});copy

fs.lchmod(path, mode, callback)#

• path <string> | <Buffer> | <URL>
• mode <integer>
• callback <Function>
  • err <Error> | <AggregateError>

更改符號連結的許可權。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

此方法僅在 macOS 上實現。

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

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

• path <string> | <Buffer> | <URL>
• uid <integer>
• gid <integer>
• callback <Function>
  • err <Error>

設定符號連結的所有者。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

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

• path <string> | <Buffer> | <URL>
• atime <number> | <string> | <Date>
• mtime <number> | <string> | <Date>
• callback <Function>
  • err <Error>

以與 fs.utimes() 相同的方式更改檔案的訪問和修改時間，不同之處在於，如果路徑指向一個符號連結，則連結本身不會被解引用：而是更改符號連結本身的時間戳。

除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

fs.link(existingPath, newPath, callback)#

• existingPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

建立從 existingPath 到 newPath 的新連結。有關更多詳細資訊，請參閱 POSIX link(2) 文件。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返回的 <fs.Stats> 物件中的數值是否應為 bigint。預設: false。
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

檢索路徑所引用的符號連結的 <fs.Stats>。回撥函式接收兩個引數 (err, stats)，其中 stats 是一個 <fs.Stats> 物件。lstat() 與 stat() 相同，不同之處在於如果 path 是一個符號連結，那麼會獲取連結本身的狀態，而不是它所引用的檔案。

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

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

• path <string> | <Buffer> | <URL>
• options <Object> | <integer>
  • recursive <boolean> 預設: false
  • mode <string> | <integer> 在 Windows 上不支援。預設: 0o777。
• callback <Function>
  • err <Error>
  • path <string> | <undefined> 僅在 recursive 設定為 true 並建立目錄時存在。

非同步地建立目錄。

回撥函式接收一個可能的異常，並且如果 recursive 是 true，則接收第一個建立的目錄路徑 (err[, path])。當 recursive 是 true 時，如果未建立目錄（例如，如果它之前已建立），path 仍然可以是 undefined。

可選的 options 引數可以是一個指定 mode（許可權和粘滯位）的整數，或者是一個帶有 mode 屬性和 recursive 屬性（指示是否應建立父目錄）的物件。當 path 是一個已存在的目錄時，只有在 recursive 為 false 時呼叫 fs.mkdir() 才會導致錯誤。如果 recursive 為 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(prefix[, options], callback)#

• prefix <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• callback <Function>
  • err <Error>
  • directory <string>

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

生成六個隨機字元附加在必需的 prefix 後面，以建立一個唯一的臨時目錄。由於平臺不一致，請避免在 prefix 中使用尾隨的 X 字元。某些平臺，特別是 BSD，可以返回超過六個隨機字元，並用隨機字元替換 prefix 中的尾隨 X 字元。

建立的目錄路徑作為字串傳遞給回撥函式的第二個引數。

可選的 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 <string> | <number> 參見檔案系統 flags 的支援。預設: 'r'。
• mode <string> | <integer> 預設值：0o666（可讀可寫）
• callback <Function>
  • err <Error>
  • fd <integer>

非同步檔案開啟。有關更多詳細資訊，請參閱 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 <string> blob 的可選 mime 型別。
• 返回：<Promise> 成功時兌現為一個 <Blob>。

返回一個 <Blob>，其資料由給定檔案支援。

在建立 <Blob> 後不得修改檔案。任何修改都將導致讀取 <Blob> 資料時失敗並返回 DOMException 錯誤。在建立 Blob 時以及每次讀取之前，都會對檔案進行同步的 stat 操作，以檢測檔案資料在磁碟上是否已被修改。

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 <string> | <null> 預設: 'utf8'
  • bufferSize <number> 從目錄讀取時內部緩衝的目錄條目數。較高的值會導致更好的效能，但記憶體使用量也更高。預設: 32
  • recursive <boolean> 預設: false
• callback <Function>
  • err <Error>
  • dir <fs.Dir>

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

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

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

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

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> 將要寫入資料的緩衝區。
• offset <integer> 在 buffer 中寫入資料的位置。
• length <integer> 要讀取的位元組數。
• position <integer> | <bigint> | <null> 指定從檔案中的何處開始讀取。如果 position 是 null 或 -1，則將從當前檔案位置讀取資料，並且檔案位置將被更新。如果 position 是一個非負整數，則檔案位置將保持不變。
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

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

回撥函式接收三個引數：(err, bytesRead, buffer)。

如果檔案沒有被併發修改，當讀取的位元組數為零時，即到達檔案末尾。

如果此方法作為其 util.promisify() 版本被呼叫，它將返回一個 promise，該 promise 解析為一個帶有 bytesRead 和 buffer 屬性的 Object。

fs.read() 方法從檔案描述符 (fd) 指定的檔案中讀取資料。length 引數指示 Node.js 將嘗試從核心讀取的最大位元組數。然而，由於各種原因，實際讀取的位元組數 (bytesRead) 可能低於指定的 length。

例如：

• 如果檔案短於指定的 length，bytesRead 將被設定為實際讀取的位元組數。
• 如果在緩衝區被填滿之前檔案遇到 EOF（檔案結束），Node.js 將讀取所有可用位元組直到遇到 EOF，並且回撥中的 bytesRead 引數將指示實際讀取的位元組數，這可能小於指定的 length。
• 如果檔案位於慢速網路檔案系統上或在讀取期間遇到任何其他問題，bytesRead 可能低於指定的 length。

因此，在使用 fs.read() 時，檢查 bytesRead 值以確定實際從檔案中讀取了多少位元組非常重要。根據您的應用程式邏輯，您可能需要處理 bytesRead 低於指定 length 的情況，例如，如果您需要最小數量的位元組，則可以將讀取呼叫包裝在迴圈中。

此行為類似於 POSIX preadv2 函式。

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

• fd <integer>
• options <Object>
  • buffer <Buffer> | <TypedArray> | <DataView> 預設值：Buffer.alloc(16384)
  • offset <integer> 預設: 0
  • length <integer> 預設: buffer.byteLength - offset
  • position <integer> | <bigint> | <null> 預設值：null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

與 fs.read() 函式類似，此版本接受一個可選的 options 物件。如果未指定 options 物件，則將使用上述預設值。

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

• fd <integer>
• buffer <Buffer> | <TypedArray> | <DataView> 將要寫入資料的緩衝區。
• options <Object>
  • offset <integer> 預設: 0
  • length <integer> 預設: buffer.byteLength - offset
  • position <integer> | <bigint> 預設值：null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffer <Buffer>

與 fs.read() 函式類似，此版本接受一個可選的 options 物件。如果未指定 options 物件，則將使用上述預設值。

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
  • withFileTypes <boolean> 預設: false
  • recursive <boolean> 如果為 true，則遞迴地讀取目錄內容。在遞迴模式下，它將列出所有檔案、子檔案和目錄。預設值：false。
• callback <Function>
  • err <Error>
  • files <string[]> | <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 <string> | <Buffer> | <URL> | <integer> 檔名或檔案描述符
• options <Object> | <string>
  • encoding <string> | <null> 預設: null
  • flag <string> 參見檔案系統 flags 的支援。預設: 'r'。
  • signal <AbortSignal> 允許中止正在進行的 readFile 操作
• callback <Function>
  • err <Error> | <AggregateError>
  • data <string> | <Buffer>

非同步讀取檔案的全部內容。

import { readFile } from 'node:fs';

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

回撥函式接收兩個引數 (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 被呼叫。

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 執行的內部緩衝。

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• callback <Function>
  • err <Error>
  • linkString <string> | <Buffer>

讀取 path 所引用的符號連結的內容。回撥函式接收兩個引數 (err, linkString)。

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

可選的 options 引數可以是一個指定編碼的字串，或者是一個帶有 encoding 屬性的物件，用於指定傳遞給回撥函式的連結路徑所使用的字元編碼。如果 encoding 設定為 'buffer'，返回的連結路徑將作為 <Buffer> 物件傳遞。

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

• fd <integer>
• buffers <ArrayBufferView[]>
• position <integer> | <null> 預設: null
• callback <Function>
  • err <Error>
  • bytesRead <integer>
  • buffers <ArrayBufferView[]>

使用 readv() 從 fd 指定的檔案中讀取資料，並寫入一個 ArrayBufferView 陣列。

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

回撥函式將接收三個引數：err、bytesRead 和 buffers。bytesRead 是從檔案中讀取的位元組數。

如果此方法作為其 util.promisify() 版本被呼叫，它將返回一個 promise，該 promise 解析為一個帶有 bytesRead 和 buffers 屬性的 Object。

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

透過解析 .、.. 和符號連結來非同步計算規範路徑名。

規範路徑名不一定是唯一的。硬連結和繫結掛載可以透過許多路徑名暴露檔案系統實體。

此函式的行為類似於 realpath(3)，但有一些例外

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

2. 符號連結的最大數量是平臺無關的，通常比原生 realpath(3) 實現支援的數量要高（得多）。

回撥函式接收兩個引數 (err, resolvedPath)。可能會使用 process.cwd 來解析相對路徑。

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

可選的 options 引數可以是一個指定編碼的字串，或者是一個帶有 encoding 屬性的物件，用於指定傳遞給回撥函式的路徑所使用的字元編碼。如果 encoding 設定為 'buffer'，返回的路徑將作為 <Buffer> 物件傳遞。

如果 path 解析為一個套接字或管道，該函式將返回該物件的系統相關名稱。

不存在的路徑會導致 ENOENT 錯誤。error.path 是絕對檔案路徑。

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

• path <string> | <Buffer> | <URL>
• options <string> | <Object>
  • encoding <string> 預設值： 'utf8'
• callback <Function>
  • err <Error>
  • resolvedPath <string> | <Buffer>

非同步 realpath(3)。

回撥函式接收兩個引數 (err, resolvedPath)。

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

可選的 options 引數可以是一個指定編碼的字串，或者是一個帶有 encoding 屬性的物件，用於指定傳遞給回撥函式的路徑所使用的字元編碼。如果 encoding 設定為 'buffer'，返回的路徑將作為 <Buffer> 物件傳遞。

在 Linux 上，當 Node.js 連結到 musl libc 時，procfs 檔案系統必須掛載在 /proc 上才能使此函式正常工作。Glibc 沒有此限制。

fs.rename(oldPath, newPath, callback)#

• oldPath <string> | <Buffer> | <URL>
• newPath <string> | <Buffer> | <URL>
• callback <Function>
  • err <Error>

非同步地將 oldPath 處的檔案重新命名為 newPath 提供的路徑名。如果 newPath 已存在，它將被覆蓋。如果 newPath 處存在一個目錄，則會引發錯誤。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

另請參閱：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> 目前沒有公開的選項。以前曾有用於 recursive、maxBusyTries 和 emfileWait 的選項，但它們已被棄用和移除。為了向後相容，仍然接受 options 引數，但不會使用它。
• callback <Function>
  • err <Error>

非同步 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 <boolean> 當為 true 時，如果 path 不存在，異常將被忽略。預設值：false。
  • maxRetries <integer> 如果遇到 EBUSY、EMFILE、ENFILE、ENOTEMPTY 或 EPERM 錯誤，Node.js 將在每次嘗試時以 retryDelay 毫秒的線性退避等待時間重試操作。此選項表示重試次數。如果 recursive 選項不為 true，則此選項將被忽略。預設值：0。
  • recursive <boolean> 如果為 true，則執行遞迴刪除。在遞迴模式下，操作失敗時會重試。預設值：false。
  • retryDelay <integer> 兩次重試之間等待的時間（以毫秒為單位）。如果 recursive 選項不為 true，則此選項將被忽略。預設值：100。
• callback <Function>
  • err <Error>

非同步地移除檔案和目錄（模仿標準的 POSIX rm 實用程式）。除了一個可能的異常外，沒有其他引數會傳遞給完成回撥函式。

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

• path <string> | <Buffer> | <URL>
• options <Object>
  • bigint <boolean> 返回的 <fs.Stats> 物件中的數值是否應為 bigint。預設: false。
• callback <Function>
  • err <Error>
  • stats <fs.Stats>

非同步 stat(2)。回撥函式接收兩個引數 (err, stats)，其中 stats 是一個 <fs.Stats> 物件。

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

fs.stat() 會跟隨符號連結。要檢視連結本身，請使用 fs.lstat()。

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

要檢查檔案是否存在而不對其進行後續操作，建議使用 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 <Function>
  • err <Error>
  • stats <fs.StatFs>