Node.js异步文件读取JSDoc标注TS类型不匹配报错解决

问题出在TypeScript无法自动根据你传入的encoding参数推断函数返回类型，即便传了utf8，它仍会保留string | Buffer的联合类型。可以通过以下方式修复：

方法一：用JSDoc重载定义函数类型 #

给read函数添加多组JSDoc注释，分别定义「带编码参数」和「不带编码参数」的返回类型，让TypeScript能根据调用时的参数匹配对应返回类型：

/**
 * 异步读取文件内容
 * @param {string} filePath 文件路径
 * @returns {Promise<Buffer>} 文件内容Buffer
 */
/**
 * 异步读取文件内容（指定编码）
 * @param {string} filePath 文件路径
 * @param {string} encoding 编码格式
 * @returns {Promise<string>} 文件内容字符串
 */
async function read(filePath, encoding) {
  const fs = await import('fs/promises');
  return fs.readFile(filePath, encoding);
}

// 调用示例
async function main() {
  // 此时TypeScript会自动识别content为string类型
  const content = await read('./test.txt', 'utf8');
  console.log(content.trim()); // 无类型报错
}

方法二：用JSDoc泛型+条件类型推断 #

通过泛型和条件类型，让TypeScript根据传入的encoding参数动态推断返回类型：

/**
 * 异步读取文件内容
 * @template TEncoding
 * @param {string} filePath 文件路径
 * @param {TEncoding} [encoding] 编码格式
 * @returns {Promise<TEncoding extends string ? string : Buffer>} 根据编码返回对应类型的内容
 */
async function read(filePath, encoding) {
  const fs = await import('fs/promises');
  return fs.readFile(filePath, encoding);
}

// 调用示例
async function main() {
  const content = await read('./test.txt', 'utf8');
  // TypeScript会推断content为string
  processContent(content);
}

function processContent(str) {
  /** @param {string} str */
  console.log(str.toUpperCase());
}

临时快速修复（直接调用fs.readFile时） #

如果不是自己封装的read函数，而是直接调用fs.readFile，可以给变量添加类型断言：

async function main() {
  // 方式1：提前标注变量类型
  /** @type {string} */
  const content = await fs.readFile('./test.txt', 'utf8');
  
  // 方式2：用类型断言强制指定
  const content = /** @type {string} */ (await fs.readFile('./test.txt', 'utf8'));
}

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