文件下载到沙箱后为什么大小与源文件不一致

文件下载成功但写入沙箱后损坏、体积异常，通常是写入环节的数据处理不当导致的，而非下载本身的问题。下载过程不报错是因为网络请求和响应流读取都正常完成了，但在将接收到的数据写入本地文件时出现了偏差。

原因一：未循环读取写入（最常见，导致体积偏小）

下载大文件时通常分块接收数据，每次收到一个 ArrayBuffer。如果只写入了一次就认为完成了，或者 buffer 被写成了一个固定值而没有循环读取，就只有开头部分内容被存入沙箱，文件体积明显偏小1。

原因二：文件已存在且未清空（导致体积偏大）

如果目标文件已存在，打开时未使用 TRUNC 模式（截断为零），新数据会从文件头部开始覆盖写入，但如果新数据比旧数据短，文件尾部会残留旧数据，导致体积偏大且内容混乱。若使用了 APPEND 模式，则新数据会追加在旧数据之后，同样导致体积异常。

原因三：写入后未关闭文件（导致体积偏小或内容缺失）

文件写入后数据可能还在系统缓存中，如果没有调用 closeSync 或 fsyncSync 将缓存刷入磁盘，文件实际写入的数据量可能小于预期。

原因四：二进制数据被当作字符串处理（导致体积偏大或内容错误）

将二进制文件数据通过字符串编码方式（如 Base64 或 UTF-8）处理后再写入，编码转换会改变数据体积和内容，导致文件损坏。

正确的写入方式

以下示例展示了通过 HTTP 请求下载文件并正确写入沙箱目录的完整流程，使用分块接收、循环写入的方式确保数据完整性：

import { http } from '@kit.NetworkKit';
import { fileIo } from '@kit.CoreFileKit';
import { buffer } from '@kit.ArkTS';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct DownloadFilePage {
  @State downloadProgress: number = 0;
  @State isDownloading: boolean = false;

  async downloadFile(context: common.UIAbilityContext): Promise<void> {
    const url: string = 'https://example.com/test.pdf';
    const filePath: string = `${context.filesDir}/test.pdf`;

    // 创建 HTTP 请求
    const httpRequest: http.HttpRequest = http.createHttp();

    try {
      // 发起请求，启用流式接收
      const promise: http.HttpResponse = await httpRequest.request(url, {
        method: http.RequestMethod.GET,
        expectDataType: http.HttpDataType.ARRAY_BUFFER,
        connectTimeout: 60000,
        readTimeout: 60000,
      });

      // 获取响应数据
      const responseData: ArrayBuffer = promise.result as ArrayBuffer;

      // 打开文件并写入，使用 CREATE | WRITE_ONLY | TRUNC 确保文件清空后写入
      const file: fileIo.File = fileIo.openSync(
        filePath,
        fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.TRUNC
      );

      // 将完整数据写入文件
      fileIo.writeSync(file.fd, responseData);

      // 关闭文件，确保数据刷入磁盘
      fileIo.closeSync(file);

      console.info('文件下载并写入成功');
    } catch (error) {
      console.error(`下载失败: ${(error as BusinessError).message}`);
    } finally {
      httpRequest.destroy();
    }
  }

  build() {
    Column() {
      Button('下载文件')
        .onClick(() => {
          this.downloadFile(this.getUIContext().getHostContext() as common.UIAbilityContext);
        })
    }
  }
}

如果使用 request.downloadFile（系统下载服务），它内部会自动处理文件写入，只需在 DownloadConfig中指定 filePath 即可，无需手动写入：

import { request } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function downloadWithSystemAPI(context: common.UIAbilityContext): Promise<void> {
  const filePath: string = `${context.filesDir}/test.pdf`;

  try {
    const downloadTask: request.DownloadTask = await request.downloadFile(context, {
      url: 'https://example.com/test.pdf',
      filePath: filePath,
    });

    // 监听下载进度
    downloadTask.on('progressReceive', (receivedSize: number, totalSize: number) => {
      console.info(`下载进度: ${receivedSize}/${totalSize}`);
    });

    // 监听下载完成
    downloadTask.on('complete', () => {
      console.info('下载完成，文件已保存至: ' + filePath);
    });
  } catch (error) {
    console.error(`下载失败: ${(error as BusinessError).message}`);
  }
}

六大根因深度剖析

⚠️ 关键认知：HarmonyOS 的 @ohos.request 下载任务和 @ohos.fs 文件系统是两套独立 API。下载成功 ≠ 落盘成功。request.DownloadTask.on('complete') 只表示网络传输结束，不代表数据已安全刷入磁盘。

 标准修复方案：原子化写入 + 校验闭环

方案一：使用 request.download 的正确姿势（推荐）

