fs.watch 在 vscode 插件中常静默失效，因底层 inotify 事件丢失且无兜底；应改用 chokidar，它自动 fallback 轮询、兼容跨平台，并需正确管理生命周期与内容比对。
为什么 fs.watch 在插件里经常失效
VSCode 插件运行在 Node.js 环境，但 fs.watch 在某些路径下会静默失败——尤其是 WSL2、NTFS 挂载点、iCloud 同步目录或远程文件系统（如 Remote-SSH 未启用轮询时）。它不报错，只是不再触发事件，导致监控逻辑“看起来正常却完全不工作”。
根本原因是底层 inotify 事件被丢弃，而 fs.watch 默认不兜底。实际开发中更可靠的是用 chokidar（VSCode 自身也用它），它自动 fallback 到 stat 轮询，并兼容跨平台路径处理。
- 必须显式安装依赖：
npm install chokidar，不能只靠 VSCode 内置的 Node API - 监听路径要用绝对路径：
vscode.workspace.rootPath已废弃，改用vscode.workspaceFolders?.[0]?.uri.fsPath - 忽略 node_modules 和 .git 是默认安全实践，否则大量事件会拖慢响应
- 监听器必须在
activate中注册，且需保存引用——插件停用时要调用unwatch()，否则内存泄漏
监听特定文件内容变更而非仅文件修改事件
只监听 change 事件不够：用户可能用外部编辑器改文件，或 Git checkout 切换分支，这些操作不会触发 VSCode 的 onDidChangeTextDocument，但 chokidar 能捕获。
真正要监控“内容变了”，得读取文件并比对哈希或文本快照。例如检测 .env 是否新增了 API_KEY=：
const watcher = chokidar.watch(envPath, { ignoreInitial: true });
watcher.on('change', async path => {
const content = await vscode.workspace.fs.readFile(vscode.Uri.file(path));
if (/API_KEY=/.test(new TextDecoder().decode(content))) {
vscode.window.showWarningMessage(`⚠️ .env contains API_KEY`);
}
});
-
ignoreInitial: true防止插件启动时误报——否则首次监听就会触发一次 change - 别用
fs.readFileSync：插件主线程阻塞会导致 UI 卡顿，必须用vscode.workspace.fs.readFile - 正则匹配前先 decode，避免二进制内容误判；大文件建议限制扫描行数
如何避免监听器重复注册和资源泄露
VSCode 插件可能被多次 activate（比如重装后、窗口重开），若每次都在 activate 里新建 chokidar.watch 而不清理旧实例，就会累积多个监听器，CPU 占用飙升，甚至触发系统 inotify 限额。
正确做法是把 watcher 实例存为模块级变量，并在 deactivate 钩子中销毁：
let watcher: chokidar.FSWatcher | null = null;
export function activate(context: vscode.ExtensionContext) {
if (watcher) watcher.close(); // 先关掉旧的
watcher = chokidar.watch(...);
context.subscriptions.push({ dispose() { watcher?.close(); } });
}
-
context.subscriptions是最稳妥的清理方式，VSCode 会在插件卸载时自动调用dispose - 不要依赖
process.on('exit')：插件进程可能被强制终止，钩子不保证执行 - 如果监听多个路径，用一个 watcher 实例统一管理，比开多个更轻量
实时监控与状态栏联动的常见陷阱
想在状态栏显示“当前文件已修改”？别直接在 chokidar 回调里写 statusBarItem.text = '✅'——这会绕过 VSCode 的渲染调度，导致闪烁或不同步。
状态栏项更新必须满足两个条件：一是确保 statusBarItem.show() 已调用过，二是所有赋值后需主动触发重绘（虽然通常隐式发生）。
- 监听器内更新前，先检查
vscode.window.activeTextEditor?.document.uri.fsPath === changedPath，避免全局变更影响当前视图 - 高频变更（如保存频繁的配置文件）要做防抖：
setTimeout延迟 300ms 更新，或用vscode.workspace.onDidSaveTextDocument替代底层监听 - 图标用
$(sync~spin)表示加载中态时，记得在完成后切回$(check)，否则旋转图标一直转
真正难的不是监听文件，而是判断“这次变更是否值得通知用户”——路径、内容、上下文、频率，四者缺一不可，漏掉任何一个都容易变成骚扰式提示。
