Windows环境Node.js fs读取已存在文件报ENOENT的问题排查

Windows平台Node文件系统缓存兼容缺陷 #

• Windows 8.1环境下的Node v14.8.0存在已知Win32文件API兼容问题：Node 14早期版本会在进程初始化阶段缓存系统的目录枚举结果，若目标文件在Node进程启动完成后才完成落盘写入，Node内部的文件查询逻辑不会主动触发系统级目录刷新，会出现命令行dir可正常识别文件、但fs.existsSync、fs.readFileSync统一判定文件不存在的表现。
• 对应场景的恢复逻辑验证：调用fs.access、新建Node REPL会话后程序恢复正常，本质是这两个操作会主动向系统发起实时文件查询请求，强制刷新Node内部缓存的路径枚举结果，无需重启项目即可恢复文件读取能力。

路径字符串的隐性匹配偏差 #

• 看似和控制台输出完全一致的“绝对路径”，可能存在肉眼难以识别的字符异常：比如复制路径时带入零宽空格、全角格式反斜杠，这类问题会导致传入的字符串和真实文件路径不匹配，所有文件API都会判定文件不存在，而报错信息中打印的路径因为自动转义，视觉上和正确路径没有差异。
• 老版本Windows默认开启8.3短文件名兼容机制，Node v14.8.0在解析长路径时存在API参数传递错误的已知bug，可能把长路径错误解析为不存在的短文件节点，直接导致路径匹配失败。

系统资源占用的错误码混淆 #

• 若目标文件被杀毒软件实时扫描、Windows搜索索引服务临时占用，处于短暂不可访问状态时，Node v14.8.0的Win32文件模块不会区分“文件真的不存在”和“文件被占用无读取权限”，会统一抛出ENOENT、errno: -4058的错误，和文件不存在的报错表现完全一致。

• 路径标准化前置：调用文件读取逻辑前，先用path.normalize()对传入的绝对路径做字符清洗，自动剔除不可见字符、统一反斜杠格式，再通过fs.realpathSync()解析出文件的真实物理路径，规避软链接、短文件名带来的解析偏差。
• 预加载刷新缓存：在项目启动初始化阶段，对所有需要读取的静态资源路径，提前调用一次fs.accessSync(path, fs.constants.R_OK)做权限预校验，主动触发Node的系统文件缓存刷新，不要等到业务逻辑首次读取文件时才发起IO请求。
• 版本适配修正：针对Windows 8.1下的Node v14.8.0场景，将Node升级到v14线的最终稳定版v14.21.3，该版本已修复Win32平台的文件枚举缓存同步bug，从根源解决偶发的路径找不到问题。
• 错误重试兜底：捕获文件读取的ENOENT错误后，增加100ms短延时的单次重试逻辑，覆盖系统临时文件锁、缓存未刷新的偶发场景，避免偶发异常直接导致程序崩溃。

内容的提问来源于stack exchange，提问作者Werlious