FSEvents是macOS专有的内核级异步文件系统事件通知机制，基于fseventsd daemon，仅报告存在性变更（创建、删除、重命名），不保证顺序与内容修改；而inotify和ReadDirectoryChangesW分别是Linux和Windows的原生API，设计模型不同，无法跨平台通用。
什么是 FSEvents，为什么不能直接用 inotify 或 ReadDirectoryChangesW
FSEvents 是 macOS 专有的异步文件系统事件通知机制，运行在内核层（fseventsd daemon），不暴露文件句柄或路径实时状态。它和 Linux 的 inotify、Windows 的 ReadDirectoryChangesW 完全不同：没有“监听 fd”概念，不保证事件顺序绝对严格，也不提供“当前文件是否被删除/重命名”的上下文判断能力——只给一个事件流 + 树状路径的 cookie 值。
这意味着你不能像写跨平台轮询那样套用通用逻辑；必须用 Apple 提供的 FSEventStreamRef API，并接受它的设计约束：
-
FSEventStreamCreate需要传入绝对路径数组，相对路径会被静默忽略 - 事件回调中拿到的
paths是CFArrayRef，不是 C 字符串数组，需用CFStringGetCString转换 - 默认不报告“文件内容修改”，只报告“文件/目录存在性变更”（创建、删除、重命名）；想捕获写入需配合
kevent或FSEventStreamShow+ 文件 mtime 比对
如何正确初始化 FSEventStream 并避免崩溃
常见崩溃点是 FSEventStreamScheduleWithRunLoop 后没调用 FSEventStreamStart，或在非主线程 RunLoop 中调度却没提前 CFRunLoopAddSource。C++ 环境下还要注意 CFArrayRef 和 CFStringRef 的内存管理边界。
关键步骤如下：
立即学习“C++免费学习笔记（深入）”；
- 用
CFArrayCreate构造路径数组，每个元素必须是CFStringRef（可用CFSTR("/path/to/watch")或CFStringCreateWithCString） - 设置
kFSEventStreamCreateFlagFileEvents才能收到文件级事件（否则只有目录级） - 回调函数签名必须为
void (*)(ConstFSEventStreamRef, void *, size_t, CFArrayRef, const FSEventStreamEventFlags[], const FSEventStreamEventId[])，且不能是类成员函数（需用static+context传this指针） - 启动前确保当前线程有活跃的
CFRunLoopRef（主线程默认有；子线程需手动CFRunLoopGetCurrent+CFRunLoopRun）
示例片段（省略错误检查）：
FSEventStreamContext ctx = {0, this, nullptr, nullptr, nullptr};
CFArrayRef paths = CFArrayCreate(nullptr, (const void**)&pathStr, 1, &kCFTypeArrayCallBacks);
FSEventStreamRef stream = FSEventStreamCreate(nullptr, &callback, &ctx, paths,
kFSEventStreamEventIdSinceNow, 0.1,
kFSEventStreamCreateFlagFileEvents);
FSEventStreamScheduleWithRunLoop(stream, CFRunLoopGetCurrent(), kCFRunLoopDefaultMode);
FSEventStreamStart(stream);
FSEventStreamEventFlags 怎么解读，哪些标志位真正有用
回调中拿到的 flags 数组和事件一一对应，但很多标志位是冗余或仅用于调试的。实际业务中重点关注这几个：
-
kFSEventStreamEventFlagItemCreated：文件或目录被创建（含touch、mkdir、cp） -
kFSEventStreamEventFlagItemRemoved：文件或目录被删除（rm、mv出目录） -
kFSEventStreamEventFlagItemRenamed：文件或目录重命名或移动（mv同一卷内）；注意：这常和ItemCreated+ItemRemoved成对出现，需用cookie关联 -
kFSEventStreamEventFlagItemIsFile/kFSEventStreamEventFlagItemIsDir：区分类型，避免对目录做open()失败 -
kFSEventStreamEventFlagMustScanSubDirs：说明该目录下可能有大量变动，建议延迟处理或触发全量扫描
不要依赖 kFSEventStreamEventFlagItemModified —— 它极少触发，且文档明确说“不保证可靠”，macOS 通常只在 Finder 操作时发这个。
为什么事件会丢失？如何缓解漏报问题
FSEvents 本质是基于快照的差分机制，内核只保存最近若干次变更的 cookie 映射。当短时间内大量文件变动（如 git checkout、rsync），旧事件会被覆盖，导致 FSEventStreamEventId 跳变，回调中看到的 eventId 不连续，甚至整个批次消失。
缓解方式有限但实用：
- 降低
latency参数（如设为0.01），但会增加 CPU 和电源消耗 - 监听父目录而非具体文件（例如监听
/Users/me/project而非/Users/me/project/src/main.cpp），减少路径过滤丢弃 - 定期用
stat()对比关键文件的st_mtime和上次记录值，作为事件缺失的兜底检测 - 遇到
kFSEventStreamEventFlagRootChanged或eventId突增 > 1000，立即触发一次全量目录树遍历并更新本地快照
没有银弹。FSEvents 的设计目标是“高效通知大致变更”，不是“精确捕获每一字节改动”。如果业务强依赖内容变更（比如 IDE 实时 lint），必须叠加 kevent 监听 NOTE_WRITE 或用 dispatch_source_create(DISPATCH_SOURCE_TYPE_VNODE) 补充。
