一、这个函数返回的到底是什么

fs.readdirSync(path,options)读取目录内容，返回一个数组。数组元素的类型取决于options.withFileTypes的取值：

• 默认（false）：返回string[]（或Buffer[]，当encoding设为'buffer'时）。每个元素是文件或子目录的名称，不含路径前缀，不含.与..。

• withFileTypes:true：返回fs.Dirent[]。每个Dirent对象携带name属性，以及isFile()、isDirectory()、isSymbolicLink()等方法。

返回值不保证顺序。Node.js官方文档没有承诺排序行为，实际顺序由底层文件系统决定。Linuxext4常呈现哈希序，macOSAPFS和WindowsNTFS通常更接近字母序，但这不是规范。任何依赖readdirSync输出顺序的代码，在跨平台部署时都可能暴只在特定CI上失败的问题。如果业务逻辑需要稳定顺序，必须在调用侧显式排序。

二、withFileTypes的实质收益：消除逐项stat

不使用withFileTypes时，区分文件与目录需要额外调用fs.statSync()或fs.lstatSync()。这意味着目录中有N个条目，就多出N次系统调用。withFileTypes:true让底层在读取目录时一并返回条目类型，Dirent的isFile()/isDirectory()直接从已有信息判断，不再触发独立的stat。

Node.js核心仓库中有一个与之相关的性能提交：为readdir系列增加recursive:true时，曾因对每个条目执行stat()导致同步版本比手写的readdirSync(dir,{withFileTypes:true})遍历慢约4.5倍；后续优化移除了不必要的stat调用。这个数据从侧面印证了withFileTypes在遍历场景中的价值：它不是语法糖，而是减少系统调用的实质性优化。

一个容易踩的TypeScript细节：fs.readdirSync(dir,{withFileTypes:false})的显式写法可能导致重载解析异常，返回类型被推断为string[]|Buffer[]，而省略该选项时重载能正确解析为string[]。默认值就是false，不需要画蛇添足地写出来。

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

readdirSync不是读取目录的唯一选择，选错函数会在并发模型或大目录场景中付出代价。

fs.readdirSync()
同步阻塞。适合启动脚本、CLI工具、构建流程中一次性读取目录，或测试代码。在HTTP请求处理路径中调用它，会阻塞事件循环，影响同一进程内其他请求的响应。

fs.readdir()（回调）与fs.promises.readdir()
异步版本，返回Promise或走回调。在服务端热路径中应优先使用异步版本。fs.promises.readdir同样支持withFileTypes，语义与同步版一致。

fs.opendirSync()/fs.opendir()
返回Dir对象，支持逐项迭代。Node.js核心团队在优化cp()实现时曾指出：readdir系列在大目录下伸缩性不理想，opendir的流式迭代更适合条目数量大或内存受限的场景。如果目录可能包含数万条目，opendir配合forawait...of比一次性拿到完整数组更可控。

fs.statSync()
不读目录。它获取单个路径的元数据。在readdirSync返回字符串数组后，statSync被用来补全类型信息——这正是withFileTypes:true要替代的模式。

四、错误码与异常处理

readdirSync同步抛出错误，不会返回rejectedPromise。不包裹try/catch的同步文件系统调用在遇到缺失路径或权限问题时会导致进程级异常，在GitHubActions等CI环境中表现为无诊断信息的崩溃。

常见错误码：

错误码	触发条件	处理方向
ENOENT	路径不存在	确认目录是否在运行前被删除，或路径拼接错误
ENOTDIR	路径存在但不是目录	上游逻辑误将文件路径传入
EACCES	权限不足	检查运行用户对目录的读权限
EPERM	操作被系统拒绝（Windows常见）	检查是否涉及受保护目录
ELOOP	符号链接循环	递归遍历中未跳过符号链接时的典型错误

一个建议：在递归遍历中，如果目标是“遍历目录树”，不要用statSync跟随符号链接来判断目录。Dirent.isDirectory()对符号链接返回false（符号链接本身不是目录），isSymbolicLink()返回true。显式跳过符号链接可以避免循环引用和越界读取。有项目在索引器中将readdirSync与withFileTypes配合，对每个条目先判断isSymbolicLink()并continue，再处理普通文件与目录。

五、：递归统计目录体积的健壮写法

下面这个示例统计目录树的总字节数，重点展示withFileTypes的用法与符号链接防御。不同于原文示例中对错误“静默忽略”的做法，这里区分了“可跳过”与“应上报”的异常。

const fs = require('node:fs');
const path = require('node:path');