import { request } from '@kit.BasicServicesKit';
import { fileIo as fs } from '@kit.CoreFileKit';
import { cryptoFramework } from '@kit.CryptoArchitectureKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

class SafeDownloader {
  private context: Context;
  
  constructor(context: Context) {
    this.context = context;
  }

  async downloadWithVerification(
    url: string, 
    expectedSize?: number,
    expectedMd5?: string
  ): Promise<string> {
    const fileName = url.split('/').pop() ?? `download_${Date.now()}`;
    // 先写入临时文件，验证通过后再 rename（原子操作）
    const tempPath = `${this.context.cacheDir}/${fileName}.tmp`;
    const finalPath = `${this.context.filesDir}/${fileName}`;

    return new Promise((resolve, reject) => {
      const config: request.DownloadConfig = {
        url: url,
        filePath: tempPath, // 直接指定落盘路径，避免手动拼接流
        enableMetered: true,
        enableRoaming: true
      };

      let downloadTask: request.DownloadTask | undefined;

      try {
        downloadTask = request.createDownloadTask(this.context, config);
      } catch (err) {
        reject(new Error(`Create task failed: ${JSON.stringify(err)}`));
        return;
      }

      let receivedBytes = 0;

      downloadTask.on('progress', (received: number, total: number) => {
        receivedBytes = received;
        if (expectedSize && total > 0 && total !== expectedSize) {
          hilog.warn(0x0000, 'Download', 
            `Size mismatch header: expected=${expectedSize}, actual=${total}`);
        }
      });

      downloadTask.on('complete', async () => {
        try {
          // 1. 强制同步文件系统（确保内核缓冲区刷盘）
          await this.syncFile(tempPath);
          
          // 2. 校验文件大小
          const stat = await fs.stat(tempPath);
          if (expectedSize && stat.size !== expectedSize) {
            throw new Error(`Size mismatch: expected=${expectedSize}, got=${stat.size}`);
          }
          if (stat.size === 0) {
            throw new Error('Downloaded file is empty');
          }

          // 3. 校验 MD5（如有提供）
          if (expectedMd5) {
            const actualMd5 = await this.calculateMd5(tempPath);
            if (actualMd5.toLowerCase() !== expectedMd5.toLowerCase()) {
              throw new Error(`MD5 mismatch: expected=${expectedMd5}, got=${actualMd5}`);
            }
          }

          // 4. 原子性移动到目标位置（rename 在同一文件系统下是原子操作）
          await fs.rename(tempPath, finalPath);
          
          hilog.info(0x0000, 'Download', 
            `✅ Verified & saved: ${finalPath} (${stat.size} bytes)`);
          resolve(finalPath);

        } catch (verifyErr) {
          // 校验失败，删除临时文件，防止残留
          await fs.unlink(tempPath).catch(() => {});
          reject(verifyErr);
        } finally {
          downloadTask?.off('progress');
          downloadTask?.off('complete');
          downloadTask?.off('fail');
        }
      });

      downloadTask.on('fail', (err: number) => {
        fs.unlink(tempPath).catch(() => {});
        reject(new Error(`Download failed with code: ${err}`));
      });

      downloadTask.start((err) => {
        if (err) {
          reject(new Error(`Start failed: ${JSON.stringify(err)}`));
        }
      });
    });
  }

  /**
   * 强制刷盘：打开 → fsync → close
   */
  private async syncFile(path: string): Promise<void> {
    const fd = await fs.open(path, fs.OpenMode.READ_ONLY);
    try {
      await fs.fsync(fd.fd); // 关键：将内核缓冲区数据刷入物理存储
    } finally {
      await fs.close(fd);
    }
  }

  /**
   * 计算文件 MD5
   */
  private async calculateMd5(filePath: string): Promise<string> {
    const md = cryptoFramework.createMd('MD5');
    const file = await fs.open(filePath, fs.OpenMode.READ_ONLY);
    const stat = await fs.stat(filePath);
    const buf = new ArrayBuffer(stat.size);
    await fs.read(file.fd, buf);
    await fs.close(file);
    
    const dataBlob: cryptoFramework.DataBlob = { data: new Uint8Array(buf) };
    await md.update(dataBlob);
    const digest = await md.digest();
    
    return Array.from(digest.data)
      .map(b => b.toString(16).padStart(2, '0'))
      .join('');
  }
}

方案二：手动流式下载（适用于需要自定义进度/UI 的场景）

如果你不用 request.download 而是用 http.HttpResponse 手动接收流，必须严格管理写入生命周期：

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

