Node.js 文件系統：fs 模塊常用 API 速查手冊¶

在 Node.js 中，文件系統（File System）是處理文件讀取、寫入、目錄管理等操作的核心模塊。fs 模塊提供了豐富的 API，讓我們能在代碼中直接操控磁盤文件。本文將整理初學者最常用的 fs API，用簡單易懂的示例幫助你快速上手。

一、基礎概念：同步 vs 異步¶

fs 模塊的 API 分爲同步和異步兩種風格：
- 同步方法（如 readFileSync、writeFileSync）：代碼執行會阻塞等待操作完成，類似“一步一步執行”。適合簡單腳本或調試，但可能導致程序卡頓（尤其處理大文件時）。
- 異步方法（如 readFile、writeFile）：代碼非阻塞，操作完成後通過回調函數或 Promise 處理結果。適合高併發場景，需處理異步流程（如錯誤、結果）。

二、常用 API 速查¶

1. 讀取文件：fs.readFile（異步）¶

用途：異步讀取文件內容。
語法：fs.readFile(path[, options], callback)
- path：文件路徑（相對或絕對路徑）。
- options：可選，指定編碼（如 'utf8'），默認返回 Buffer（二進制數據）。
- callback：回調函數，參數爲 (err, data)，err 爲錯誤信息，data 爲文件內容（字符串或 Buffer）。

示例（讀取文本文件）：

const fs = require('fs');

fs.readFile('./example.txt', 'utf8', (err, data) => {
  if (err) { // 錯誤處理：文件不存在或權限不足時觸發
    console.error('讀取失敗：', err);
    return;
  }
  console.log('文件內容：', data); // 成功時輸出文件內容
});

同步版本：fs.readFileSync(path[, options])（直接返回內容，錯誤拋異常）

try {
  const data = fs.readFileSync('./example.txt', 'utf8');
  console.log('同步讀取：', data);
} catch (err) {
  console.error('同步讀取失敗：', err);
}

2. 寫入文件：fs.writeFile（異步）¶

用途：異步寫入內容到文件（文件不存在時會自動創建，存在時會覆蓋）。
語法：fs.writeFile(path, data[, options], callback)
- path：目標文件路徑。
- data：要寫入的內容（字符串或 Buffer）。
- options：編碼等配置。
- callback：回調函數，參數爲 (err)，無返回值時表示寫入成功。

示例（寫入文本內容）：

const fs = require('fs');
const content = 'Hello, Node.js!';

fs.writeFile('./output.txt', content, 'utf8', (err) => {
  if (err) {
    console.error('寫入失敗：', err);
    return;
  }
  console.log('文件寫入成功！');
});

同步版本：fs.writeFileSync(path, data[, options])（直接返回，錯誤拋異常）

try {
  fs.writeFileSync('./output.txt', '同步寫入的內容', 'utf8');
  console.log('同步寫入成功！');
} catch (err) {
  console.error('同步寫入失敗：', err);
}

3. 創建目錄：fs.mkdir（異步）¶

用途：創建目錄（文件夾）。
語法：fs.mkdir(path[, options], callback)
- path：目錄路徑。
- options：可選，recursive: true 表示遞歸創建多層目錄（如 mkdir('a/b/c') 需 recursive: true）。
- callback：回調函數，參數爲 (err)。

示例（創建單級目錄）：

const fs = require('fs');

// 創建單級目錄（不存在父目錄時會報錯，需加 recursive: true）
fs.mkdir('./new-dir', (err) => {
  if (err) {
    console.error('創建失敗：', err);
    return;
  }
  console.log('目錄創建成功！');
});

遞歸創建多級目錄：

// 創建嵌套目錄 'a/b/c'
fs.mkdir('./a/b/c', { recursive: true }, (err) => {
  if (err) console.error(err);
  else console.log('遞歸目錄創建成功！');
});

4. 刪除文件/目錄：fs.unlink（刪文件）/ fs.rmdir（刪目錄）¶

• 刪除文件：fs.unlink(path, callback)
  示例：

  fs.unlink('./output.txt', (err) => {
    if (err) console.error('刪除文件失敗：', err);
    else console.log('文件已刪除！');
  });

• 刪除空目錄：fs.rmdir(path, callback)
  示例：

  fs.rmdir('./new-dir', (err) => {
    if (err) console.error('刪除目錄失敗：', err);
    else console.log('空目錄已刪除！');
  });

注意：刪除非空目錄需用 fs.rm（Node.js 14+），並指定 recursive: true：

// 遞歸刪除目錄（包含內容）
fs.rm('./a', { recursive: true }, (err) => {
  if (err) console.error(err);
  else console.log('非空目錄已刪除！');
});

5. 讀取目錄：fs.readdir（異步）¶

用途：列出目錄下的所有文件和子目錄。
語法：fs.readdir(path, callback)
- path：目錄路徑。
- callback：回調函數，參數爲 (err, files)，files 是文件/目錄名稱數組。

示例：

fs.readdir('./', (err, files) => {
  if (err) {
    console.error('讀取目錄失敗：', err);
    return;
  }
  console.log('目錄內容：', files); // 輸出當前目錄下的文件列表
});

6. 獲取文件信息：fs.stat（異步）¶

用途：獲取文件/目錄的元數據（大小、修改時間等）。
語法：fs.stat(path, callback)
- path：文件/目錄路徑。
- callback：回調函數，參數爲 (err, stats)，stats 是包含文件信息的對象。

常用 stats 屬性：
- stats.isFile()：是否爲文件（true/false）
- stats.isDirectory()：是否爲目錄
- stats.size：文件大小（字節）
- stats.mtime：最後修改時間

示例：

fs.stat('./example.txt', (err, stats) => {
  if (err) {
    console.error('獲取信息失敗：', err);
    return;
  }
  console.log('是否爲目錄：', stats.isDirectory());
  console.log('文件大小：', stats.size, '字節');
  console.log('最後修改時間：', stats.mtime);
});

7. 檢查文件是否存在：fs.existsSync（同步）¶

用途：快速判斷文件/目錄是否存在（僅同步方法，異步用 fs.access 或 fs.stat）。
語法：fs.existsSync(path)
- path：路徑。
- 返回值：true（存在）或 false（不存在）。

示例：

const path = './example.txt';
if (fs.existsSync(path)) {
  console.log('文件存在！');
} else {
  console.log('文件不存在！');
}

三、進階技巧與注意事項¶

1. 路徑處理：避免直接拼接字符串，用 path 模塊更安全。

   const path = require('path');
   const fullPath = path.join(__dirname, 'data', 'file.txt'); // 拼接路徑（__dirname 是當前文件所在目錄）

2. 異步錯誤處理：必須在回調中檢查 err，否則程序可能因未處理的錯誤崩潰。

3. 性能優化：大文件讀寫建議用流（Stream） 而非一次性加載（如 fs.createReadStream），避免內存佔用過高。

4. 權限問題：文件操作需確保 Node.js 進程有對應權限（如讀取/寫入/執行權限）。

四、總結¶

fs 模塊是 Node.js 處理文件的核心工具，掌握上述 API 可滿足絕大多數基礎需求。從簡單的“讀寫文本文件”到“遞歸創建目錄”，靈活運用同步/異步方法，並注意錯誤處理和路徑安全，就能高效完成文件系統相關開發。

更多高級場景（如流處理、管道、文件鎖等）可後續深入學習，本文爲你提供快速入門的“速查手冊”。