去年接了个跨端适配的活儿要把一款已经跑了好几年的 React Native 应用移植到一个新增的系统平台——鸿蒙。团队里没有人接触过鸿蒙的原生开发RN 适配来得也突然所有人都在摸黑走路。业务方给出的第一个需求很朴素用户要在 App 里拍照、选相册图片然后上传到服务器。听起来平平无奇但就是这个看似基础的 ImagePicker 功能我在适配过程中前前后后踩了十几天的坑从权限弹窗不出现到上传的文件后端打不开几乎每个环节都掉了一遍。这篇文章就是这次实战的完整复盘包含鸿蒙权限模型、RN 桥接层对接、图片路径适配、multipart/form-data 上传以及弱网重试机制希望能给正在做 RN 鸿蒙适配的同行省一些时间。1. 项目背景为什么第一个要攻克的就是 ImagePicker1.1 从业务场景看功能定位先回到需求本身。这个 App 里的图片上传不是单一入口而是散落在好几个业务模块个人头像、用户反馈带截图、订单凭证拍照、社区帖子配图。每个模块对图片的要求不同头像要求压缩到 200KB 以内订单凭证要求原图清晰、不能过度压缩社区配图则希望选完图能裁剪构图。统一的诉求只有一个——拍照/选图 → 上传 → 拿到 URL 回填给业务层。这个链路看着简单拆开却涉及四个子系统系统权限、媒体库访问、临时文件管理、网络上传。任何一个环节在鸿蒙的交互方式有变化就会直接暴露给用户。比如权限弹窗没弹出来用户点拍照按钮毫无反应比如图片路径解析不对上传直接失败。所以在 RN 适配鸿蒙的最早期我们优先把 ImagePicker 跑通目的就是用这个功能把鸿蒙平台上的系统能力链路完整验证一遍。1.2 技术选型三条路线的取舍RN 生态里做图片选择方案不外乎三种我逐一试过之后才选定最终路线直接用react-native-image-picker。这是最成熟的库API 设计把拍照和相册选择统一成两个方法launchCamera和launchImageLibrary返回的 asset 对象包含 uri、宽度、高度、文件类型等标准字段。但它在鸿蒙上没有官方支持需要自己补一套原生桥接实现。直接用鸿蒙的PhotoViewPicker自己写原生模块。这套 API 设计得很好但意味着所有上层逻辑都要自己封装工作量大而且后续维护成本高。临时方案让用户先用系统相机 App 拍完照、再用文件路径拼接一个假 asset。这个方案我只在验证阶段用过不可持续。最后的选择是第一条路沿用react-native-image-picker的 JS 层 API在鸿蒙原生侧写桥接实现把鸿蒙的PhotoViewPicker、相机能力和权限逻辑封装到库的底层。这样上层业务代码在 Android、iOS、鸿蒙三端完全一致后续维护时只需要关注原生桥接层。1.3 整体架构怎么分层定完选型我画了整个模块的分层业务层只在 JS 里调用ImagePickerService.takePhoto()或ImagePickerService.chooseFromLibrary()不感知平台差异。服务层JS 里封装统一的ImagePickerService负责组装参数、解析结果、调用上传。桥接层RN 的 Native Module / TurboModule把 JS 调用映射到鸿蒙原生 Api同时负责处理 URI 转换、权限申请。原生层鸿蒙的abilityAccessCtrl权限 API、PhotoViewPicker选图 API、相机拍照 API。这套分层从一开始就定下来后期大量返工都省掉了。最核心的原则是平台差异必须被终结在桥接层不允许向上渗透到业务代码。2. 鸿蒙权限模型这块不搞清楚拍照永远起不来2.1 静态声明和动态申请是两回事鸿蒙的敏感权限机制和 Android 有点像但细节不一样。Android 是在 Manifest 里声明权限然后在代码里动态申请授权弹窗由系统管理。鸿蒙则是在module.json5里声明requestPermissions同时还需要在代码里调用requestPermissionsFromUser才能真正触发用户的授权弹窗。这里有一个很容易踩的坑很多人以为在module.json5里写了权限声明系统就会自动弹窗。实际上不会。你只是完成了告诉系统这个应用可能用到该权限这一步用户授权弹窗是另一套机制。必须调用鸿蒙的requestPermissionsFromUser弹窗才会出现。以拍照上传为例需要两个敏感权限ohos.permission.CAMERA打开相机拍照。ohos.permission.READ_MEDIA读取相册媒体库。有些鸿蒙版本还区分READ_MEDIA和WRITE_MEDIA如果只是选取用户相册里已有的图片READ_MEDIA就够。要注意的是不同 API 版本里的权限名称可能略有差异开发前先确认当前系统版本的权限列表我就在这上面吃过亏——旧名字写进去编译能过但运行时申请永远失败。2.2 动态申请的代码落地我在桥接层暴露了一个ensurePermissions方法给 JS 调用底层走的是鸿蒙abilityAccessCtrlimport { abilityAccessCtrl, bundleManager, common } from kit.AbilityKit; import { BusinessError } from kit.BasicServicesKit; async function requestPhotoPermissions(context: common.UIAbilityContext): Promiseboolean { const atManager abilityAccessCtrl.createAtManager(); const permissions [ ohos.permission.CAMERA, ohos.permission.READ_MEDIA, ]; try { const result await atManager.requestPermissionsFromUser(context, permissions); // 结果里会返回每个权限的授权状态需要逐一判断 const granted result.authResults.every((item) item 0); return granted; } catch (err) { const error err as BusinessError; console.error(Permission request failed: ${error.code} ${error.message}); return false; } }这里有个细节authResults是逐项对应的不能只看整体返回值。如果只申请一个权限还好说两个权限时必须逐项判断不然可能出现相机权限给了、相册权限没给你也浑然不觉的情况。关于授权时机我也要特意强调不要在模块加载阶段就申请权限应该推迟到用户第一次真正需要触发拍照或选图时。一是为了符合应用商店的审核规范二是从用户体验上讲一进页面就弹一堆权限框用户很大概率直接拒绝后续再引导就费劲了。2.3 拒绝后的降级策略权限被拒绝之后能做什么这是最容易被人忽视的部分。我一开始也只是在 JS 层弹了个 Toast后来发现体验极差——用户完全不知道接下来该怎么办。建议按三种情况分别处理用户点了拒绝但没勾选不再询问下次点击拍照时重新弹出申请弹窗。用户勾选了不再询问应用内无法再次触发系统弹窗只能引导用户跳转到系统设置页手动开启权限。这个跳转可以通过鸿蒙的SettingProviderAPI 完成。用户拒绝了相机权限但给了相册权限UI 层动态隐藏拍照上传入口只保留从相册选择。这三种分支逻辑不复杂但能明显减少功能看起来坏了的客服投诉。3. 核心实现拍照、选图、路径转换、上传3.1 JS 侧统一封装无论底层怎么实现JS 侧我始终只用一个统一入口。下面是我项目里的ImagePickerService核心代码import { launchCamera, launchImageLibrary } from react-native-image-picker; export interface PhotoAsset { uri: string; width?: number; height?: number; type?: string; fileName?: string; } const baseOptions { mediaType: photo as const, includeBase64: false, maxWidth: 1920, maxHeight: 1920, quality: 0.9, }; export const ImagePickerService { async takePhoto(): PromisePhotoAsset | null { const result await launchCamera(baseOptions); if (result.didCancel) return null; if (result.errorCode) { throw new Error(Camera error: ${result.errorMessage}); } return result.assets?.[0] ?? null; }, async chooseFromLibrary(): PromisePhotoAsset | null { const result await launchImageLibrary({ ...baseOptions, selectionLimit: 1 }); if (result.didCancel) return null; if (result.errorCode) { throw new Error(Gallery error: ${result.errorMessage}); } return result.assets?.[0] ?? null; }, };这段代码在 Android 和 iOS 上没有任何问题。真正花功夫的是它在鸿蒙平台上的一些差异化处理下面展开讲。3.2 桥接层与鸿蒙原生 API 的对接react-native-image-picker官方并没有鸿蒙的原生实现所以我在鸿蒙侧写了一个 Native Module模拟库原有的对外接口。这个原生模块需要实现两个核心方法launchCamera和launchImageLibrary。对相册选取鸿蒙的标准做法是使用photoAccessHelper.PhotoViewPickerimport { photoAccessHelper } from kit.MediaLibraryKit; async function pickFromGallery(): Promisestring { const picker new photoAccessHelper.PhotoViewPicker(); const options new photoAccessHelper.PhotoSelectOptions(); options.MIMEType photoAccessHelper.PhotoMIMETypes.IMAGE_TYPE; options.maxSelectNumber 1; const result await picker.select(options); const uri result.photoUris[0]; return uri; }拍照方面更稳妥的做法也是通过系统级别的能力拉起相机让用户拍完后返回图片 URI。这里有一个细节不同鸿蒙版本对PhotoViewPicker的返回格式有差异有些版本直接返回file://media/xxx有些版本返回datashare://media/xxx所以在桥接层必须做一层 URI 归一化。3.3 路径适配从 datashare:// 到可上传的 file://这是整篇文章里最值得记录的一个坑。在 Android 上react-native-image-picker返回的 uri 通常是content://media/external/images/media/123标准FormData配合fetch可以直接把流读出来上传。但在鸿蒙上返回的 uri 可能是file://media/Photo/xx.jpg、file://docs/storage/...或者datashare://media/...不同的 URI 前缀在这个平台上的可读性差异很大。我最初直接把 uri 塞进FormData结果服务端根本收不到文件体。解决办法是在桥接层增加一个resolveUploadPath方法import { fileIo as fs } from kit.CoreFileKit; function resolveUploadPath(uri: string): string { // 如果已经是 file:// 开头去掉前缀取路径 if (uri.startsWith(file://)) { return uri.replace(file://, ); } // 如果是 datashare:// 或 media://需要走资源拷贝 const tmpPath ${getAppCacheDir()}/upload_tmp_${Date.now()}.jpg; fs.copySync(uri, tmpPath); return tmpPath; }核心思路是绝不能信任外部传入的 uri 前缀一定要在原生层把 URI 转换为应用沙盒内的实际文件路径。转换后的路径可以被FormData正常读取。这里我补充一个经验拷贝文件到沙盒时目标后缀名要根据asset.type来定不然有些服务端会根据扩展名判断文件类型jpg写成了png服务端解码直接报错。3.4 上传实现multipart/form-data 的完整套路路径解析好了上传代码就是常规套路但有几个细节必须注意。先看代码async function uploadImage(asset: PhotoAsset, userId: string): Promisestring { const formData new FormData(); formData.append(file, { uri: asset.uri, type: asset.type || image/jpeg, name: asset.fileName || photo.jpg, }); formData.append(userId, userId); formData.append(channel, harmony); const response await fetch(https://api.example.com/v1/upload, { method: POST, headers: { Content-Type: multipart/form-data, }, body: formData, }); if (!response.ok) { throw new Error(upload failed: HTTP ${response.status}); } const json await response.json(); return json.url; // 服务端返回的图片访问地址 }三个细节第一Content-Type头不写boundary。RN 的 fetch 会自动生成边界标记如果你手动加了错误格式的boundary服务端解析 multipart 时就会分割错误。我见过太多人在这里手动拼字符串反而出问题。第二FormData里 file 字段的三个子属性缺一不可。uri告诉底层从哪里读文件type告诉服务端文件 MIME 类型name决定服务端保存的文件名。fileName如果为空很多后端会直接拒绝请求。第三如果图片是 PNG 但asset.type没返回上面的代码默认image/jpeg就会出错。稳妥做法是后端配合识别或者前端根据文件名后缀兜底。3.5 上传进度、超时与重试机制fetch有个天生缺陷不支持上传进度回调。如果需求里要给用户展示进度条必须换成XMLHttpRequestfunction uploadWithProgress(formData: FormData, onProgress: (pct: number) void) { return new Promise((resolve, reject) { const xhr new XMLHttpRequest(); xhr.open(POST, https://api.example.com/v1/upload); xhr.setRequestHeader(Content-Type, multipart/form-data); xhr.timeout 30000; xhr.upload.addEventListener(progress, (event) { if (event.lengthComputable) { const pct Math.round((event.loaded / event.total) * 100); onProgress(pct); } }); xhr.onload () { // 这里注意xhr 拿到的是字符串要自己 JSON.parse resolve(xhr.responseText); }; xhr.onerror () { reject(new Error(network error)); }; xhr.ontimeout () { reject(new Error(request timeout)); }; xhr.send(formData); }); }配合一个指数退避的重试函数实测弱网环境下成功率提升非常明显async function uploadWithRetry(formData: FormData, retries 2) { let attempt 0; while (attempt retries) { try { return await uploadWithProgress(formData, () {}); } catch (err) { attempt; if (attempt retries) throw err; await new Promise((r) setTimeout(r, 1000 * Math.pow(2, attempt))); } } }重试逻辑要注意幂等性后端接口必须支持上传接口幂等或者前端在重试时不能重复提交表单里已有的订单号等业务字段。4. 踩坑实录五个最常见的翻车现场4.1 权限弹窗不出现这是最常见的问题没有之一。现象是点击拍照按钮没反应控制台也没有任何日志。排查路径我总结如下第一步检查module.json5里是否真的声明了ohos.permission.CAMERA。不要看文件名要看打包进产物里那份。第二步确认requestPermissionsFromUser是在用户点击拍照时调用而不是在 App 启动或者页面加载时就提前调了一遍。如果提前申请过即使返回了拒绝后续再调用可能不再弹窗。第三步检查上下文参数是否传入正确。requestPermissionsFromUser需要UIAbilityContext如果把普通的Context传了进去调用会静默失败。我当时踩的坑就是第二步——模块初始化时我把权限申请跑了一遍以为提前申请好能提升流畅度结果用户点击拍照时弹窗根本不出现后来查日志才发现权限请求已经返回了拒绝状态。4.2 uri 解析失败导致上传报错症状是拍照正常、预览正常一上传就失败。最初我还以为是网络问题后来打了个日志才发现asset.uri的值是datashare://media/image/photo/123直接塞进FormData后底层根本读不出文件流。解决办法就是我前面说的resolveUploadPath。这里提醒一下在桥接层把 URI 转换成文件路径时要用同步方式在小文件场景下减少回调地狱但如果文件较大还是用异步拷贝避免阻塞 UI 线程。4.3 includeBase64 引发内存峰值有些同学图省事把includeBase64设为true这样可以直接拿到图片的 Base64 字符串省去文件路径处理。千万别这么干。Base64 编码会让数据体积增加约 33%6MB 的图片变成 8MB 的字符串。更要命的是这个字符串还全量存在于 JS 堆内存里。RN 的 JS 引擎在鸿蒙设备上本来就受内存限制比较严格一张几 MB 的图片做 Base64 转换在那个瞬间就可能触发内存告警进而导致整个 App 被杀。我的铁律是includeBase64永远为false图片一律走文件路径上传。4.4 服务端收到的图片损坏或无法解码上传接口返回 200 了但服务端拿着文件打不开提示Invalid image file。原因基本都是type字段不匹配。比如图片明明是 PNG但上传代码里写死了image/jpeg或者文件名后缀与实际编码不一致。解决办法是上传前做一次统一校验function detectMimeType(fileName: string, rawType?: string): string { if (rawType) return rawType; const ext fileName.split(.).pop()?.toLowerCase() ?? jpg; const mimeMap: Recordstring, string { jpg: image/jpeg, jpeg: image/jpeg, png: image/png, gif: image/gif, webp: image/webp, }; return mimeMap[ext] ?? image/jpeg; }这个函数很小但帮我挡掉了至少三次线上问题。4.5 真机和模拟器行为差异鸿蒙模拟器的相册里面预置了几张示例图片拍照也是模拟的不会真正调用相机硬件。结果就是模拟器上一切正常一到真机就出问题。真实差异主要在三个地方一是真机照片带有 EXIF 旋转信息部分场景下预览方向是反的二是真机返回的 URI 格式和模拟器不完全一样模拟器可能统一返回file://真机却返回datashare://三是真机的拍照行为受相机硬件和厂商定制层影响可能出现极端分辨率。所以这个功能从第一天起就要保留一台真机做回归验证不能只依赖模拟器。5. 几点经验沉淀如果让我重新做一遍这个功能我会把精力更多地放在下面四个方面这些也是我做完整个项目的核心体会。第一桥接层要做得足够厚实。鸿蒙适配的诡异问题绝大多数都发生在原生层和 JS 层之间的缝隙里比如 URI 格式、权限上下文、文件读写。把这些通通收进桥接层用统一的接口暴露给 JS整个项目组后续维护成本会低很多。第二权限逻辑必须提前设计分支。用户拒绝授权不是异常而是常态。在大规模设备上一定会有用户拒绝、用户误触、用户后悔授权等各种情况。代码里把授权状态的分支都处理好比事后在线上看崩溃日志要省力得多。第三上传要内置进度反馈和重试。用户能感知到的只有图片发出去了没有。进度条提升的是安全感重试机制提升的是成功率两者加在一起才能把图片上传失败转变成图片上传重试中请稍候这种不那么刺眼的提示。第四多平台验证不要偷懒。我在 Android、iOS、鸿蒙三端同时跑同一套 JS 代码表面上代码是统一的但每端的原生实现细节并不一致。每个平台在拍照-上传这个链路里至少覆盖十次真机测试才敢说这个功能稳定。最后分享一个实用小技巧调试阶段可以在桥接层临时加一个__dumpImageInfo(rawUri)方法把原始 URI、归一化后的路径、文件大小、MIME 类型全部打印出来。这个 dump 逻辑在整个开发阶段帮了我大忙几乎每个上传失败的问题都能靠它快速定位到具体环节。等到功能稳定后再把这个方法移除或者用编译开关控制不会有什么性能影响。 去年接了个跨端适配的活儿要把一款已经跑了好几年的 React Native 应用移植到一个新增的系统平台——鸿蒙。团队里没有人接触过鸿蒙的原生开发RN 适配来得也突然所有人都在摸黑走路。业务方给出的第一个需求很朴素用户要在 App 里拍照、选相册图片然后上传到服务器。听起来平平无奇但就是这个看似基础的 ImagePicker 功能我在适配过程中前前后后踩了十几天的坑从权限弹窗不出现到上传的文件后端打不开几乎每个环节都掉了一遍。这篇文章就是这次实战的完整复盘包含鸿蒙权限模型、RN 桥接层对接、图片路径适配、multipart/form-data 上传以及弱网重试机制希望能给正在做 RN 鸿蒙适配的同行省一些时间。1. 项目背景为什么第一个要攻克的就是 ImagePicker1.1 从业务场景看功能定位先回到需求本身。这个 App 里的图片上传不是单一入口而是散落在好几个业务模块个人头像、用户反馈带截图、订单凭证拍照、社区帖子配图。每个模块对图片的要求不同头像要求压缩到 200KB 以内订单凭证要求原图清晰、不能过度压缩社区配图则希望选完图能裁剪构图。统一的诉求只有一个——拍照/选图 → 上传 → 拿到 URL 回填给业务层。这个链路看着简单拆开却涉及四个子系统系统权限、媒体库访问、临时文件管理、网络上传。任何一个环节在鸿蒙的交互方式有变化就会直接暴露给用户。比如权限弹窗没弹出来用户点拍照按钮毫无反应比如图片路径解析不对上传直接失败。所以在 RN 适配鸿蒙的最早期我们优先把 ImagePicker 跑通目的就是用这个功能把鸿蒙平台上的系统能力链路完整验证一遍。1.2 技术选型三条路线的取舍RN 生态里做图片选择方案不外乎三种我逐一试过之后才选定最终路线直接用react-native-image-picker。这是最成熟的库API 设计把拍照和相册选择统一成两个方法launchCamera和launchImageLibrary返回的 asset 对象包含 uri、宽度、高度、文件类型等标准字段。但它在鸿蒙上没有官方支持需要自己补一套原生桥接实现。直接用鸿蒙的PhotoViewPicker自己写原生模块。这套 API 设计得很好但意味着所有上层逻辑都要自己封装工作量大而且后续维护成本高。临时方案让用户先用系统相机 App 拍完照、再用文件路径拼接一个假 asset。这个方案我只在验证阶段用过不可持续。最后的选择是第一条路沿用react-native-image-picker的 JS 层 API在鸿蒙原生侧写桥接实现把鸿蒙的PhotoViewPicker、相机能力和权限逻辑封装到库的底层。这样上层业务代码在 Android、iOS、鸿蒙三端完全一致后续维护时只需要关注原生桥接层。1.3 整体架构怎么分层定完选型我画了整个模块的分层业务层只在 JS 里调用ImagePickerService.takePhoto()或ImagePickerService.chooseFromLibrary()不感知平台差异。服务层JS 里封装统一的ImagePickerService负责组装参数、解析结果、调用上传。桥接层RN 的 Native Module / TurboModule把 JS 调用映射到鸿蒙原生 Api同时负责处理 URI 转换、权限申请。原生层鸿蒙的abilityAccessCtrl权限 API、PhotoViewPicker选图 API、相机拍照 API。这套分层从一开始就定下来后期大量返工都省掉了。最核心的原则是平台差异必须被终结在桥接层不允许向上渗透到业务代码。2. 鸿蒙权限模型这块不搞清楚拍照永远起不来2.1 静态声明和动态申请是两回事鸿蒙的敏感权限机制和 Android 有点像但细节不一样。Android 是在 Manifest 里声明权限然后在代码里动态申请授权弹窗由系统管理。鸿蒙则是在module.json5里声明requestPermissions同时还需要在代码里调用requestPermissionsFromUser才能真正触发用户的授权弹窗。这里有一个很容易踩的坑很多人以为在module.json5里写了权限声明系统就会自动弹窗。实际上不会。你只是完成了告诉系统这个应用可能用到该权限这一步用户授权弹窗是另一套机制。必须调用鸿蒙的requestPermissionsFromUser弹窗才会出现。以拍照上传为例需要两个敏感权限ohos.permission.CAMERA打开相机拍照。ohos.permission.READ_MEDIA读取相册媒体库。有些鸿蒙版本还区分READ_MEDIA和WRITE_MEDIA如果只是选取用户相册里已有的图片READ_MEDIA就够。要注意的是不同 API 版本里的权限名称可能略有差异开发前先确认当前系统版本的权限列表我就在这上面吃过亏——旧名字写进去编译能过但运行时申请永远失败。2.2 动态申请的代码落地我在桥接层暴露了一个ensurePermissions方法给 JS 调用底层走的是鸿蒙abilityAccessCtrlimport { abilityAccessCtrl, bundleManager, common } from kit.AbilityKit; import { BusinessError } from kit.BasicServicesKit; async function requestPhotoPermissions(context: common.UIAbilityContext): Promiseboolean { const atManager abilityAccessCtrl.createAtManager(); const permissions [ ohos.permission.CAMERA, ohos.permission.READ_MEDIA, ]; try { const result await atManager.requestPermissionsFromUser(context, permissions); // 结果里会返回每个权限的授权状态需要逐一判断 const granted result.authResults.every((item) item 0); return granted; } catch (err) { const error err as BusinessError; console.error(Permission request failed: ${error.code} ${error.message}); return false; } }这里有个细节authResults是逐项对应的不能只看整体返回值。如果只申请一个权限还好说两个权限时必须逐项判断不然可能出现相机权限给了、相册权限没给你也浑然不觉的情况。关于授权时机我也要特意强调不要在模块加载阶段就申请权限应该推迟到用户第一次真正需要触发拍照或选图时。一是为了符合应用商店的审核规范二是从用户体验上讲一进页面就弹一堆权限框用户很大概率直接拒绝后续再引导就费劲了。2.3 拒绝后的降级策略权限被拒绝之后能做什么这是最容易被人忽视的部分。我一开始也只是在 JS 层弹了个 Toast后来发现体验极差——用户完全不知道接下来该怎么办。建议按三种情况分别处理用户点了拒绝但没勾选不再询问下次点击拍照时重新弹出申请弹窗。用户勾选了不再询问应用内无法再次触发系统弹窗只能引导用户跳转到系统设置页手动开启权限。这个跳转可以通过鸿蒙的SettingProviderAPI 完成。用户拒绝了相机权限但给了相册权限UI 层动态隐藏拍照上传入口只保留从相册选择。这三种分支逻辑不复杂但能明显减少功能看起来坏了的客服投诉。3. 核心实现拍照、选图、路径转换、上传3.1 JS 侧统一封装无论底层怎么实现JS 侧我始终只用一个统一入口。下面是我项目里的ImagePickerService核心代码import { launchCamera, launchImageLibrary } from react-native-image-picker; export interface PhotoAsset { uri: string; width?: number; height?: number; type?: string; fileName?: string; } const baseOptions { mediaType: photo as const, includeBase64: false, maxWidth: 1920, maxHeight: 1920, quality: 0.9, }; export const ImagePickerService { async takePhoto(): PromisePhotoAsset | null { const result await launchCamera(baseOptions); if (result.didCancel) return null; if (result.errorCode) { throw new Error(Camera error: ${result.errorMessage}); } return result.assets?.[0] ?? null; }, async chooseFromLibrary(): PromisePhotoAsset | null { const result await launchImageLibrary({ ...baseOptions, selectionLimit: 1 }); if (result.didCancel) return null; if (result.errorCode) { throw new Error(Gallery error: ${result.errorMessage}); } return result.assets?.[0] ?? null; }, };这段代码在 Android 和 iOS 上没有任何问题。真正花功夫的是它在鸿蒙平台上的一些差异化处理下面展开讲。3.2 桥接层与鸿蒙原生 API 的对接react-native-image-picker官方并没有鸿蒙的原生实现所以我在鸿蒙侧写了一个 Native Module模拟库原有的对外接口。这个原生模块需要实现两个核心方法launchCamera和launchImageLibrary。对相册选取鸿蒙的标准做法是使用photoAccessHelper.PhotoViewPickerimport { photoAccessHelper } from kit.MediaLibraryKit; async function pickFromGallery(): Promisestring { const picker new photoAccessHelper.PhotoViewPicker(); const options new photoAccessHelper.PhotoSelectOptions(); options.MIMEType photoAccessHelper.PhotoMIMETypes.IMAGE_TYPE; options.maxSelectNumber 1; const result await picker.select(options); const uri result.photoUris[0]; return uri; }拍照方面更稳妥的做法也是通过系统级别的能力拉起相机让用户拍完后返回图片 URI。这里有一个细节不同鸿蒙版本对PhotoViewPicker的返回格式有差异有些版本直接返回file://media/xxx有些版本返回datashare://media/xxx所以在桥接层必须做一层 URI 归一化。3.3 路径适配从 datashare:// 到可上传的 file://这是整篇文章里最值得记录的一个坑。在 Android 上react-native-image-picker返回的 uri 通常是content://media/external/images/media/123标准FormData配合fetch可以直接把流读出来上传。但在鸿蒙上返回的 uri 可能是file://media/Photo/xx.jpg、file://docs/storage/...或者datashare://media/...不同的 URI 前缀在这个平台上的可读性差异很大。我最初直接把 uri 塞进FormData结果服务端根本收不到文件体。解决办法是在桥接层增加一个resolveUploadPath方法import { fileIo as fs } from kit.CoreFileKit; function resolveUploadPath(uri: string): string { // 如果已经是 file:// 开头去掉前缀取路径 if (uri.startsWith(file://)) { return uri.replace(file://, ); } // 如果是 datashare:// 或 media://需要走资源拷贝 const tmpPath ${getAppCacheDir()}/upload_tmp_${Date.now()}.jpg; fs.copySync(uri, tmpPath); return tmpPath; }核心思路是绝不能信任外部传入的 uri 前缀一定要在原生层把 URI 转换为应用沙盒内的实际文件路径。转换后的路径可以被FormData正常读取。这里我补充一个经验拷贝文件到沙盒时目标后缀名要根据asset.type来定不然有些服务端会根据扩展名判断文件类型jpg写成了png服务端解码直接报错。3.4 上传实现multipart/form-data 的完整套路路径解析好了上传代码就是常规套路但有几个细节必须注意。先看代码async function uploadImage(asset: PhotoAsset, userId: string): Promisestring { const formData new FormData(); formData.append(file, { uri: asset.uri, type: asset.type || image/jpeg, name: asset.fileName || photo.jpg, }); formData.append(userId, userId); formData.append(channel, harmony); const response await fetch(https://api.example.com/v1/upload, { method: POST, headers: { Content-Type: multipart/form-data, }, body: formData, }); if (!response.ok) { throw new Error(upload failed: HTTP ${response.status}); } const json await response.json(); return json.url; // 服务端返回的图片访问地址 }三个细节第一Content-Type头不写boundary。RN 的 fetch 会自动生成边界标记如果你手动加了错误格式的boundary服务端解析 multipart 时就会分割错误。我见过太多人在这里手动拼字符串反而出问题。第二FormData里 file 字段的三个子属性缺一不可。uri告诉底层从哪里读文件type告诉服务端文件 MIME 类型name决定服务端保存的文件名。fileName如果为空很多后端会直接拒绝请求。第三如果图片是 PNG 但asset.type没返回上面的代码默认image/jpeg就会出错。稳妥做法是后端配合识别或者前端根据文件名后缀兜底。3.5 上传进度、超时与重试机制fetch有个天生缺陷不支持上传进度回调。如果需求里要给用户展示进度条必须换成XMLHttpRequestfunction uploadWithProgress(formData: FormData, onProgress: (pct: number) void) { return new Promise((resolve, reject) { const xhr new XMLHttpRequest(); xhr.open(POST, https://api.example.com/v1/upload); xhr.setRequestHeader(Content-Type, multipart/form-data); xhr.timeout 30000; xhr.upload.addEventListener(progress, (event) { if (event.lengthComputable) { const pct Math.round((event.loaded / event.total) * 100); onProgress(pct); } }); xhr.onload () { // 这里注意xhr 拿到的是字符串要自己 JSON.parse resolve(xhr.responseText); }; xhr.onerror () { reject(new Error(network error)); }; xhr.ontimeout () { reject(new Error(request timeout)); }; xhr.send(formData); }); }配合一个指数退避的重试函数实测弱网环境下成功率提升非常明显async function uploadWithRetry(formData: FormData, retries 2) { let attempt 0; while (attempt retries) { try { return await uploadWithProgress(formData, () {}); } catch (err) { attempt; if (attempt retries) throw err; await new Promise((r) setTimeout(r, 1000 * Math.pow(2, attempt))); } } }重试逻辑要注意幂等性后端接口必须支持上传接口幂等或者前端在重试时不能重复提交表单里已有的订单号等业务字段。4. 踩坑实录五个最常见的翻车现场4.1 权限弹窗不出现这是最常见的问题没有之一。现象是点击拍照按钮没反应控制台也没有任何日志。排查路径我总结如下第一步检查module.json5里是否真的声明了ohos.permission.CAMERA。不要看文件名要看打包进产物里那份。第二步确认requestPermissionsFromUser是在用户点击拍照时调用而不是在 App 启动或者页面加载时就提前调了一遍。如果提前申请过即使返回了拒绝后续再调用可能不再弹窗。第三步检查上下文参数是否传入正确。requestPermissionsFromUser需要UIAbilityContext如果把普通的Context传了进去调用会静默失败。我当时踩的坑就是第二步——模块初始化时我把权限申请跑了一遍以为提前申请好能提升流畅度结果用户点击拍照时弹窗根本不出现后来查日志才发现权限请求已经返回了拒绝状态。4.2 uri 解析失败导致上传报错症状是拍照正常、预览正常一上传就失败。最初我还以为是网络问题后来打了个日志才发现asset.uri的值是datashare://media/image/photo/123直接塞进FormData后底层根本读不出文件流。解决办法就是我前面说的resolveUploadPath。这里提醒一下在桥接层把 URI 转换成文件路径时要用同步方式在小文件场景下减少回调地狱但如果文件较大还是用异步拷贝避免阻塞 UI 线程。4.3 includeBase64 引发内存峰值有些同学图省事把includeBase64设为true这样可以直接拿到图片的 Base64 字符串省去文件路径处理。千万别这么干。Base64 编码会让数据体积增加约 33%6MB 的图片变成 8MB 的字符串。更要命的是这个字符串还全量存在于 JS 堆内存里。RN 的 JS 引擎在鸿蒙设备上本来就受内存限制比较严格一张几 MB 的图片做 Base64 转换在那个瞬间就可能触发内存告警进而导致整个 App 被杀。我的铁律是includeBase64永远为false图片一律走文件路径上传。4.4 服务端收到的图片损坏或无法解码上传接口返回 200 了但服务端拿着文件打不开提示Invalid image file。原因基本都是type字段不匹配。比如图片明明是 PNG但上传代码里写死了image/jpeg或者文件名后缀与实际编码不一致。解决办法是上传前做一次统一校验function detectMimeType(fileName: string, rawType?: string): string { if (rawType) return rawType; const ext fileName.split(.).pop()?.toLowerCase() ?? jpg; const mimeMap: Recordstring, string { jpg: image/jpeg, jpeg: image/jpeg, png: image/png, gif: image/gif, webp: image/webp, }; return mimeMap[ext] ?? image/jpeg; }这个函数很小但帮我挡掉了至少三次线上问题。4.5 真机和模拟器行为差异鸿蒙模拟器的相册里面预置了几张示例图片拍照也是模拟的不会真正调用相机硬件。结果就是模拟器上一切正常一到真机就出问题。真实差异主要在三个地方一是真机照片带有 EXIF 旋转信息部分场景下预览方向是反的二是真机返回的 URI 格式和模拟器不完全一样模拟器可能统一返回file://真机却返回datashare://三是真机的拍照行为受相机硬件和厂商定制层影响可能出现极端分辨率。所以这个功能从第一天起就要保留一台真机做回归验证不能只依赖模拟器。5. 几点经验沉淀如果让我重新做一遍这个功能我会把精力更多地放在下面四个方面这些也是我做完整个项目的核心体会。第一桥接层要做得足够厚实。鸿蒙适配的诡异问题绝大多数都发生在原生层和 JS 层之间的缝隙里比如 URI 格式、权限上下文、文件读写。把这些通通收进桥接层用统一的接口暴露给 JS整个项目组后续维护成本会低很多。第二权限逻辑必须提前设计分支。用户拒绝授权不是异常而是常态。在大规模设备上一定会有用户拒绝、用户误触、用户后悔授权等各种情况。代码里把授权状态的分支都处理好比事后在线上看崩溃日志要省力得多。第三上传要内置进度反馈和重试。用户能感知到的只有图片发出去了没有。进度条提升的是安全感重试机制提升的是成功率两者加在一起才能把图片上传失败转变成图片上传重试中请稍候这种不那么刺眼的提示。第四多平台验证不要偷懒。我在 Android、iOS、鸿蒙三端同时跑同一套 JS 代码表面上代码是统一的但每端的原生实现细节并不一致。每个平台在拍照-上传这个链路里至少覆盖十次真机测试才敢说这个功能稳定。最后分享一个实用小技巧调试阶段可以在桥接层临时加一个__dumpImageInfo(rawUri)方法把原始 URI、归一化后的路径、文件大小、MIME 类型全部打印出来。这个 dump 逻辑在整个开发阶段帮了我大忙几乎每个上传失败的问题都能靠它快速定位到具体环节。等到功能稳定后再把这个方法移除或者用编译开关控制不会有什么性能影响。