async function manualStreamDownload(url: string, savePath: string): Promise<void> {
  const httpRequest = http.createHttp();
  let fileFd: fs.File | null = null;
  let totalWritten = 0;

  try {
    // 1. 预先创建文件并获取 fd
    fileFd = await fs.open(savePath, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY);
    
    const response = await httpRequest.request(url, {
      method: http.RequestMethod.GET,
      expectDataType: http.HttpDataType.ARRAY_BUFFER // ⭐ 必须用 ARRAY_BUFFER，绝不能用 STRING
    });

    if (response.responseCode !== http.ResponseCode.OK) {
      throw new Error(`HTTP ${response.responseCode}`);
    }

    const arrayBuffer = response.result as ArrayBuffer;
    const uint8Array = new Uint8Array(arrayBuffer);
    
    // 2. 一次性写入（小文件）或分块写入（大文件）
    const writeLen = await fs.write(fileFd.fd, uint8Array.buffer);
    totalWritten = writeLen;
    
    if (writeLen !== uint8Array.length) {
      throw new Error(`Partial write: expected=${uint8Array.length}, written=${writeLen}`);
    }

    // 3. 【最关键】显式 fsync + close
    await fs.fsync(fileFd.fd);
    await fs.close(fileFd);
    fileFd = null; // 置空防止 finally 重复关闭
    
    // 4. 二次校验
    const stat = await fs.stat(savePath);
    if (stat.size !== totalWritten) {
      throw new Error(`Post-write size mismatch: stat=${stat.size}, written=${totalWritten}`);
    }

    hilog.info(0x0000, 'ManualDL', `✅ Success: ${stat.size} bytes`);

  } catch (err) {
    // 失败时清理不完整文件
    if (fileFd) {
      await fs.close(fileFd).catch(() => {});
    }
    await fs.unlink(savePath).catch(() => {});
    throw err;
  } finally {
    httpRequest.destroy();
  }
}

致命陷阱：如果上面代码中 expectDataType 用了默认的 STRING，二进制文件会被当作 UTF-8 文本解码再编码，导致：

• 非法字节序列被替换为 U+FFFD（）
• 单字节 0x80-0xFF 被扩展为 2-3 字节
• 文件体积变大且内容彻底损坏

这是"文件偏大"场景的头号元凶。

 工程化防御体系

防御层 1：写入即校验（Write-Verify Pattern）

每次下载完成后，强制执行三重校验：

interface DownloadManifest {
  url: string;
  expectedSize: number;   // 从 Content-Length 头获取
  expectedMd5?: string;   // 服务端提供
  expectedSha256?: string;
}

async function verifiedDownload(manifest: DownloadManifest): Promise<string> {
  const path = await downloader.downloadWithVerification(
    manifest.url,
    manifest.expectedSize,
    manifest.expectedMd5
  );
  
  // 额外：读取首尾字节做魔数校验（Magic Number）
  await verifyMagicNumber(path, manifest.url);
  
  return path;
}

async function verifyMagicNumber(filePath: string, url: string): Promise<void> {
  const fd = await fs.open(filePath, fs.OpenMode.READ_ONLY);
  const headerBuf = new ArrayBuffer(8);
  await fs.read(fd.fd, headerBuf, { length: 8, offset: 0 });
  await fs.close(fd);
  
  const header = new Uint8Array(headerBuf);
  const ext = url.split('.').pop()?.toLowerCase();
  
  const magicMap: Record<string, number[]> = {
    'png': [0x89, 0x50, 0x4E, 0x47],
    'jpg': [0xFF, 0xD8, 0xFF],
    'pdf': [0x25, 0x50, 0x44, 0x46], // %PDF
    'zip': [0x50, 0x4B, 0x03, 0x04],
  };
  
  if (ext && magicMap[ext]) {
    const expected = magicMap[ext];
    for (let i = 0; i < expected.length; i++) {
      if (header[i] !== expected[i]) {
        throw new Error(`Magic number mismatch for .${ext}: file may be corrupted or wrong type`);
      }
    }
  }
}

防御层 2：断点续传 + 范围请求

大文件下载必须支持 Range 请求，避免中途失败后全量重下导致的不一致窗口：

async function resumableDownload(url: string, savePath: string): Promise<void> {
  let existingSize = 0;
  
  try {
    const stat = await fs.stat(savePath);
    existingSize = stat.size;
  } catch (_) {
    // 文件不存在，从头开始
  }

  const headers: Record<string, string> = {};
  if (existingSize > 0) {
    headers['Range'] = `bytes=${existingSize}-`;
  }

  const httpRequest = http.createHttp();
  const response = await httpRequest.request(url, {
    method: http.RequestMethod.GET,
    header: headers,
    expectDataType: http.HttpDataType.ARRAY_BUFFER
  });

  const isPartial = response.responseCode === http.ResponseCode.PARTIAL_CONTENT; // 206
  const mode = isPartial 
    ? fs.OpenMode.APPEND | fs.OpenMode.WRITE_ONLY 
    : fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY | fs.OpenMode.TRUNC;

  const fd = await fs.open(savePath, mode);
  try {
    const data = new Uint8Array(response.result as ArrayBuffer);
    await fs.write(fd.fd, data.buffer);
    await fs.fsync(fd.fd);
  } finally {
    await fs.close(fd);
    httpRequest.destroy();
  }
  
  // 最终校验总大小
  const finalStat = await fs.stat(savePath);
  const contentLength = parseInt(response.header['content-length'] as string);
  const expectedTotal = isPartial ? existingSize + contentLength : contentLength;
  
  if (finalStat.size !== expectedTotal) {
    throw new Error(`Resumable download size mismatch: ${finalStat.size} vs ${expectedTotal}`);
  }
}

