Cocos Creator 安卓相机相册调用全链路：权限、EXIF、压缩与上传避坑指南

简介：这份资源面向Android与Cocos Creator开发者，聚焦调用系统相机、相册选取图片、裁剪后上传与下载头像的完整实现，覆盖运行时权限申请、Intent启动相机与相册、onActivityResult回调接收、系统裁剪工具参数配置、Bitmap压缩存盘及OkHttp网络上传下载等关键环节，适合需要落地头像模块的中级开发者参考。压缩包共321个文件，约5.12MB，以json配置与rawproto数据文件为主，辅以js脚本、jar与aar依赖库、png图片资源及少量java源码、xml布局与gradle构建文件，另含一个可运行的Demo安装包，便于对照调试。该资源已有2446人学习下载。读者可从中获得从权限声明到图片裁剪、本地保存再到服务端上传下载的完整链路代码，以及AvatarManager式的流程封装思路，帮助快速搭建稳定可靠的图片处理模块并排查常见兼容性问题。

1. 从一次头像上传翻车说起：creator 调相机相册到底难在哪

去年帮一个做社交 Demo 的团队收尾，功能清单里写着「点头像换图」，看着像半小时的活，结果卡了整整两天。第一版在模拟器上跑得好好的，真机一测，安卓 13 上点「拍照」直接闪退；换成「从相册选」，图片回来了但方向是横的；好不容易把图传上去，服务端收到的是一张 8MB 的原图，列表页加载直接卡成幻灯片。这三个问题分别对应 creator 调安卓相机相册这条链路上的三个关键节点：权限与回调、EXIF 方向、压缩与上传。这篇笔记就把这条链路拆开讲清楚——creator 侧怎么发起调用、安卓原生侧怎么接、裁剪怎么做、上传下载怎么收尾，适合正在做头像/证件照/商品图上传的移动端开发者，也适合被真机兼容性折磨过的熟手对照排查。

2. 调用链路拆解：creator 与安卓原生的桥怎么搭

creator 本身不直接操作相机硬件，它走的是引擎封装的桥接层。理解这层桥的边界，后面所有坑才有解释。

2.1 为什么不能只用 cc.sys 那套接口

creator 提供了cc.sys和部分平台 API，但相机、相册、裁剪这类能力在安卓上并没有统一封装。常见做法是走两条路：一是用引擎的jsb.reflection.callStaticMethod直接调 Java 静态方法，二是写一个原生扩展模块（Android 侧继承Cocos2dxActivity或通过JavaScriptProxy注册）。前者上手快、代码少，适合 Demo 和中小项目；后者结构清晰、能持有 Activity 引用、方便处理onActivityResult，适合要长期维护的产品。

我一般这样选：如果只是「拍一张、选一张、传上去」，用反射调静态方法足够；如果还要裁剪、要多图、要处理生命周期，老老实实写原生模块。原因很直接——startActivityForResult的回调必须落在 Activity 上，反射调静态方法拿不到稳定的 Activity 上下文，真机上偶发空指针就是这么来的。

2.2 安卓侧的最小骨架

先在原生工程里建一个工具类，负责拉起相机和相册，并把结果通过onActivityResult回传给 creator。下面是最小可用版本，省略了包名和 import：

