一、前置思考

1.1 大文件处理是"内存杀手"与"卡顿之源"

视频播放、大文件上传下载、数据库备份恢复、离线地图包……这些场景都要面对几十 MB 到几个 GB 的文件。直接 readAsArrayBuffer(整个文件) 会把应用内存峰值拉爆、触发 GC 卡顿甚至 OOM。

❌ 错误示范1: 读 500MB 文件到内存再解析
   → 内存峰值 +500MB, 进程可能被杀

❌ 错误示范2: 下载中断后从头再来
   → 弱网下永远下载不完

❌ 错误示范3: 上传时分片太小/太大
   → 太小: 请求数爆炸; 太大: 失败重传成本高

❌ 错误示范4: 全部文件一次性 fs.write
   → 写缓存堆积, IO 抖动

1.2 本文路线

深入分片读写、mmap 大文件映射、断点续传架构、内存峰值管控四个方向，给出企业级大文件处理方案。

二、核心原理

2.1 大文件读写的三条路径

路径A: 一次性读入 (小文件适用)
  readAsArrayBuffer → 内存峰值 = 文件大小

路径B: 分片流式读写 (大文件主力)
  open(file, READ) → 循环 seek + read(64KB)
  → 内存峰值 ≈ 分片大小, 恒定

路径C: mmap 内存映射 (随机访问场景)
  mmap(文件) → 按页访问文件内容
  → 按需缺页加载, 随机访问高效

路径	内存峰值	顺序读	随机访问	适用
一次性读入	=文件大小	快	快	< 5MB
分片流式	=分片大小	快	慢	任意大小
mmap	页缓存共享	快	快	大文件随机访问

2.2 分片读写机制

分片读:
  offset = 0
  while offset < fileSize:
    chunk = read(offset, 64KB)   // 一次最多读 64KB
    process(chunk)
    offset += 64KB

分片写:
  offset = 0
  while offset < total:
    write(offset, chunkData)
    offset += chunkData.length

分片大小选择：网络传输 1-4MB 片、本地读写 64KB-1MB 片。片太小 IO 调用次数多，片太大单次失败重传成本高。

2.3 断点续传原理

上传断点续传:
  ① 分片: 文件切成 N 片 (每片带 index + checksum)
  ② 服务端记录已收片 index
  ③ 断网/失败 → 查询已收片列表
  ④ 只重传缺失片 → 续传完成

下载断点续传:
  ① 记录已下载字节数 (metadata 文件 / KV Store)
  ② 断网 → 从 offset 继续 HTTP Range 请求
  ③ 校验续传后文件完整性 (整体 checksum)

2.4 mmap 大文件映射

mmap 将文件映射到进程地址空间，访问哪个页才加载哪个页（缺页中断）：

mmap 好处:
  - 随机访问快 (省去 seek + read 两次系统调用)
  - 多进程可共享同一映射 (共享读)
  - 内存按需加载, 峰值受控

mmap 注意:
  - 映射大文件占用地址空间 (64位下无碍)
  - 写映射需注意脏页回写时机
  - 文件被外部截断/修改 → SIGBUS 风险

三、源码/API 深度解析

3.1 分片读取（fs + fileio）

import { fileIo as fs } from '@kit.CoreFileKit';

const CHUNK_SIZE = 64 * 1024;  // 64KB

async function readLargeFile(path: string,
  onChunk: (data: ArrayBuffer, offset: number, isLast: boolean) => void): Promise<void> {
  const file = fs.openSync(path, fs.OpenMode.READ_ONLY);
  try {
    const stat = fs.statSync(path);
    let offset = 0;
    while (offset < stat.size) {
      const size = Math.min(CHUNK_SIZE, stat.size - offset);
      const buf = new ArrayBuffer(size);
      const readLen = fs.readSync(file.fd, buf, { offset: offset });
      onChunk(buf, offset, offset + readLen >= stat.size);
      offset += readLen;
    }
  } finally {
    fs.closeSync(file.fd);
  }
}

3.2 断点续传元数据

import { preferences } from '@kit.ArkData';

interface TransferMeta {
  fileId: string;
  totalBytes: number;
  doneBytes: number;
  chunkIndex: number;      // 下一个待传片 index
  chunkSize: number;
  checksum: string;        // 整体校验值
}

class TransferResume {
  private static KEY = 'transfer_meta';

  static async save(pref: preferences.Preferences, meta: TransferMeta): Promise<void> {
    await pref.put(TransferResume.KEY, JSON.stringify(meta));
    await pref.flush();
  }

  static async load(pref: preferences.Preferences): Promise<TransferMeta | null> {
    const raw = await pref.get(TransferResume.KEY, '');
    return raw === '' ? null : JSON.parse(raw) as TransferMeta;
  }
}

3.3 内存峰值管控：对象池 + 复用缓冲

class ChunkPool {
  private pool: ArrayBuffer[] = [];
  private readonly max = 4;   // 最多复用 4 个缓冲

