鸿蒙报错速查：Cannot find name 'image'，忘 import 编译就炸，根因 + 真解法

报错原文

ERROR: 10505001 ArkTS Compiler Error
Error Message: Cannot find namespace 'image'. At File: xxx.ets:N:N

报错触发场景

你写鸿蒙 ArkTS 处理图片时，直接用 image.createImageSource / image.PixelMap / image.Size 不 import 就炸：

// ❌ 报错写法
async makeThumb(): Promise<image.PixelMap> {  ← image 命名空间未 import
  const src: image.ImageSource = image.createImageSource(buf)
  return src.createPixelMap()
}

根因

鸿蒙 ArkTS 的 image 命名空间不是全局名 ------它定义在 @ohos.multimedia.image �模块里，必须显式 import 才能用。

image �命名空间下有大量图片处理类型和 API：image.createImageSource / image.createPixelMap / image.ImageSource / image.PixelMap / image.Size / image.InitializationOptions / image.PixelMapFormat 等。新手最容易踩的坑：肌肉记忆直接用 image.xxx，编译就报「Cannot find namespace 'image'」。

ArkTS 这么设计的原因：按 ES Module 规范设计------每个模块要显式 import，避免全局名污染。代价是多写一行 import，但模块化更清晰。

真解法

一种解法：显式 import

// ✅ 正解
import image from '@ohos.multimedia.image'

async makeThumb(buf: ArrayBuffer): Promise<image.PixelMap> {
  const src: image.ImageSource = image.createImageSource(buf)
  const info: image.ImageInfo = await src.getImageInfo()
  const opts: image.InitializationOptions = {
    size: { width: 200, height: 200 },
    pixelFormat: image.PixelMapFormat.RGBA_8888,
    editable: false,
    alphaType: 0
  } as image.InitializationOptions
  const pm: image.PixelMap = await src.createPixelMap(opts)
  src.release()
  return pm
}

import image from '@ohos.multimedia.image'------import 整个命名空间（不是 { } 解构单个符号）。

真机配图：import 正解能编译能跑

import image 后------正解，能编译能跑。三个 image API 都真能调：

import 正解初始态（createImageSource/makeSize/createPixelMap 均未调用）：

点调三个 API 后（都真调了，日志更新「第 3 次：createPixelMap 调用完」）：

报错写法（忘 import）编译就炸，装不上真机；正解写法（显式 import）能跑，三个 image API 都真能调。忘 import 就炸，import 了就跑------这是 image 命名空间非全局最直白的证据。

高频踩坑场景

场景 1：image.createImageSource 忘 import

// ❌ 报错
const src = image.createImageSource(buf)

// ✅ 正解
import image from '@ohos.multimedia.image'
const src: image.ImageSource = image.createImageSource(buf)

场景 2：image.PixelMap 类型忘 import

// ❌ 报错（类型用 image 命名空间，未 import）
async fn(): Promise<image.PixelMap> { ... }

// ✅ 正解
import image from '@ohos.multimedia.image'
async fn(): Promise<image.PixelMap> { ... }

场景 3：photoAccessHelper 里 image.PixelMap 也要 import

// ❌ 报错（photoAccessHelper.getThumbnail 返 image.PixelMap，image 未 import）
import photoAccessHelper from '@ohos.file.photoAccessHelper'
const pm: image.PixelMap = await asset.getThumbnail({ width: 200, height: 200 })

// ✅ 正解（两个模块都 import）
import photoAccessHelper from '@ohos.file.photoAccessHelper'
import image from '@ohos.multimedia.image'
const pm: image.PixelMap = await asset.getThumbnail({ width: 200, height: 200 })

场景 4：image.InitializationOptions 字段写错

// ❌ 报错（字段名 srcSize 不存在）
const opts: image.InitializationOptions = {
  srcSize: { width: 100, height: 100 }  ← 报错，字段叫 size 不叫 srcSize
} as image.InitializationOptions

// ✅ 正解（字段名 size）
const opts: image.InitializationOptions = {
  size: { width: 100, height: 100 },
  pixelFormat: image.PixelMapFormat.RGBA_8888,
  editable: false,
  alphaType: 0
} as image.InitializationOptions

一句话速查

Cannot find namespace 'image' → 忘 import，加 import image from '@ohos.multimedia.image'

image 命名空间速查表

API/类型	用途	import 吗
image.createImageSource	从 buf/fd 创 ImageSource	要
image.createPixelMap	创 PixelMap	要
image.ImageSource	图片源类型	要
image.PixelMap	位图类型	要
image.Size	{width, height}	要
image.InitializationOptions	PixelMap 创配置	要
image.PixelMapFormat	格式枚举	要

铁律 ：用 image.xxx 命名空间下任何 API/类型，必须 import image from '@ohos.multimedia.image'。

完整代码仓库

本文所有正解写法都已托管到 AtomGit：

🔗 仓库地址 ：atomgit.com/JaneConan/a...

仓库包含：

• 四种高频踩坑场景的 ❌ 报错写法 + ✅ 正解写法对照
• image 命名空间速查表
• 可直接用 DevEco Studio 打开参考

---

作者：JaneConan 仓库：atomgit.com/JaneConan/a... 协议：Apache-2.0，随便用，别告我