一、这个函数到底做什么

fs.futimesSync()属于Node.js文件系统模块中针对文件描述符操作的时间戳修改方法。它同步地更改一个已打开文件描述符所指向文件的访问时间（atime）和修改时间（mtime），调用期间程序执行流会被阻塞，直到内核完成时间戳写入或抛出异常。

与fs.utimesSync()按路径操作不同，futimesSync接收的是一个整数文件描述符。文件描述符由fs.openSync()等方法获取，代表当前进程内一个已打开的文件句柄。这个区别在需要多次操作同一文件、或文件在操作期间可能被重命名/替换的场景中有实际意义：描述符绑定的是打开时的文件实体，路径则每次都需要重新解析。

官方文档对它的定义很精简：fs.futimes()的同步版本，返回undefined。但真正在项目中用好它，需要理解它和相邻函数之间的细微边界。

二、语法与参数规则

fs.futimesSync(fd, atime, mtime)

参数	类型	说明
fd	integer	由fs.openSync()或类似方法返回的文件描述符
atime	number|string|Date	新的访问时间
mtime	number|string|Date	新的修改时间

时间值的接受规则与fs.utimes()系列一致：可以是Unix纪元秒数（数字）、Date对象，或数字字符串（如'1717200000'）。如果值无法转换为数字，或者是NaN、Infinity、-Infinity，会抛出错误。

这里有一个容易被忽略的历史差异：在较老的Node.js版本中，utimes系列对NaN和Infinity的处理是静默转换为Date.now()，而较新版本的文档已明确改为抛出异常。如果你的项目跨越大版本升级，这部分行为需要纳入回归测试。

三、与相邻函数的职责对比

这是理解futimesSync定位的关键部分。

fs.utimesSync(path,atime,mtime)按路径修改时间戳。每次调用都会经过路径解析、权限检查和目录遍历。优点是使用直观，不需要管理文件描述符生命周期。缺点是如果文件在打开和修改之间被替换，你修改的可能是另一个文件。

fs.futimes(fd,atime,mtime,callback)是异步版本。它把时间戳修改操作交给事件循环处理，不阻塞主线程。适合在服务端请求处理中修改时间戳且不要求立即完成的场景。但异步版本存在一个实践中需要留意的问题：如果在回调执行前你关闭了描述符，操作可能失败。

fs.futimesSync()在以下情形中是不可替代的：你已经在代码路径中持有一个打开的描述符，并且后续逻辑严格依赖时间戳已经更新完毕。例如，在写入文件内容后立即修改其时间戳以匹配业务语义（如“归档时间”），然后关闭描述符并通知外部系统。此时异步版本会引入不必要的状态同步复杂度。

函数	操作对象	阻塞	典型使用场景
fs.utimesSync(path,...)	路径	是	简单脚本、一次性修改
fs.futimesSync(fd,...)	描述符	是	已打开文件、需确保修改完成
fs.futimes(fd,...)	描述符	否	高并发I/O、不要求立即生效
fs.utimes(path,...)	路径	否	常规异步文件操作

四、一个容易被忽视的安全背景

在Node.js的权限模型（PermissionModel，通过--allow-fs-read等标志启用）下，futimes()和futimesSync()的行为与utimes()存在一处差异：即使进程只拥有读取权限，通过文件描述符仍然可以修改时间戳。这意味着在只读目录中，持有可读描述符的代码可以更改文件元数据。该问题被记录为CVE-2025-55132，影响启用了权限模型的Node.jsv20、v22、v24、v25用户。

这不是说futimesSync本身有设计缺陷，而是提醒：文件描述符的获取权限与时间戳修改权限在部分版本中并未对齐。如果你的应用依赖权限模型做沙箱隔离，并且对文件元数据完整性有要求，需要对futimesSync的使用位置做审计。

五、时间戳精度的边界

有一个在项目中反复遇到但文档中不显眼的问题：在部分Node.js版本和平台上，utimes系列的时间戳精度可能只有秒级。GitHub上曾有issue记录fs.utimesSync和fs.futimesSync在写入包含毫秒的Date对象时，亚秒部分丢失，底层使用的是utime()而非utimes()系统调用。

这意味着如果你用futimesSync做需要毫秒级区分的时间戳标记（例如高频缓存失效判断），实际落盘的值可能不符合预期。规避方式是在写入后通过fs.fstatSync(fd)读回并比较mtimeMs，确认精度是否符合业务要求。对于精度敏感的场景，考虑将关键时间信息写入文件内容或伴随的元数据中，而不是依赖文件系统时间戳。

