chokidar

chokidar 是跨平台文件监听库，基于 node:fs 规范化各平台监听事件，提供递归监听、路径过滤、原子写入和分块写入处理。

它适合开发服务器、构建工具和同步程序。当前 v5 为 ESM-only，最低要求 Node.js 20；旧项目应根据其 Node.js 版本选择兼容的 chokidar 版本。

安装与监听

pnpm add chokidar

import chokidar from 'chokidar'

const watcher = chokidar.watch('src', {
  ignored: /(^|[/\\])\../,
  ignoreInitial: true,
})

watcher
  .on('add', (path) => console.log(`新增：${path}`))
  .on('change', (path) => console.log(`修改：${path}`))
  .on('unlink', (path) => console.log(`删除：${path}`))
  .on('error', (error) => console.error('监听失败：', error))

add、change、unlink 分别表示新增、修改和删除；目录事件使用 addDir 与 unlinkDir。

常用选项

const watcher = chokidar.watch('uploads', {
  ignoreInitial: true,
  ignored: ['**/node_modules/**', '**/.git/**'],
  awaitWriteFinish: {
    stabilityThreshold: 1_000,
    pollInterval: 100,
  },
  atomic: true,
})

• ignoreInitial：忽略首次扫描已有文件产生的事件。
• ignored：排除不需要监听的路径。
• awaitWriteFinish：等待文件尺寸稳定后再发出事件，适用于大文件或分块写入。
• atomic：将编辑器“临时文件替换”的删除与新增归并为一次修改。
• usePolling：使用轮询；网络文件系统或容器挂载目录监听不稳定时再开启，CPU 开销更高。

释放资源

监听器会保持进程存活，退出或重建监听器时必须关闭：

await watcher.close()

监听范围应尽量小，并排除依赖目录、构建产物和版本控制目录，避免大量递归监听消耗文件描述符与 CPU。