写入与删除 EXIF 元数据：Image Kit 的正确用法

问题界定：元数据修改后，图片到底变了没有？

HarmonyOS 的 Image Kit 提供了一套相对完整的图片解码与编码能力。其中，关于元数据（EXIF）的写入和删除，官方文档虽然有 API 说明，但实际开发中很容易踩到一个坑：修改了元数据，但图片文件本身没变。

很多人第一次接触这块逻辑时，会直接调用 ImageSource.updateData() 或者修改 ImagePacker 的 PackingOptions，然后发现文件没变化。原因在于，元数据的修改必须伴随一次完整的重新编码（Encode）和保存操作，而不是在原文件上直接打补丁。

这篇文章会解决两个非常具体的需求：

1. 向图片写入自定义描述信息（比如：给图片打上作者、版权、标题等）。
2. 删除图片里的 GPS 位置信息（用户隐私保护）。

这两个操作在拍照分享、图片管理工具、办公类 App 里很常见。

它解决了什么问题：不只是“改个属性”

Image Kit 的 ImagePacker 组件，提供了 PackingOptions 来携带元数据。但这个设计有一个容易忽略的前提：PackingOptions 只在打包（重新编码）时生效。也就是说，你必须在解码原图后，用 ImagePacker 重新生成一份新的图片数据，再写回文件系统。

操作	方式	是否文件级修改
读取 EXIF	ImageSource.getImageProperty()	否，仅内存读取
修改/写入 EXIF	设置 PackingOptions 后重新编码	是，生成新文件
删除 EXIF	清空或过滤 PackingOptions，再编码	是，生成新文件

简单说：任何对 EXIF 的写操作，最终都会落到“生成新图片文件”这一步上。

环境说明

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机

核心实现：写入与删除 EXIF 的完整逻辑

核心流程分四步：

1. 用 ImageSource 解码源图片（拿到原始像素数据）。
2. 构造新的 PackingOptions，设置要写入或要删除的元数据 Key-Value。
3. 用 ImagePacker 重新打包，生成 ArrayBuffer。
4. 把 ArrayBuffer 写回文件系统（覆盖原文件或另存为新文件）。

第一步：准备基础工具函数

创建一个工具文件，用来封装核心的元数据读写与编码。

// util/ImageMetaHelper.ets
import { image } from '@kit.ImageKit';
import { fileIo } from '@kit.CoreFileKit';

export class ImageMetaHelper {
  /**
   * 获取图片文件的 ImageSource 实例
   */
  static async createImageSource(uri: string): Promise<image.ImageSource> {
    let file = await fileIo.open(uri, fileIo.OpenMode.READ_ONLY);
    let fd = file.fd;
    return image.createImageSource(fd);
  }

  /**
   * 向图片写入自定义描述，并删除GPS信息
   * @param srcUri 原图路径
   * @param targetUri 目标路径（可以是同一路径，即覆盖）
   * @param description 要写入的描述（对应 exif:ImageDescription）
   */
  static async writeAndClearMetadata(
    srcUri: string,
    targetUri: string,
    description: string
  ): Promise<void> {
    // 1. 创建解码源
    let imageSource: image.ImageSource = await this.createImageSource(srcUri);

    // 2. 配置打包参数：写入描述，删除GPS
    let packOpts: image.PackingOption = {
      format: "image/jpeg",  // 支持jpg/jpeg格式
      quality: 95,
      metadata: {
        // 【写入】自定义描述信息
        ["exif:ImageDescription"]: description,

        // 【删除GPS】将GPS相关字段设为空字符串
        ["exif:GPSLatitude"]: "",
        ["exif:GPSLongitude"]: "",
        ["exif:GPSLatitudeRef"]: "",
        ["exif:GPSLongitudeRef"]: "",
        ["exif:GPSAltitude"]: "",
        ["exif:GPSTimeStamp"]: "",
      }
    };

    // 3. 从ImageSource解码出一帧图像（通常是第0帧）
    let pixelMap: image.PixelMap = await imageSource.createPixelMap();

    // 4. 创建ImagePacker并重新编码
    let packer: image.ImagePacker = image.createImagePacker();
    // 这里用到 packingOptions 携带元数据
    let packedData: ArrayBuffer = await packer.packing(pixelMap, packOpts);

    // 5. 将新数据写回文件系统
    let file = await fileIo.open(targetUri, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY);
    await fileIo.write(file.fd, packedData);
    fileIo.close(file);
    console.info("ImageMetaHelper: 元数据写入/删除完成，已重新编码保存。");
  }
}

关键点说明：

• 删除的逻辑：通过将 GPS 相关字段设为空字符串 "" 来实现。系统在打包时如果检测到空值，会跳过或清除该字段。
• PackingOption.metadata 的类型：它是一个 Record<string, string | number | boolean>，所有值都必须是基础类型。不能传复杂对象。
• 重新编码是必须的：packer.packing() 会基于 PixelMap 和 PackingOptions 生成一个全新的 ArrayBuffer。不经过这一步，元数据只在 ImageSource 的缓存里，不会落到文件上。

第二步：页面调用

在页面中触发这个操作，并选择一张图片。

// pages/Index.ets
import { ImageMetaHelper } from '../util/ImageMetaHelper';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

@Entry
@Component
struct Index {
  @State statusMsg: string = "未开始";

