FileReader读取结果为null/ArrayBuffer时的Base64编码及TS报错问题

一、问题背景 #

使用FileReader.readAsDataURL()将文件编码为Base64时，根据TypeScript类型定义，ProgressEvent.target.result可能返回string、ArrayBuffer或null。需要明确这两种异常类型的含义、出现原因及规避方案，同时修复代码中的TypeScript类型错误。

二、针对null类型的疑问解答 #

• null代表什么？
  表示文件读取完全失败，未获取到任何有效数据。
• 为什么会出现null？
  常见原因包括：文件被删除或移动、读取权限不足、文件本身损坏、FileReader实例被提前销毁、浏览器内存不足无法加载文件等。
• 如何确保得到string类型结果？
  • 读取前校验文件有效性：检查targetFile是否为合法File对象、文件大小是否在合理范围。
  • 监听FileReader.onerror事件，捕获具体错误原因（而非仅通过result为null判断）。
  • 确保FileReader实例在读取周期内不被意外回收（比如避免在异步流程中提前销毁实例）。

三、针对ArrayBuffer类型的疑问解答 #

• ArrayBuffer代表什么？
  表示文件内容被读取为二进制缓冲区，但readAsDataURL()的设计目标是返回Base64格式的字符串，出现ArrayBuffer属于异常场景。
• 为什么会出现ArrayBuffer？
  通常是因为FileReader实例被重复调用了不同的读取方法（比如先调用readAsArrayBuffer()，后调用readAsDataURL()，导致结果被覆盖），或存在浏览器兼容性bug。
• 如何确保得到string类型结果？
  • 确保对同一个FileReader实例仅调用一次readAsDataURL()，避免混合调用其他读取方法。
  • 每次读取文件时创建新的FileReader实例（如你代码中已实现的逻辑），避免状态污染。
  • 对结果类型做严格校验，出现ArrayBuffer时直接抛出异常，排查根源问题而非强行转换。

四、修复TypeScript错误 #

错误信息翻译 #

S2345: 参数类型“Uint8Array”无法赋值给参数类型“number[]”
类型“Uint8Array”缺少类型“number[]”的以下属性：pop, push, concat, shift 及其他5个属性。

错误原因与修复 #

String.fromCharCode.apply()的第二个参数要求是标准数组，而Uint8Array是类数组对象，并非真正的数组。可以通过以下方式将其转换为数组：

• 使用Array.from()：Array.from(new Uint8Array(buffer))
• 使用扩展运算符：[...new Uint8Array(buffer)]

五、优化后的完整代码 #

// 辅助函数：判断值是否为undefined或null
function isEitherUndefinedOrNull(value: unknown): value is undefined | null {
  return value === undefined || value === null;
}

async function encodeFileToBase64(targetFile: File): Promise<string> {
  return new Promise<string>((resolve, reject) => {
    const fileReader = new FileReader();

    // 监听读取成功事件
    fileReader.onload = (event: ProgressEvent<FileReader>) => {
      const result = event.target?.result;

      if (isEitherUndefinedOrNull(result)) {
        reject(new Error("文件读取失败：未获取到任何数据，可能是文件损坏、权限不足或已被删除。"));
        return;
      }

      if (typeof result === 'string') {
        resolve(result);
      } else {
        reject(new Error(`文件读取异常：预期返回Base64字符串，实际返回ArrayBuffer。请检查是否重复调用了不同的FileReader读取方法。`));
        // 若需强行转换ArrayBuffer为Base64，可启用下面的代码：
        // const base64Str = btoa(String.fromCharCode(...new Uint8Array(result)));
        // resolve(`data:${targetFile.type};base64,${base64Str}`);
      }
    };

    // 监听读取错误事件，获取具体错误信息
    fileReader.onerror = (event) => {
      const error = event.target?.error;
      reject(new Error(`文件读取失败：${error?.message || '未知错误'}`));
    };

    fileReader.readAsDataURL(targetFile);
  });
}

补充说明 #

• 遇到ArrayBuffer时更推荐抛出错误，因为这属于readAsDataURL()的异常输出，优先排查代码逻辑或环境问题，而非强行转换。
• 新增onerror监听可获取更精准的错误原因，比仅判断result为null更实用。

内容的提问来源于stack exchange，提问作者Takeshi Tokugawa YD