Node.js / 系统课时

监听文件变化

监听文件变化

文件监听看起来只是“文件一改就回调”,但编辑器原子保存、不同操作系统事件语义和重复事件都会让简单写法失效。这里用 fs.watch() 监听父目录、做 120 ms 防抖,并通过 stat() 重新确认目标文件状态。

学习目标

  • 选择 fs.watch() 与 fs.watchFile() 的适用场景
  • 写出能处理重复事件、缺失 filename 和原子替换的监听程序
  • 识别 Linux、macOS、Windows 与网络文件系统上的常见差异

先选对监听方式

Node.js 常用的两种文件监听方式语义不同。fs.watch() 依赖操作系统提供的文件系统通知,通常更及时、资源开销也更低;fs.watchFile() 通过周期性 stat 轮询,更适合作为底层通知不可靠时的兜底。

API 工作方式 建议用法
fs.watch() 操作系统事件通知 本地文件、目录监听的默认选择
fs.watchFile() 定时比较文件状态 网络盘、虚拟化目录或必须轮询校验的场景
fs.unwatchFile() 停止 watchFile 轮询 结束任务时释放轮询

使用轮询时不要依赖默认间隔,直接给出业务能接受的值。例如配置热重载可从 interval: 1000 ms 开始;如果要求 100 ms 内响应,再评估更高轮询频率带来的系统调用开销。

用父目录监听目标文件

下面示例保存为 watch-file.mjs。它不是直接监听文件本身,而是监听父目录并筛选目标文件名;收到事件后等待 120 ms,再用 stat() 检查目标文件是否存在。这样更能适应很多编辑器“写临时文件再重命名覆盖”的保存方式。

js
import { watch } from 'node:fs';
import { stat } from 'node:fs/promises';
import { basename, dirname, resolve } from 'node:path';

const input = process.argv[2];

if (!input) {
  console.error('用法: node watch-file.mjs <file>');
  process.exit(1);
}

const target = resolve(input);
const directory = dirname(target);
const targetName = basename(target);
let timer;

// 监听父目录可以覆盖编辑器“临时文件 + rename 替换”的保存方式。
const watcher = watch(directory, (eventType, filename) => {
  // 某些平台可能不提供 filename;此时仍重新检查目标文件。
  if (filename && filename.toString() !== targetName) return;

  // 合并一次保存过程中连续出现的 rename/change 事件。
  clearTimeout(timer);
  timer = setTimeout(async () => {
    try {
      const info = await stat(target);
      console.log(
        `event=${eventType} file=${targetName} size=${info.size} mtimeMs=${Math.round(info.mtimeMs)}`
      );
    } catch (error) {
      if (error.code === 'ENOENT') {
        console.log(`event=${eventType} file=${targetName} status=missing`);
        return;
      }
      console.error(`stat failed: ${error.code ?? error.message}`);
    }
  }, 120);
});

watcher.on('error', (error) => {
  console.error(`watch failed: ${error.code ?? error.message}`);
  watcher.close();
  process.exitCode = 1;
});

process.on('SIGINT', () => {
  // 显式关闭 FSWatcher,避免开发工具退出时残留资源。
  clearTimeout(timer);
  watcher.close();
  console.log('watcher closed');
});

console.log(`watching: ${target}`);

运行监听器后,修改并保存目标文件。

bash
node watch-file.mjs "<PATH>/config.json"

预期输出

text
watching: <PATH>/config.json
event=<EVENT> file=config.json size=<BYTES> mtimeMs=<TIME>

<EVENT> 常见为 change 或 rename,但事件类型、次数和顺序可能因平台与编辑器保存方式不同;<BYTES> 与 <TIME> 也是动态值。这个示例把操作系统事件当成“需要重新检查”的信号,而不是把单次回调直接等同于一次业务修改。

为什么原子保存会让监听失效

不少编辑器保存文件时不会原地覆盖,而是先写 config.json.tmp,再删除或替换旧文件,最后把临时文件重命名为 config.json。在 Linux 和 macOS 上,直接监听单个文件时可能跟随的是原 inode;文件被替换后,新路径可能已经对应新的 inode。

编辑器原子保存与目录监听的关系

因此,开发服务器、配置热重载和代码生成器通常更适合监听目录,再按文件名过滤。若同一保存动作触发多次事件,用 80~200 ms 防抖是常见起点;本例取 120 ms,既能合并短时间重复事件,又不会让人工保存产生明显延迟。

处理平台差异与漏事件

fs.watch() 不保证“一次文件修改只对应一次事件”,也不保证回调一定带 filename。Linux、macOS 上文件替换涉及 inode 变化;Windows 删除或移动被监听目录时可能停止继续报告,某些情况下还会触发错误。NFS、SMB、Docker 挂载目录等环境也可能出现通知不完整或不可用。

可按下面顺序做容错:先监听父目录;把回调当作脏标记;防抖后重新读取或 stat();遇到 watcher error 时记录并重建监听;对必须保证最终一致的任务,再加一个较低频率的轮询校验,例如每 5~30 秒扫描一次关键文件状态。

如果业务要求审计“每一次”文件变更,不要把 fs.watch() 当作可靠事件日志。它适合触发刷新、重编译、热重载等“最终重新读取当前状态”的任务;真正需要无遗漏历史,应由写入方记录事务日志、消息队列或版本记录。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

监听文件变化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通