六、常见错误与处理

EBADF：传入的fd不是有效的打开文件描述符。常见原因是描述符已被关闭，或openSync返回前发生了异常。处理方式是确保futimesSync只在描述符有效的作用域内调用。

TypeError或时间转换错误：atime或mtime传入无法转换的值。现在Node.js版本会抛出明确的错误信息，提示时间戳无法转换为有效数字。建议在调用前对时间值做显式转换，避免依赖隐式类型coercion。

描述符泄漏：futimesSync本身不关闭描述符。如果调用链中发生异常而closeSync未被finally覆盖，描述符会持续占用，最终导致进程无法打开新文件。这是同步文件操作中最典型的生产事故来源之一。

七、可运行的示例：归档标记场景

以下示例模拟一个简化的工作流：打开日志文件，写入归档标记，将修改时间设置为业务时间，读回验证后关闭描述符。示例中的文件名为code_number_archive.log，时间使用2026年的日期但精确到日。

const fs = require('fs');

const filePath = 'code_number_archive.log';
const fd = fs.openSync(filePath, 'a+');

try {
  fs.writeSync(fd, `archived at ${new Date().toISOString()}\n`);

  const archiveDate = new Date('2026-03-15T00:00:00Z');
  fs.futimesSync(fd, archiveDate, archiveDate);

  const stats = fs.fstatSync(fd);
  console.log('修改时间读回:', stats.mtime);
  console.log('访问时间读回:', stats.atime);

  if (stats.mtime.getTime() !== archiveDate.getTime()) {
    console.warn('时间戳未匹配，检查当前平台的精度支持');
  }
} catch (err) {
  console.error('操作失败:', err.code, err.message);
} finally {
  fs.closeSync(fd);
}

这个示例的要点不在于展示API调用，而在于fstatSync读回验证和finally中的closeSync。前者暴露精度问题，后者杜绝描述符泄漏。

八、单元测试与边界验证思路

针对futimesSync的测试不需要复杂的框架，核心是覆盖三个维度：

正常路径：打开临时文件，传入两个不同的Date，用fstatSync读回，断言mtime和atime与预期一致（允许秒级精度容差）。

边界路径：传入NaN、Infinity、空字符串，断言抛出错误。传入数字字符串'1717200000'，断言正常接受。关闭描述符后再调用，断言EBADF。

描述符生命周期：在try块中故意抛出异常，确认finally中的closeSync仍然执行。可以用process.getActiveResourcesInfo()或简单的描述符计数来间接验证。

与fs.utimesSync的性能对比可以用简单的时间循环：对同一文件分别用路径方式和描述符方式各修改1000次时间戳，记录耗时差异。通常描述符方式略快，因为跳过了路径解析，但差异在多数业务场景中不构成决策依据。选择futimesSync的理由应当是“已经持有描述符”，而不是“为了微小的性能优势”。

九、练习与思考

1. 如果你在futimesSync之后、closeSync之前程序崩溃，文件时间戳是否已经持久化？这与fs.fsyncSync有什么关系？

2. 在一个文件监听（fs.watch）场景中，用futimesSync修改时间戳是否会触发监听回调？不同平台行为是否一致？

3. 为什么Node.js在权限模型下futimes的写入检查与utimes不同？这个差异对容器化部署的元数据完整性有何影响？

十、延伸阅读与参考文献

Node.js官方文档fs.futimesSync(fd,atime,mtime)，nodejs.cn中文镜像，提供该函数的基础定义与版本变更记录。https://url.nodejs.cn/api/v25/fs/fs_futimessync_fd_atime_mtime.html

Node.js官方文档fs.utimes(path,atime,mtime,callback)，nodejs.cn中文镜像，其中关于时间参数转换规则的说明同样适用于futimesSync的atime和mtime。https://url.nodejs.cn/api/v24/fs/fs_utimes_path_atime_mtime_callback.html

GitHubIssue#22070“utimesdoesn'tseemtosupportsubsecondstimes”，记录了utimes系列时间戳亚秒精度丢失的实际案例与底层原因分析，对理解futimesSync的精度边界有直接参考价值。https://github.com/nodejs/node/issues/22070

CVE-2025-55132漏洞记录（OSV条目），说明futimes()在Node.js权限模型下与utimes()的权限检查差异，影响版本与安全建议。http://test.osv.dev/vulnerability/CVE-2025-55132

CVE-2025-55132Launchpad追踪页，提供同一问题的多来源交叉参考。https://launchpad.net/bugs/cve/CVE-2025-55132