防御层 3：沙箱空间预检

写入前检查可用空间，避免静默截断：

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

async function checkDiskSpace(requiredBytes: number, context: Context): Promise<void> {
  const statvfs = await fs.statvfs(context.filesDir);
  const availableBytes = statvfs.f_bavail * statvfs.f_bsize;
  const safetyMargin = 1.2; // 预留 20% 余量
  
  if (availableBytes < requiredBytes * safetyMargin) {
    throw new Error(
      `Insufficient disk space: need=${Math.ceil(requiredBytes * safetyMargin)}, ` +
      `available=${availableBytes}`
    );
  }
}

 诊断与验证清单

 快速自查决策树

文件大小不一致 + 打开损坏
    │
    ├─ 沙箱文件 < 源文件？
    │   ├─ 是 → 检查 fs.close/fsync 是否遗漏
    │   │       检查是否分片下载漏了最后一片
    │   │       检查沙箱空间是否不足
    │   └─ 否（偏大）→ 几乎必然是用了 STRING 模式写二进制
    │                   立即改为 ARRAY_BUFFER
    │
    ├─ 大小相同但内容损坏？
    │   └─ 检查编码转换 / 字节序 / 加密解密环节
    │
    ├─ 偶发性不一致？
    │   └─ 异步竞态 → 加锁或串行化下载队列
    │       弱网中断 → 实现断点续传 + 临时文件 rename 模式
    │
    └─ 稳定复现？
        └─ 打印每一步的 byte count：
            network received → buffer length → fs.write return → fs.stat size
            定位差异发生在哪一环

 核心原则总结

1. 永远信任校验，不信任回调：on('complete') 只是网络层信号，必须用 stat.size + MD5 二次确认
2. 二进制文件禁用字符串模式：这是"文件偏大"的万恶之源
3. 临时文件 + rename 原子提交：避免写入中途崩溃留下半残文件污染后续逻辑
4. fsync 是数据安全落盘的最后一道闸门：尤其在掉电/强杀场景下至关重要
5. 服务端必须提供 Content-Length + MD5/SHA256：没有校验源的下载等于裸奔

。

这种情况可以优先检查下载数据 → 写入沙箱的过程，下载接口返回成功并不代表最终文件内容一定完整。

常见原因有几个：

1. 分段下载/断点续传处理有问题

   如果使用 Range 分段下载，需要确认每段数据的 Content-Range、长度以及写入文件的 offset 是否正确。offset 算错很容易导致文件偏大、偏小或者内容覆盖。

2. 二进制数据被当成字符串处理

   图片、PDF、压缩包等必须按二进制数据写入。中间如果经过字符串转换、UTF-8 编解码，很容易导致文件大小变化和文件损坏。

3. 写文件没有处理完整

   重点确认下载数据长度和实际 write() 返回长度是否一致。异步写文件时也要确保所有写操作完成后再认为下载成功。

4. 文件追加/覆盖模式错误

   重复下载时，如果使用追加模式，可能导致文件比源文件大；如果使用覆盖模式但下载过程提前结束，则可能比源文件小。

5. 云端返回的实际内容不是源文件

   建议直接检查 HTTP 响应的 Content-Length、Content-Range、Content-Encoding。例如服务器启用了 gzip/压缩传输时，响应体长度和文件原始大小不能直接比较。

排查时建议记录这几个值：

源文件实际大小
HTTP Content-Length
实际收到的数据长度
实际写入文件长度
最终沙箱文件 stat().size

如果实际收到的数据长度就已经和源文件不一致，重点查网络请求/Range/服务端。

如果收到的数据长度正确，但沙箱文件大小不一致，重点查文件写入逻辑。

如果两边大小一致但文件仍然打不开，再检查二进制数据是否被转换、截断或拼接顺序错误。

尤其是 HarmonyOS 沙箱下载文件，建议优先确认：下载响应拿到的是 ArrayBuffer/Uint8Array 等二进制数据，并且写文件时按二进制写入，不要经过字符串转换。