[BUG]Windows 下 edit/write 覆盖已有文件:ReplaceFileW EIO (Win32 32)(ERROR_SHARING_VIOLATION)高频失败,无重试机制

[Acidmoon]

描述

在 Windows 上使用 edit 工具(或 writeText)覆盖一个已存在的文件时,经常直接失败,报错形如:

Error: ReplaceFileW EIO (Win32 32): E:\vibecoding\xxx.md

• 新建文件正常,只有覆盖已有文件时出现;
• 频率高,但并非 100%;对同一文件立即重试通常可成功——指向瞬时文件锁,而非确定性缺陷。

环境

• OS: Windows 11 25H2(build 26200.8875),64 位
• DSH: 0.1.0-rc.6(npm 全局安装)
• 安全软件:仅 Windows Defender 实时防护(RealTimeProtectionEnabled=True);无第三方杀软
• 磁盘:本地 NTFS 固定盘(非网络盘、非 OneDrive 目录)

根因分析

1. 错误串来源与含义

dsh-fs-local 的 win32Error()(src/fsio.ts,安装包中为 lib/index.js 34–51 行)只把 Win32 2/3 映射为 ENOENT、5 映射为 EACCES,其余所有错误码一律映射为 EIO。因此消息中的 "EIO" 只是兜底标签,真实错误码是 Win32 32 = ERROR_SHARING_VIOLATION("文件正被另一个进程使用,且未授予 FILE_SHARE_DELETE")。

2. 调用链

edit/write 覆盖已有文件时,writeFileAtomic(lib/index.js 461 行起)执行:

1. 在目标旁创建 .文件名.<pid>.<uuid>.tmpdir/ staging 目录;
2. open("wx", 0o600) 写入临时文件 → fsync → close(483–497 行);
3. 立即调用 ReplaceFileW(目标, 临时文件, NULL)(83–86 行,经 koffi 直调 kernel32)——为保留目标文件的 DACL(见设计笔记 2026-07-19-windows-atomic-write-dacl-preservation);
4. 失败处理:只有 ENOENT 才回退 rename(504–509 行),其余错误(包括 32)直接抛出,无任何重试。

3. 为什么失败

ReplaceFileW 要求目标文件与替换文件在调用瞬间不被任何进程以不带 FILE_SHARE_DELETE 的方式打开。Node/libuv 打开文件时带 FILE_SHARE_READ|WRITE|DELETE,DSH 自身句柄不会造成此问题。最可疑的占用者是 Windows Defender 实时防护对刚创建的 staging 临时文件的扫描句柄——DSH 在 close 后毫秒级调用 ReplaceFileW,扫描尚未结束 → ERROR_SHARING_VIOLATION。这解释了"频率高、非 100%、重试即过"的特征。

复现与实测

瞬时锁,无法稳定复现。实测记录(Windows 11 25H2 / build 26200.8875):

实验	结果
按 DSH 精确调用形态(node + koffi + toNamespacedPath + staging 子目录 + wx/fsync/close)连续压测 20 次	20/20 成功
DSH 服务进程内用 edit 工具真实编辑工作区文件	3/3 成功
MoveFileExW(MOVEFILE_REPLACE_EXISTING)(即 fs.rename)对照组	始终成功

失败概率与 Defender 扫描时长相关(签名刚更新、目录冷启动时窗口更宽)。

最小压测脚本(与 DSH 相同调用形态):

// 依赖 DSH 的 koffi;签名与 replaceFileWin32 一致
const koffi = require('koffi');
const kernel32 = koffi.load('kernel32.dll');
const replaceFileW = kernel32.func(
  'int __stdcall ReplaceFileW(const char16_t *replaced, const char16_t *replacement, ' +
  'const char16_t *backup, uint32_t flags, void *exclude, void *reserved)');

// 1. 在目标同卷目录创建 staging 临时文件(如 .name.tmpdir/name.tmp)
// 2. 写入内容、fsync、close
// 3. 立即调用:
const r = replaceFileW(toNamespacedPath(target), toNamespacedPath(temp), null, 0, null, null);
// r === 0 时 GetLastError() 通常为 32(ERROR_SHARING_VIOLATION)

预期行为

瞬时文件锁(杀软扫描、索引器等)不应导致编辑失败:

• 应先做短退避重试(几十毫秒级);
• 重试仍失败时,回退到 MoveFileExW(MOVEFILE_REPLACE_EXISTING)(即 fs.rename)——临时文件在写入前已拷贝目标 DACL(lib/index.js 485 行),rename 不会丢失 ACL,仅失去 ReplaceFileW 的元数据保留语义,作为兜底可接受。