  acquire(size: number): ArrayBuffer {
    for (let i = 0; i < this.pool.length; i++) {
      if (this.pool[i].byteLength >= size) {
        return this.pool.splice(i, 1)[0];
      }
    }
    return new ArrayBuffer(size);
  }

  release(buf: ArrayBuffer): void {
    if (this.pool.length < this.max) { this.pool.push(buf); }
  }
}

四、企业级实战落地

4.1 分片上传架构

┌─────────┐   分片(4MB)   ┌──────────┐   合并/校验   ┌────────┐
│  客户端   │ ───────────→ │  服务端    │ ───────────→ │ 对象存储 │
│ 断点记录   │ ←─────────── │ 已收片列表  │            └────────┘
└─────────┘  缺失片重传    └──────────┘

async function uploadByChunks(filePath: string, fileId: string,
  api: (chunk: ArrayBuffer, index: number) => Promise<boolean>): Promise<void> {
  const file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
  const stat = fs.statSync(filePath);
  const chunkSize = 4 * 1024 * 1024;   // 4MB 片
  const totalChunks = Math.ceil(stat.size / chunkSize);

  // 从服务端查询已上传片 (模拟)
  const uploaded: Set<number> = await queryUploaded(fileId);

  for (let i = 0; i < totalChunks; i++) {
    if (uploaded.has(i)) { continue; }   // 跳过已传片
    const size = Math.min(chunkSize, stat.size - i * chunkSize);
    const buf = new ArrayBuffer(size);
    fs.readSync(file.fd, buf, { offset: i * chunkSize });
    // 上传失败自动重试 (此处简化)
    await api(buf, i);
  }
  fs.closeSync(file.fd);
}

4.2 分片下载 + 合并

// 下载: 服务端返回文件总大小 → 分片 Range 拉取 → 逐片写入
async function downloadWithRange(url: string, filePath: string): Promise<void> {
  const total = await queryFileSize(url);
  const file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  let offset = 0;
  while (offset < total) {
    const end = Math.min(offset + 2 * 1024 * 1024 - 1, total - 1);
    const data = await httpRangeGet(url, offset, end);   // HTTP Range
    fs.writeSync(file.fd, data, { offset: offset });
    offset = end + 1;
  }
  fs.closeSync(file.fd);
}

4.3 mmap 大文件随机读取（日志/DB 分析）

// 场景: 分析 1GB 日志文件中指定偏移的内容
// 方案: mmap 映射后按需读取, 内存峰值与访问区域成正比
import { fileIo as fs } from '@kit.CoreFileKit';

async function mmapRead(path: string, offset: number, length: number): Promise<ArrayBuffer> {
  const file = fs.openSync(path, fs.OpenMode.READ_ONLY);
  const map = fs.mmapSync(file.fd, {
    offset: 0,
    length: fs.statSync(path).size,
    protection: 1  // PROT_READ
  });
  const out = new ArrayBuffer(length);
  new Uint8Array(out).set(new Uint8Array(map, offset, length));
  fs.munmapSync(map);
  fs.closeSync(file.fd);
  return out;
}

4.4 内存峰值对比（实测模拟）

方案	文件大小	内存峰值	耗时
一次性读入	500MB	500MB+	2.1s
分片读取	500MB	64KB	2.3s
mmap 随机读 10MB 区间	500MB	~10MB	0.3s

五、问题排查与性能优化

坑	现象	原因	解决
OOM	大文件读入内存	一次性 readAsArrayBuffer	分片流式
下载永远失败	弱网中断从头来	无断点续传	Range + 元数据记录
内存抖动	处理时 GC 频繁	每片新建缓冲	对象池复用
上传很慢	分片过小请求爆炸	片太小	4MB 分片
重传成本高	大失败整片重传	片太大	适中分片 + 重试
文件损坏	续传后打不开	无校验	checksum 校验
SIGBUS	mmap 访问异常	文件被截断	捕获信号/长度校验

5.1 分片大小调优

场景	推荐分片	原因
本地文件拷贝	1MB	平衡系统调用次数
弱网上传	512KB-1MB	失败重传成本低
高速上传	4MB-8MB	减少请求数
内存受限设备	64KB-256KB	峰值控制

5.2 传输调度优化

并发度控制: 同时 2-3 个分片并发 (太多拥塞, 太少吞吐低)
失败重试: 指数退避 (1s → 2s → 4s → 上限30s)
进度持久化: 每完成一片写元数据 (Preferences/KV)
续传校验: 完成后整体 checksum, 不一致回退重下

六、高阶总结与最佳实践

1. 永远不要整文件读入内存：分片流式是处理任意大小文件的唯一正确姿势。
2. 断点续传三件套：分片 index + 进度元数据 + checksum 校验。
3. mmap 是大文件随机访问的利器：按需加载，峰值受控。
4. 对象池复用缓冲：消除高频分片处理的 GC 抖动。
5. 分片大小看场景：网络 1-4MB，本地 64KB-1MB，内存受限设备更小。

一句话记住：大文件三原则——读分片、写流式、传断点；内存峰值永远等于分片大小而非文件大小。