关于本文
本文是通过利用生成式 AI 的自动化生成流程创建的。在查阅 Microsoft Learn 的 FileSystemWatcher 官方资料的基础上，针对保存一次会发生多个事件的情况，将合并短时间内重复通知的防抖（debounce）思路整理成了可在 PowerShell 中尝试的形式。验证状态：📘 已确认官方规范・未在实机上验证
在实际业务中使用 FileSystemWatcher 时，有时会遇到“明明只保存了一次文件，却收到了两三次 Changed 事件”的情况。
这并不是异常，而是因为应用程序在保存时可能会执行多次 I/O 操作。
因此需要的是：将短时间内针对同一对象的事件合并为一次处理的防抖（debounce）机制。
首先观察重复事件
$dir = Join-Path $env:TEMP 'papanda-watch-debounce'
New-Item -ItemType Directory -Force $dir | Out-Null
$watcher = [System.IO.FileSystemWatcher]::new($dir)
$watcher.NotifyFilter = [IO.NotifyFilters]'FileName, LastWrite, Size'
$watcher.EnableRaisingEvents = $true
Register-ObjectEvent -InputObject $watcher -EventName Changed -SourceIdentifier 'PapandaChanged' | Out-Null
$file = Join-Path $dir 'demo.txt'
'first' | Set-Content $file
'second' | Add-Content $file
'third' | Add-Content $file
Start-Sleep -Seconds 1
Get-Event -SourceIdentifier 'PapandaChanged' |
Select-Object TimeGenerated,
@{n='Name';e={$_.SourceEventArgs.Name}}
事件的数量因环境而异。重要的是，写入次数和事件数量并不一定是一对一的。
什么是防抖（debounce）
例如，如果同一个 demo.txt 在 500ms 内收到多个事件，则只将最后 1 个事件视为“处理对象”的思路。
flowchart LR A[Changed #1] --> W[500ms待つ] B[Changed #2] --> W C[Changed #3] --> W W --> P[demo.txt を1回だけ処理]
重点不是删除事件本身，而是控制后续处理执行的次数。
首先通过批处理合并重复项
将事件缓存 1 秒钟，然后按文件名进行合并。
$events = Get-Event -SourceIdentifier 'PapandaChanged'
$events |
Group-Object { $_.SourceEventArgs.FullPath } |
ForEach-Object {
$latest = $_.Group |
Sort-Object TimeGenerated -Descending |
Select-Object -First 1
[pscustomobject]@{
Path = $_.Name
EventCount = $_.Count
UseEvent = $latest.TimeGenerated
}
}
例如，即使是 EventCount = 3，也可以将后续处理减少到只有 1 次。
这是实时防抖的最小概念版本。在生产环境中，可以使用定时器（Timer）或队列，将其演变为“自最后一个事件起保持一段时间静默后进行处理”的形式。
为什么不直接在 Changed 内部进行处理
例如，如果针对每个 Changed 事件将接收到的 CSV 注册到数据库中，则存在多次导入同一文件的风险。
此外，在事件发生时，对方应用程序可能仍在写入文件。
因此，在实际业务中，
接收事件
合并同一文件在短时间内的事件
确认文件大小或修改时间是否稳定
仅处理一次
记录已处理状态
分阶段处理会更加安全。
仅靠防抖是不够的
当大量更改发生时，FileSystemWatcher 的内部缓冲区可能会溢出，从而导致事件丢失。
也就是说，需要采取不同的对策：
重复事件 → 防抖（debounce）
事件丢失 → 定期重新扫描
重复处理 → 幂等化、已处理状态管理
如果在工作中用于
自动导入到达共享文件夹的 CSV
扫描仪 PDF 的后处理
来自外部系统的文件集成
日志文件更新监控
构建产物的自动处理
那么，更适合采用将 FileSystemWatcher 作为“通知装置”，并通过其他状态管理来保证处理正确性的设计。
收尾
Get-Event -SourceIdentifier 'PapandaChanged' |
Remove-Event -ErrorAction SilentlyContinue
Unregister-Event -SourceIdentifier 'PapandaChanged' -ErrorAction SilentlyContinue
$watcher.Dispose()
Remove-Item $dir -Recurse -Force
总结
FileSystemWatcher 可能会在一次操作中触发多个事件
防抖是将短时间内针对同一对象的事件合并为一次处理的思路
与其在事件 Action 内立即进行主处理，不如加入队列或状态管理
防范事件丢失与防范重复事件是两码事
在实际业务中，还需组合使用幂等化、重新扫描和已处理状态管理