public class MediaBridge { public static final int REQ_CAMERA = 1001; public static final int REQ_ALBUM = 1002; private static Activity sActivity; private static String sCallbackId; // creator 侧通过反射调用，传入 Activity 和回调标识 public static void init(Activity activity) { sActivity = activity; } public static void openCamera(String callbackId) { sCallbackId = callbackId; Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE); // 指定输出路径，避免拿到缩略图 Uri outputUri = FileProvider.getUriForFile( sActivity, sActivity.getPackageName() + ".fileprovider", createTempFile()); intent.putExtra(MediaStore.EXTRA_OUTPUT, outputUri); intent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION); sActivity.startActivityForResult(intent, REQ_CAMERA); } public static void openAlbum(String callbackId) { sCallbackId = callbackId; Intent intent = new Intent(Intent.ACTION_PICK, MediaStore.Images.Media.EXTERNAL_CONTENT_URI); intent.setType("image/*"); sActivity.startActivityForResult(intent, REQ_ALBUM); } }

这段代码有三个关键点。第一，EXTRA_OUTPUT必须给，否则部分机型只返回一张几十 KB 的缩略图，用户以为拍成功了，实际糊得没法用。第二，FileProvider是安卓 7.0 之后的硬要求，直接传file://会抛FileUriExposedException，这是真机闪退的高频原因。第三，callbackId用来在回调时定位 creator 侧的回调函数，多实例场景下不能省。

2.3 creator 侧发起调用与回调注册

creator 侧用反射拉起原生方法，同时把回调函数挂到全局对象上，供原生侧回传时查找：

// 发起拍照 function takePhoto() { if (cc.sys.os !== cc.sys.OS_ANDROID) return; // 回调函数挂到 window 上，原生侧按名字查找 window.__onMediaResult = function (code, path) { if (code === 0) { console.log('拿到图片路径', path); uploadAvatar(path); } else { console.warn('用户取消或失败', code); } }; jsb.reflection.callStaticMethod( 'com/demo/MediaBridge', 'openCamera', '(Ljava/lang/String;)V', '__onMediaResult' ); }

callStaticMethod的签名串(Ljava/lang/String;)V必须和 Java 方法签名严格对应，参数类型写错不会报编译错误，只会在运行时静默失败，这是排查时最容易被忽略的一处。回调函数挂在window上而不是模块作用域里，是因为原生侧通过Cocos2dxJavascriptJavaBridge.evalString执行 JS 时，只能访问全局作用域。

2.4 权限申请放在哪一层

安卓 6.0 之后相机和存储权限都是运行时权限。常见做法是在原生侧openCamera之前先检查并申请，申请结果在onRequestPermissionsResult里再决定是否继续拉起 Intent。不要在 creator 侧申请，creator 没有直接申请安卓运行时权限的接口，绕一圈反而更乱。权限被拒后要给用户一个明确提示，而不是静默返回，否则用户会以为按钮坏了。

3. 裁剪与方向：图片回来之后的三道关

图片拿到手只是开始，真正决定成败的是方向、尺寸和格式这三道关。

3.1 EXIF 方向：为什么图是横的

手机拍照时传感器方向是固定的，系统把旋转信息写进 EXIF 的Orientation字段，而不是真的旋转像素。creator 加载图片时通常不读 EXIF，于是竖着拍的照片显示成横的。解决办法是在原生侧读取 EXIF 并做实际旋转，再回传给 creator：

public static Bitmap fixOrientation(String path) throws IOException { Bitmap bitmap = BitmapFactory.decodeFile(path); ExifInterface exif = new ExifInterface(path); int orientation = exif.getAttributeInt( ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL); Matrix matrix = new Matrix(); switch (orientation) { case ExifInterface.ORIENTATION_ROTATE_90: matrix.postRotate(90); break; case ExifInterface.ORIENTATION_ROTATE_180: matrix.postRotate(180); break; case ExifInterface.ORIENTATION_ROTATE_270: matrix.postRotate(270); break; default: return bitmap; } return Bitmap.createBitmap(bitmap, 0, 0, bitmap.getWidth(), bitmap.getHeight(), matrix, true); }

ExifInterface在安卓 7.0 前后包名不同，老版本在android.media下，新版本在androidx.exifinterface下，混用会编译不过。旋转之后记得回收原 Bitmap，否则连续拍几张就有 OOM 风险。

3.2 裁剪：系统裁剪还是自己裁

系统裁剪用com.android.camera.action.CROP，代码短，但兼容性差——部分机型没有这个 Intent，部分机型裁剪后返回的尺寸不受控。自己裁则用 creator 侧的遮罩加触摸拖拽，或者原生侧用 Canvas 画。我的经验是：头像这种固定比例（1:1）的场景，自己裁更可控，因为你能精确控制输出尺寸和压缩质量；需要自由裁剪的场景再用系统裁剪，并在resolveActivity为空时降级到不裁剪。

自己裁的核心是把裁剪框的坐标换算成原图坐标，再调用Bitmap.createBitmap截取。注意坐标要按原图尺寸缩放，不能直接用屏幕坐标，否则高分辨率机型上裁出来的区域会偏。

3.3 压缩：上传前的最后一道闸

原图动辄 5～10MB，直接上传既慢又费流量。压缩分两步：先按目标尺寸缩放，再按质量压缩。头像场景一般输出 512×512 或 800×800，质量 80 左右肉眼几乎无损：

public static String compress(String srcPath, String dstPath, int maxSize, int quality) throws IOException { Bitmap bitmap = fixOrientation(srcPath); int w = bitmap.getWidth(), h = bitmap.getHeight(); float scale = Math.min((float) maxSize / w, (float) maxSize / h); if (scale < 1f) { bitmap = Bitmap.createScaledBitmap(bitmap, Math.round(w * scale), Math.round(h * scale), true); } FileOutputStream fos = new FileOutputStream(dstPath); // JPEG 不支持透明，头像场景够用 bitmap.compress(Bitmap.CompressFormat.JPEG, quality, fos); fos.close(); bitmap.recycle(); return dstPath; }

参数上，maxSize决定长边上限，quality决定压缩比。质量低于 60 时文字边缘会出现明显锯齿，头像场景不建议再低。压缩后的文件路径要回传给 creator，而不是回传 Bitmap 对象——跨语言传大对象既慢又容易出问题。

4. 上传与下载：把文件流走通

图片处理完，剩下的是传输。这一步的坑不在协议本身，而在路径、格式和失败重试。

4.1 上传：multipart 表单的字段约定

服务端一般要求multipart/form-data，字段名要和后端对齐。creator 侧用XMLHttpRequest发FormData即可，但要注意原生侧回传的是文件路径，creator 不能直接把路径塞进 FormData，需要先读成二进制。常见做法是原生侧把文件读成 base64 回传，creator 转成 Blob 再上传：

function uploadAvatar(filePath) { // 原生侧提供 readAsBase64 方法，返回纯 base64 字符串 const b64 = jsb.reflection.callStaticMethod( 'com/demo/MediaBridge', 'readAsBase64', '(Ljava/lang/String;)Ljava/lang/String;', filePath); const bytes = atob(b64); const arr = new Uint8Array(bytes.length); for (let i = 0; i < bytes.length; i++) arr[i] = bytes.charCodeAt(i); const blob = new Blob([arr], { type: 'image/jpeg' }); const form = new FormData(); form.append('avatar', blob, 'avatar.jpg'); const xhr = new XMLHttpRequest(); xhr.open('POST', 'https://your-host/api/avatar'); xhr.onload = () => { if (xhr.status === 200) { const res = JSON.parse(xhr.responseText); downloadAvatar(res.url); // 服务端返回正式地址 } }; xhr.onerror = () => console.warn('上传失败，待重试'); xhr.send(form); }

base64 会让数据膨胀约三分之一，所以只适合压缩后的小图。如果图片超过 1MB，更稳的做法是原生侧直接用OkHttp上传，creator 只负责拿结果。字段名avatar必须和后端约定一致，改名前先确认，否则服务端收不到文件却返回 200，排查起来很费时间。

4.2 下载：缓存与覆盖策略

头像下载的典型问题是缓存。同一个 URL 换了图，客户端还显示旧的。解决办法是在 URL 后拼版本号或时间戳，或者下载时带Cache-Control: no-cache。creator 侧用cc.assetManager.loadRemote加载网络图时，引擎内部有缓存机制，覆盖同名资源要显式释放：

function downloadAvatar(url) { // 拼时间戳绕过缓存，服务端需允许该参数 const realUrl = url + '?t=' + Date.now(); cc.assetManager.loadRemote(realUrl, { ext: '.jpg' }, (err, texture) => { if (err) { console.warn('下载失败', err); return; } // 先释放旧纹理，避免显存泄漏 if (window.__avatarTex) window.__avatarTex.destroy(); window.__avatarTex = texture; avatarSprite.spriteFrame = new cc.SpriteFrame(texture); }); }

ext参数不能省，远程 URL 没有扩展名时引擎无法判断解码格式。旧纹理不释放，反复换头像会持续占用显存，低端机上表现为越用越卡。

4.3 失败重试与超时

移动网络下上传失败是常态，不是异常。给上传加一个简单的重试：失败后延迟 2 秒重试，最多三次，仍失败则提示用户。超时时间设 15～30 秒，太短会在弱网下误判，太长会让用户干等。重试时不要重复压缩，复用已压缩的文件即可。

5. 避坑清单：真机上最容易翻车的五个点

5.1 拍照返回缩略图

现象：拍照后上传的图只有几十 KB，放大全是马赛克。原因：ACTION_IMAGE_CAPTURE没传EXTRA_OUTPUT，系统默认只回传缩略图。解决：按 2.2 的方式指定输出 Uri，并确保FileProvider配置了对应路径。

5.2 安卓 13 上相册选图无响应

现象：点「从相册选」没反应，日志无报错。原因：安卓 13 收紧了媒体权限，READ_EXTERNAL_STORAGE在部分场景下不再生效，需要用READ_MEDIA_IMAGES。解决：按系统版本分支申请权限，13 及以上申请READ_MEDIA_IMAGES，以下申请READ_EXTERNAL_STORAGE。

5.3 回调函数找不到

现象：原生侧执行evalString时报undefined is not a function。原因：回调函数挂在模块作用域，原生侧全局查找不到。解决：统一挂到window上，并在调用前确认已赋值；回调执行完后可以置空，避免重复触发。

5.4 图片方向错乱

现象：竖拍的照片显示成横的，或者裁剪区域偏移。原因：没处理 EXIF 方向，或者裁剪坐标没按原图尺寸换算。解决：先按 3.1 做实际旋转，再做裁剪和缩放，顺序不能反。

5.5 上传成功但服务端收不到文件

现象：接口返回 200，但服务端说没收到文件。原因：FormData字段名和后端不一致，或者Content-Type被手动设置成了application/json。解决：字段名对齐后端文档，Content-Type交给浏览器自动生成，不要手动覆盖。

6. 进阶：把整条链路收成一个可复用的上传组件

链路跑通之后，下一步是把它收成一个组件，避免每个页面重复写。我的做法是封装一个AvatarUploader，对外只暴露pickFromCamera()、pickFromAlbum()、upload()三个方法，内部把权限、方向、压缩、重试全部吃掉。关键是把状态机理清楚：空闲 → 选择中 → 已选待上传 → 上传中 → 成功/失败，每个状态只允许特定操作，避免用户连点导致重复上传。

验证环节我一般分三层走。第一层是模拟器跑通主流程，确认回调能回来；第二层是真机覆盖三个版本（低版本、中间版本、最新版本），重点看权限和FileProvider；第三层是弱网模拟，用限速工具把上行压到 100KB/s，看重试和超时是否符合预期。下面这张表是我常用的自检清单：

还有一个容易被忽略的点：组件要处理页面切后台再回来的情况。拍照时应用可能被系统回收，回来时 creator 场景已重建，回调函数丢失。稳妥做法是在原生侧把结果暂存到文件或静态变量，creator 启动时主动查询一次「有没有待处理的结果」，而不是只依赖回调。这个兜底逻辑平时用不上，一旦用上就是救命的那种。

从那以后我每次接这类需求，都强制先把权限矩阵和版本分支列成表再动手，宁可前期多花半小时，也不在真机上反复试错。希望帮到你。

本文还有配套的精品资源，点击获取