萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

Node.js 跨平台複製目錄:`fs.cpSync`、遞迴複製與 `child_process` 方案比較

現代標準:`fs.cpSync` / `fs.cp` (Node.js 16.7.0+)

const fs = require('fs');

// 同步阻塞(腳本、CLI 工具適用)
fs.cpSync('./src', './dist', { recursive: true, force: true });

// 非同步(伺服器、建構工具適用)
await fs.promises.cp('./src', './dist', { recursive: true, force: true });
  • `recursive: true`:遞迴複製子目錄。
  • `force: true`:目標存在時覆蓋。
  • `preserveTimestamps: true`:保留修改時間(預設 false)。
  • `filter`:`(src, dest) => boolean` 過濾檔案(如排除 `node_modules`)。
  • **跨平台、無依賴、效能最佳**(內部使用 `copy_file_range` / `CopyFileEx` 系統呼叫)。

舊版 Node (≤16) 手寫遞迴複製(含檔案過濾、進度回調)

const fs = require('fs');
const path = require('path');

async function copyDir(src, dest, options = {}) {
  const { filter, onFile, concurrency = 8 } = options;
  await fs.promises.mkdir(dest, { recursive: true });

  const entries = await fs.promises.readdir(src, { withFileTypes: true });
  const limit = pLimit(concurrency); // 需安裝 p-limit 或自寫簡易佇列

  await Promise.all(entries.map(entry => limit(async () => {
    const srcPath = path.join(src, entry.name);
    const destPath = path.join(dest, entry.name);
    if (filter && !filter(srcPath, destPath)) return;

    if (entry.isDirectory()) {
      await copyDir(srcPath, destPath, options);
    } else {
      await fs.promises.copyFile(srcPath, destPath);
      onFile?.(srcPath, destPath);
    }
  })));
}

// 使用
await copyDir('./src', './dist', {
  filter: (src) => !src.includes('node_modules') && !src.endsWith('.map'),
  onFile: (s, d) => console.log(`Copied: ${path.relative(process.cwd(), s)}`)
});

`child_process` 方案:呼叫系統指令(`cp` / `xcopy` / `robocopy`)

const { spawn } = require('child_process');
const path = require('path');

function copyWithSystemCmd(src, dest) {
  return new Promise((resolve, reject) => {
    const isWin = process.platform === 'win32';
    const cmd = isWin ? 'robocopy' : 'cp';
    const args = isWin
      ? [src, dest, '/E', '/COPY:DAT', '/R:1', '/W:1', '/NFL', '/NDL', '/NJH', '/NJS']
      : ['-R', '--preserve=timestamps', src, dest];

    const proc = spawn(cmd, args, { windowsVerbatimArguments: true });
    let stderr = '';
    proc.stderr.on('data', d => stderr += d);
    proc.on('close', code => {
      // robocopy: 0~7 正常,≥8 錯誤
      if (isWin ? code >= 8 : code !== 0) reject(new Error(stderr));
      else resolve();
    });
  });
}

方案比較表

方案Node 版本跨平台效能功能豐富度適用場景
`fs.cpSync/cp`≥16.7✅ 完美⭐⭐⭐⭐⭐ (系統級)過濾、保留時間、符號連結**首選**,所有新專案
手寫遞迴≥10✅ 完美⭐⭐⭐ (JS 層面)可自訂邏輯、進度、並發控制舊版 Node、需精細控制
`spawn cp/xcopy/robocopy`所有❌ 需分平台⭐⭐⭐⭐ (系統級)robocopy 功能最強(鏡像、重試、日誌)Windows 大量檔案、需 robocopy 進階參數
第三方庫 (fs-extra, ncp)所有✅⭐⭐⭐API 豐富舊專案維護、不想升級 Node

常見坑點與解法

  • 符號連結:`fs.cp` 預設複製連結檔案本身(非目標),加 `dereference: true` 複製目標內容。
  • 權限錯誤:Windows 需管理員權限複製系統資料夾;Linux 注意 `uid/gid`。
  • 超長路徑 (Windows 260 字元):啟用 `\\?\` 前綴或系統設定 `LongPathsEnabled`。
  • 空目錄保留:`fs.cp` 預設保留;手寫遞迴需確保 `mkdir` 後即使無檔案也保留目錄。
  • 並發過高:`EMFILE: too many open files`,使用 `p-limit` 限制並發數(建議 8~16)。

結語

Node.js 16.7+ 專案**直接用 `fs.cpSync` / `fs.cp`**,一行代碼解決跨平台遞迴複製,效能最強、API 最乾淨。舊版環境手寫遞迴或用 `fs-extra`。只有 Windows 大檔案鏡像、需 `robocopy` 斷點續傳/日誌/多執行緒時,才考慮 `child_process` 呼叫系統指令。

copyright © 萬盛學電腦網 all rights reserved