为何fs.readFileSync的encoding参数定义为null|undefined？及参数类型定义

一、为什么encoding被定义为encoding?: null | undefined; #

这个类型定义对应readFileSync返回Buffer的重载场景：

• 在Node.js的实际行为中，当你不指定encoding（省略options参数，或options里encoding为undefined），或者主动传null作为encoding时，readFileSync都会返回原始的Buffer数据，不会进行编码转换。
• TypeScript里，可选属性本身默认允许undefined，但加上null是为了兼容用户主动传入null的写法——Node.js原生支持这种传参方式，所以类型定义必须覆盖这个场景，确保类型检查和实际运行逻辑一致，避免出现“传null却触发类型报错”的问题。

二、如何给调用readFileSync的函数定义参数类型 #

可以根据你的函数需求，复用Node.js内置类型或自定义兼容类型：

场景1：函数仅需返回Buffer（和你给出的重载匹配） #

直接复用fs模块的内置类型，或自定义对应options类型：

import fs from 'fs';
import type { PathOrFileDescriptor } from 'fs';

// 自定义和目标重载匹配的options类型
type ReadFileBufferOptions = {
  encoding?: null | undefined;
  flag?: string | undefined;
} | null;

// 定义你的函数
function myReadFile(path: PathOrFileDescriptor, options?: ReadFileBufferOptions): Buffer {
  return fs.readFileSync(path, options);
}

场景2：函数需要支持返回Buffer或字符串（多重载场景） #

如果你的函数要兼容“传字符串编码返回对应字符串”的情况，可以定义多重载来匹配不同的参数和返回值：

import fs from 'fs';
import type { PathOrFileDescriptor } from 'fs';

// 定义函数重载，明确不同参数对应的返回类型
function myReadFile(path: PathOrFileDescriptor): Buffer;
function myReadFile(path: PathOrFileDescriptor, options: { encoding: string; flag?: string } | string): string;
function myReadFile(path: PathOrFileDescriptor, options?: { encoding?: null | string; flag?: string } | null | string): Buffer | string {
  return fs.readFileSync(path, options);
}

这样定义后，TypeScript会根据你传入的参数自动推断返回值类型，保证类型安全。

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