建议修复

1. 对 ReplaceFileW 失败(至少 ERROR_SHARING_VIOLATION=32)增加短退避重试(如 5 次 × 20–50ms)后再报错;
2. 完善错误码映射:32 → EACCES/EBUSY,避免误导性的 EIO(2/3→ENOENT、5→EACCES 之外不应全部兜底为 EIO);
3. 重试仍失败时回退 fs.rename(temp, target) 作为兜底(本机实测 MoveFileExW 始终可用);
4. 在 dsh-fs-local README 的 Known Limitations 中补充 Windows 瞬时共享冲突的说明。

同类问题的既有修法(供参考)

• esengine/DeepSeek-Reasonix #4193: fix(desktop): retry atomic writes past transient Windows locks
• zed-industries/zed #30222: fs: Fall back from atomic write to regular fs write when file handle is in use on Windows
• LLVM: Improve reliability of file renaming in Windows

用户侧缓解(非本 issue 修复范围)

• 将工作区加入 Windows Defender 排除项(可根治本机问题);
• 失败时立即重试编辑;
• 若某个固定文件反复失败,用 Sysinternals handle.exe 排查占用进程。

[FirmaSpring]

master 47f9438 确认：packages/fs/fs-local/src/win32.ts:122-133 的 replaceFileWin32() 对 ReplaceFileW 失败没有任何重试，调用点 fsio.ts:552 也直接上抛——「无重试机制」属实，且帖主对 Win32 32 的映射分析（win32Error() 把错误码 32 展示成 EIO）与源码一致。

错误 32（ERROR_SHARING_VIOLATION）正是 Defender 实时扫描/索引器瞬时持有句柄的典型形态，「同一文件立即重试通常成功」完全符合这个特征——瞬时锁，等几十毫秒就释放。

建议

只对可重试错误做有界退避，其余照旧上抛：

// win32.ts replaceFileWin32 内
const SHARING = new Set([32 /*ERROR_SHARING_VIOLATION*/, 33 /*ERROR_LOCK_VIOLATION*/])
for (let attempt = 0; ; attempt++) {
  if (api.replaceFileW(...) !== 0) {
    const lastError = api.getLastError()
    if (SHARING.has(lastError) && attempt < 3) {
      await setTimeout(50 * (attempt + 1))  // 50/100/150ms
      continue
    }
    throw win32Error('ReplaceFileW', lastError, replaced)
  }
  break
}

不建议换成 MoveFileExW(MOVEFILE_REPLACE_EXISTING)：ReplaceFileW 保留被替换文件的 ACL 与替换元数据（这里正是和 copyFileDaclWin32 配套的语义），MoveFileExW 会丢掉这层。重试守住语义就够了。

[liuyib]

经常遇到这个问题

[Jstn-1g]

我按 #425 的复现范围做了一个可审阅的 fork reference implementation（尚未声称已被上游采用）：

• branch: https://github.com/Jstn-1g/deepseek-harness/tree/reference/discussion-425-windows-replace-retry
• exact commit: Jstn-1g@4b979f8
• base: b150a551b8d465e31e418e1b2eaf5e79bbb7d28e

实现边界：

• 只对 ERROR_SHARING_VIOLATION (32) 和 ERROR_LOCK_VIOLATION (33) 做 25/50/100 ms 三次有界退避；每次失败后立即捕获 GetLastError。
• 冲突耗尽映射为 EBUSY 并保留原 Win32 code；其他错误第一次即返回。测试还固定了部分状态结果 1176 只调用一次，避免不安全重试。
• 继续使用 ReplaceFileW，不回退到语义更弱的 rename；因此保留现有 DACL/替换元数据语义。
• 中止信号贯穿退避等待：等待期间取消不会再发起下一次原生替换；产品边界测试证明返回 FS_ABORTED、旧目标保留、暂存目录清理。

验证：Win32 binding 7/7 且 win32.ts 语句/分支/函数/行覆盖均为 100%；fs-local 聚焦套件 78 passed / 1 skipped；doc-sync 28/28；lint、build 和 pre-push typecheck 全部通过。EN/ZH README 与 Agent Note 已配对。

限制也明确记录了：本地没有伪造“真实 Defender 竞态已复现”；真实触发条件仍需要 Windows 原生运行结果和报告者确认。

感谢 @Acidmoon 的完整报告、@FirmaSpring 的边界分析，以及 @liuyib 的独立复现反馈。