  build() {
    Column({ space: 16 }) {
      Button("选择图片并修改元数据")
        .onClick(async () => {
          // 1. 通过Picker选择图片
          let uri = await this.pickImage();
          if (!uri) return;
          // 2. 写入描述，删除GPS
          await ImageMetaHelper.writeAndClearMetadata(
            uri,
            uri, // 覆盖原文件
            "这是一张来自HarmonyOS设备的测试图片"
          );
          this.statusMsg = "元数据已更新，请检查原图属性";
        })
      Text(this.statusMsg)
        .fontSize(14)
    }
    .padding(24)
  }

  async pickImage(): Promise<string | null> {
    try {
      let helper = photoAccessHelper.getPhotoAccessHelper(getContext(this));
      let uri = await helper.selectPhotoUri();
      return uri;
    } catch (e) {
      console.error("选择图片失败: " + JSON.stringify(e));
      return null;
    }
  }
}

真正有价值的“踩坑”记录

坑1：修改元数据后，原文件大小没变

现象：调用 writeAndClearMetadata 后，用文件管理器查看，发现文件大小、修改时间都没变化。再次读取 ImageDescription 依然是旧值。

原因：最常见的原因是没有正确关闭文件句柄。在写文件时，fileIo.write 是异步操作，如果写入尚未落盘就立即关闭了 fileIo 实例，数据会被丢弃。实际开发中，如果你在 close 之前没有 await write 完成，就会出现“写了个寂寞”的情况。

解法：确保 await fileIo.write() 完成后再调用 close。上面给的代码已经是正确的写法。另外，检查一下 PackingOption.metadata 的 key 名是否写错。正确的 key 是 "exif:ImageDescription"（注意冒号后的 ImageDescription 首字母大写）。写错 key 名，系统会直接忽略。

坑2：删除 GPS 后，部分第三方软件依然能读取到位置

现象：删除了 GPS 相关字段，但在某些高级看图软件（如 Lightroom、Bridge）中，依然能找到位置信息。

原因：HarmonyOS 的 PackingOption 清除的是标准 EXIF 标签，但有些图片里包含的是 EXIF 的 MakerNote 字段，或 XMP 数据，这些数据可能保存着更详细的 GPS 或设备信息。目前 Image Kit 的 PackingOption 对非标准字段的覆盖范围有限。

解法：更彻底的做法是，在 PackingOption 里显式设置一些常见的空值。如果仍然不满足，建议在写入前先通过 ImageSource.getImageProperty("exif:MakerNote") 检查是否包含敏感数据，然后在重新编码时，在 PackingOptions 里用 "" 覆盖。不过，最彻底的方式是直接生成一张不包含任何元数据的新图片，做法是在 PackingOptions 里不设置任何 metadata 字段，只保留基本的 format 和 quality。这样输出图片的 EXIF 段会被清空。

// 最彻底的删除方式：不传metadata
let packOpts: image.PackingOption = {
  format: "image/jpeg",
  quality: 95
  // metadata: {} // 不设置，输出图片将不包含EXIF
};

最佳实践（具体建议）

1. 每步都检查返回值和异常。文件操作+编解码是IO密集任务，每一步都可能因为磁盘空间不足、文件损坏、格式不支持而失败。建议在 await 后加上 try/catch，并在 catch 块里释放已打开的 ImageSource 和 file 句柄，防止资源泄漏。

2. 理解 PixelMap 的生命周期。createPixelMap() 返回的 PixelMap 对象如果不再使用，应该调用 pixelMap.release() 释放 native 层内存。如果不释放，在反复操作多张图片时，App 的内存会持续增长，最终被系统杀掉。

3. 写入操作尽量在后台线程执行。packer.packing() 在解码和重新编码时计算量较大，如果在主线程执行，会导致 UI 卡顿。可以使用 TaskPool 将整个 writeAndClearMetadata 方法迁移到 Worker 里执行。

FAQ（真实开发视角）

Q：为什么我写入 exif:ImageDescription 后，Windows 文件属性里的“描述”为空？

A：Windows 文件属性的“描述”字段读取的是 EXIF 的 XPTitle 或 ImageDescription。注意，只有标准 JPEG/TIFF 格式才支持这个字段。另外，Windows 资源管理器可能缓存了旧属性，刷新一下文件列表再查看。

Q：图片修改后，部分手机相册 App 显示“图片已损坏”，怎么处理？

A：通常是 PackingOption 的 format 和实际文件类型不匹配导致的。例如，你把一个 PNG 图片的 format 设为了 "image/jpeg"，解码后的 PixelMap 被强行压缩为 JPEG 格式，但文件后缀仍然是 .png，导致其他软件解析错误。建议保持 format 与源文件一致，或者在保存时统一将后缀名改为 .jpg。

Q：删除 GPS 信息后，照片的地理位置是否100%无法恢复？

A：不是。上面说过，Image Kit 清除的是标准 EXIF 标签。如果图片文件里还嵌入了 GPS 轨迹的 XMP 数据，或者 Google 相册有云端备份，那这些信息仍然能恢复。本地文件层面，Image Kit 的清除是有效的，但无法覆盖所有非标数据。如果对隐私要求极高，建议预处理时用独立工具（如 libexif）直接重写 EXIF 段。

示例代码地址：项目地址