function directorySize(dirPath, seen = new Set()) {
  let total = 0;

  let entries;
  try {
    entries = fs.readdirSync(dirPath, { withFileTypes: true });
  } catch (err) {
    if (err.code === 'EACCES') return 0; // 无权限目录跳过，不中断整体统计
    throw err;
  }

  for (const entry of entries) {
    if (entry.isSymbolicLink()) continue; // 不跟随链接，避免循环与越界

    const fullPath = path.join(dirPath, entry.name);

    if (entry.isDirectory()) {
      total += directorySize(fullPath, seen);
    } else if (entry.isFile()) {
      try {
        total += fs.statSync(fullPath).size;
      } catch (err) {
        if (err.code !== 'ENOENT') throw err; // 文件在 readdir 后被删除，静默跳过
      }
    }
  }

  return total;
}

这段代码中有两个值得留意的决策。第一，EACCES被局部吞掉并返回0，因为统计脚本通常不应因为一个无权限的子目录而整体失败；但其他错误码继续抛出，避免掩盖路径错误。第二，statSync在readdirSync之后执行，文件有可能在这两步之间被其他进程删除，ENOENT在此处是预期内的竞态，可以跳过；其他错误（如EIO）则不应被静默忽略。

六、跨平台排序：一个容易被低估的工程问题

如果业务逻辑需要“按名称排序的文件列表”，不要假设readdirSync返回的顺序在任何平台上是一致的。一个真实的案例：某测试代码用readdirSync(cacheDir)的原始输出与固定数组比对，在macOS和Windows上通过，在LinuxCI（ext4）上失败，因为AutoMobileOverlayAgent.json出现在AutoMobileOverlayAgent.dylib之前。

修复方式是在调用侧显式排序：

const names = fs.readdirSync(dirPath)
  .filter(name => name.endsWith('.json'))
  .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));

这里使用码元序（codeunitorder）而非localeCompare，原因是localeCompare的结果受运行环境的locale影响，在跨平台CI中可能产生不一致的排序。如果排序结果会进入缓存键、快照测试、用户可见列表或哈希计算，显式且确定性的排序是必要的工程约束，不是可选项。

七、TypeScript与类型安全

@types/node中readdirSync的重载对withFileTypes有区分。在TypeScript中，将选项对象提取为变量时，类型推断可能丢失字面量信息，导致返回值类型退化为联合类型。稳妥的写法是直接内联选项，或使用asconst：

import { readdirSync, type Dirent } from 'node:fs';

const entries: Dirent[] = readdirSync('./data', { withFileTypes: true });

如果封装工具函数，签名应明确区分两种返回形态：

function listNames(dir: string): string[];
function listEntries(dir: string): Dirent[];
function listNames(dir: string): string[] | Dirent[] {
  return readdirSync(dir);
}

但更推荐的做法是让调用方直接使用原生API，而不是在封装层做重载分发——readdirSync的选项语义足够简单，过度封装反而模糊了withFileTypes的存在感。

八、常见误区速查

“readdirSync返回完整路径”
不。返回的是条目名称。拼接路径需要path.join(dirPath,name)。

“Dirent.isDirectory()会跟随符号链接”
不会。符号链接的isDirectory()返回false，isSymbolicLink()返回true。如果要判断链接指向的目标类型，需要额外statSync（跟随）或lstatSync（不跟随）。

“withFileTypes在旧版本Node.js中不可用”
withFileTypes在Node.jsv10.10.0引入。如果项目仍需支持更早版本，只能用readdirSync返回字符串后逐个statSync。但在2026年的新项目中，这个兼容性考虑已无必要。

“同步版本在脚本里用没问题，在服务里用也没问题”
脚本是一次性执行，阻塞影响有限。服务进程在请求处理中调用readdirSync，阻塞的是整个事件循环，同一进程的所有并发请求都会被延迟。这是运行时模型决定的，不是代码风格偏好。

九、延伸阅读与参考文献

Node.js 官方文档：fs.readdirSync(path[,options])
https://nodejs.org/api/fs.html#fsreaddirsyncpath-options
最权威的语义与选项定义，明确返回值类型与withFileTypes的引入版本。

Node.js 官方Learn：Working with foldersin Node.js
https://nodejs.org/learn/manipulating-files/working-with-folders-in-nodejs
官方教程中关于读取目录内容的入门示例，展示了readdirSync配合path.join的基本用法。

Node.js 核心 PR #65487：fs:stopstat()ingeveryentryinrecursivereaddir
https://github.com/nodejs/node/pull/65487
包含readdirSync配合withFileTypes与逐项stat的性能对比数据，解释了为何Dirent路径在遍历中更高效。

Node.js核心提交d4a6f2c：fs:use async directory processing in cp()
https://github.com/nodejs/node/commit/d4a6f2caf1
核心团队在优化cp()时从readdir转向opendir的说明，涉及大目录伸缩性的权衡。

练习与思考：有一个目录，其中包含10万个文件，业务需要找出所有.log文件并统计总大小。方案A用readdirSync一次性获取全部名称，过滤后逐个statSync；方案B用opendirSync逐项迭代，对每个条目判断后缀后statSync。两者在内存占用和事件循环阻塞上的差异是什么？如果这个逻辑必须放在一个Express路由的处理函数中，你会选择同步方案还是异步方案，理由是什么？