简介这份资源面向Android与Cocos Creator开发者聚焦调用系统相机、相册选取图片、裁剪后上传与下载头像的完整实现覆盖权限动态申请、Intent启动相机与相册、onActivityResult回调、系统裁剪参数配置、Bitmap压缩存盘及OkHttp网络请求等关键环节适合需要搭建头像模块的中级开发者参考。压缩包共321个文件约5.12MB以json配置、rawproto与meta数据、js脚本、jar与aar依赖库为主辅以png图片、xml布局、gradle构建文件及少量java源码并附Demo-release.apk便于直接体验。已有2446人学习下载。资源将相机相册调用、裁剪、上传下载封装为AvatarManager式管理类读者可据此理清图片处理链路对照源码与依赖结构快速集成到自己的项目中。1. 从「点头像没反应」说起Creator 调相机相册到底卡在哪做 Creator 项目的人大多踩过同一个坑界面上摆了个头像框用户点下去安卓真机上要么毫无反应要么弹个权限框之后直接闪退日志里一行Permission denied或者Activity not found就没了下文。更麻烦的是就算把相机和相册拉起来了拿回来的图片动辄三四千像素、几 MB 大小直接塞进上传接口服务端要么超时要么拒收前端还得自己补一层裁剪和压缩。这套「调相机相册 → 裁剪 → 上传 → 回显下载」的链路看着是四个独立动作实际是一条必须一次走通的流水线任何一环参数没对齐整条链路就断。这篇笔记拆的就是这条流水线Creator 侧怎么通过原生桥接拉起安卓相机和相册、裁剪参数怎么设才不糊、上传前怎么压到合理体积、下载回显又该怎么处理缓存和路径。适合正在做用户头像、证件照、商品图上传这类功能的 Creator 开发者尤其是被真机权限和图片体积折腾过一轮的人。下面按「先立住原理、再给能抄的代码、最后说坑」的顺序走代码以 Creator 3.x 的 TypeScript 脚本加 Android 原生 Java 桥接为主线2.x 的写法差异会在对应位置点一句。2. 原生桥接的骨架Creator 侧脚本与 Android 侧接口怎么对接Creator 本身没有直接操作安卓相机硬件的 API所有「拉起系统相机/相册」的动作都得走原生层。常见做法是在 Creator 里用native.reflection.callStaticMethod调 Java 静态方法或者用jsb.reflection2.x 叫法反射调用原生侧则写一个带JavascriptInterface的桥接类或者干脆用静态方法接收参数、通过jsb回调把结果送回 JS。选静态方法反射的原因很直接不用额外注册 JSB 绑定改一行 Java 重新打包就能验证调试成本最低。2.1 为什么用静态方法反射而不是自定义 JSB自定义 JSB 绑定性能好、类型安全但要写jsb_module_register、改CMakeLists、重新编译整个引擎绑定层对一个「就调个相机」的需求来说太重。静态方法反射的代价是每次调用都走字符串匹配参数只能是基本类型和字符串返回也只能是基本类型——但相机相册这个场景恰好只需要传「请求码、裁剪宽高、输出路径」这几个值返回一个结果码或路径字符串就够了完全在反射的能力范围内。我一般会约定JS 传一个 JSON 字符串给 JavaJava 解析后执行结果再以 JSON 字符串回传这样参数扩展不用改方法签名。2.2 Creator 侧调用封装先看 JS 侧的封装。核心是把「拉起相机」「拉起相册」两个入口统一成一个函数用source区分避免两套代码各写一遍权限和回调逻辑。// ImageBridge.ts —— Creator 3.x 脚本挂在需要上传头像的节点上 import { native, sys } from cc; export interface PickOptions { source: camera | album; // 来源相机或相册 aspectX: number; // 裁剪框宽高比头像一般 1 aspectY: number; outputX: number; // 裁剪输出宽头像 400 足够 outputY: number; } export class ImageBridge { // 调原生静态方法类名必须是完整包名 类名 static pickImage(opts: PickOptions): Promisestring { return new Promise((resolve, reject) { if (!sys.isNative || sys.platform ! sys.Platform.ANDROID) { reject(new Error(only android supported)); return; } const payload JSON.stringify({ source: opts.source, aspectX: opts.aspectX, aspectY: opts.aspectY, outputX: opts.outputX, outputY: opts.outputY, // 输出到应用私有缓存目录避免外部存储权限 outPath: ${native.fileUtils.getWritablePath()}avatar_${Date.now()}.jpg, }); // 第三个参数是方法签名返回 String const ret native.reflection.callStaticMethod( com/example/game/ImagePicker, pick, (Ljava/lang/String;)Ljava/lang/String;, payload ); if (ret ret.startsWith(OK:)) { resolve(ret.substring(3)); // 去掉 OK: 前缀拿路径 } else { reject(new Error(ret || native returned null)); } }); } }这段代码有三个关键点。第一callStaticMethod的签名(Ljava/lang/String;)Ljava/lang/String;必须和 Java 方法签名严格一致少个分号、把String写成string都会静默返回 null这是反射调用最常见的翻车点。第二输出路径用native.fileUtils.getWritablePath()拿到的是应用私有目录写这里不需要申请存储权限能省掉一大截权限适配的麻烦。第三返回约定成OK:路径或ERR:原因JS 侧只做前缀判断错误信息原样透出排查时能直接看到原生侧抛了什么。2.3 Android 侧桥接类原生侧要做的事分四步解析参数、检查并申请权限、用Intent拉起相机或相册、在onActivityResult里做裁剪并把结果写回。下面这段是精简后的骨架重点看权限分支和裁剪 Intent 的组装。// ImagePicker.java —— 放在 android 工程对应包下 package com.example.game; import android.app.Activity; import android.content.Intent; import android.net.Uri; import android.provider.MediaStore; import androidx.core.content.FileProvider; import java.io.File; public class ImagePicker { private static Activity sActivity; private static String sOutPath; private static final int REQ_CAMERA 1001; private static final int REQ_ALBUM 1002; private static final int REQ_CROP 1003; // 由 Creator 启动时注入当前 Activity public static void init(Activity act) { sActivity act; } public static String pick(String json) { try { org.json.JSONObject o new org.json.JSONObject(json); sOutPath o.getString(outPath); String source o.getString(source); if (camera.equals(source)) { // 相机需要 CAMERA 权限且输出走 FileProvider Uri uri FileProvider.getUriForFile(sActivity, sActivity.getPackageName() .fileprovider, new File(sOutPath)); Intent i new Intent(MediaStore.ACTION_IMAGE_CAPTURE); i.putExtra(MediaStore.EXTRA_OUTPUT, uri); i.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION); sActivity.startActivityForResult(i, REQ_CAMERA); } else { Intent i new Intent(Intent.ACTION_PICK, MediaStore.Images.Media.EXTERNAL_CONTENT_URI); sActivity.startActivityForResult(i, REQ_ALBUM); } return OK:pending; // 异步结果通过回调回传 } catch (Exception e) { return ERR: e.getMessage(); } } }这里有个必须说清的设计取舍pick方法本身是同步返回的但相机和相册都是异步的真正的图片路径要等onActivityResult才拿得到。所以实际工程里pick返回OK:pending只是表示「已成功拉起」结果得靠另一条通道回传——常见做法是在onActivityResult里再反射调回 JS 的一个全局回调函数或者用jsb的dispatchEvent发事件。我一般选后者因为 Creator 侧监听事件比维护一个全局函数名更干净。裁剪那一步则是在onActivityResult收到相机/相册结果后再组一个com.android.camera.action.CROP的 Intent把aspectX/aspectY/outputX/outputY塞进 extra输出仍指向sOutPath这样裁剪完的图直接落在约定路径上JS 侧拿到路径就能上传。提示FileProvider的 authority 必须和AndroidManifest.xml里注册的 provider 一致且res/xml/file_paths.xml要覆盖输出目录否则相机写入时会抛IllegalArgumentException日志里只显示「Failed to find configured root」很容易误判成权限问题。3. 裁剪参数与图片体积outputX 设多少、压缩在哪一步做链路通了之后下一个现实问题是图片质量。系统裁剪的outputX/outputY设成 400 还是 800直接决定上传体积和头像清晰度而裁剪本身不做压缩一张 400×400 的 JPEG 仍可能上百 KB。这一章把裁剪参数、压缩时机、上传格式三件事拆开说。3.1 裁剪 Intent 的参数边界安卓系统裁剪com.android.camera.action.CROP不是标准 API各家 ROM 实现有差异但几个核心 extra 是通用的aspectX/aspectY控制裁剪框比例outputX/outputY控制输出像素return-data决定是否把 Bitmap 直接塞回 Intent。这里有个血泪经验return-data设成true时大图会触发TransactionTooLargeException因为 Bitmap 走 Binder 传输有大小上限一般 1MB 左右。所以正确做法是return-data设false只传output的 Uri让裁剪结果直接写文件。参数建议值说明aspectX / aspectY1 / 1头像固定正方形比例不对裁剪框会变形outputX / outputY400 / 400头像展示够用再大上传体积翻倍收益很低return-datafalse避免 Binder 传输大 Bitmap 崩溃outputFileProvider Uri裁剪结果直接落盘JS 侧读路径noFaceDetectiontrue部分 ROM 人脸检测会额外弹框关掉更稳outputX设 400 的依据是头像在列表里通常显示 80120dp按 3 倍屏算也就 360px400 留了一点余量如果业务要求点开大图看细节可以提到 800但要在上传前再压一次。aspectX/aspectY和outputX/outputY的比例最好保持一致不一致时部分 ROM 会以output为准强行拉伸裁出来的人脸是扁的。3.2 上传前的二次压缩裁剪只保证尺寸不保证体积。一张 400×400 的 JPEG 在质量 100 时约 80150KB质量 80 时能降到 3050KB肉眼几乎看不出差别。压缩放在哪一步做有讲究放 JS 侧用 Canvas 重绘再toDataURL会多一次解码编码低端机上明显卡顿放原生侧用Bitmap.compress更直接。我一般在上传前于原生侧补一个压缩方法JS 传目标质量和最大边长原生读文件、按需缩放、重写文件。// 在 ImagePicker 里补一个压缩方法JS 上传前调用 public static String compress(String path, int maxSide, int quality) { try { android.graphics.BitmapFactory.Options opt new android.graphics.BitmapFactory.Options(); opt.inJustDecodeBounds true; android.graphics.BitmapFactory.decodeFile(path, opt); int sample 1; while (Math.max(opt.outWidth, opt.outHeight) / sample maxSide) { sample * 2; // 2 的幂次采样解码阶段就降分辨率省内存 } opt.inJustDecodeBounds false; opt.inSampleSize sample; android.graphics.Bitmap bmp android.graphics.BitmapFactory.decodeFile(path, opt); java.io.FileOutputStream fos new java.io.FileOutputStream(path); bmp.compress(android.graphics.Bitmap.CompressFormat.JPEG, quality, fos); fos.close(); bmp.recycle(); return OK: path; } catch (Exception e) { return ERR: e.getMessage(); } }inSampleSize用 2 的幂次是有原因的安卓解码器对非 2 的幂次采样会向下取整到最近的 2 的幂传 3 和传 2 效果一样不如自己算准。maxSide传 800、quality传 80 是我常用的组合400 的头像其实maxSide传 400 就够但留到 800 是为了兼容后续可能的高清展示。压缩完直接覆盖原文件省得管理两份路径。3.3 上传与下载回显上传走 Creator 的assetManager或XMLHttpRequest都行关键是FormData里文件名带.jpg后缀、Content-Type设image/jpeg服务端才认。下载回显则要注意缓存同一个 URL 换了图客户端可能还读旧缓存常见做法是 URL 后拼时间戳或版本号。Creator 里加载网络图用assetManager.loadRemote加载完记得在合适时机releaseAsset否则反复换头像会累积纹理内存。// 上传 回显的串联写法 async function uploadAvatar(localPath: string) { const form new FormData(); // 原生路径转 BlobCreator 里可用 fileUtils 读成 ArrayBuffer const data native.fileUtils.getDataFromFile(localPath); form.append(file, new Blob([data], { type: image/jpeg }), avatar.jpg); const resp await fetch(https://your.api/upload, { method: POST, body: form }); const { url } await resp.json(); // 回显时拼时间戳破缓存 return ${url}?t${Date.now()}; }getDataFromFile返回的是ArrayBuffer包成Blob时显式指定image/jpeg服务端拿到的 MIME 才正确。回显 URL 拼t参数是成本最低的破缓存手段比让服务端配Cache-Control快得多适合头像这种低频但要求即时生效的场景。4. 真机上的四类翻车权限、FileProvider、ROM 差异与内存这条链路在模拟器上跑通不代表真机能用下面四条是我在不同机型上反复遇到的按「现象 → 原因 → 解决」记下来照着排查能省不少时间。4.1 相机拉起后黑屏或直接返回现象点拍照相机界面闪一下就回来onActivityResult的resultCode是RESULT_CANCELED日志无异常。原因多半是EXTRA_OUTPUT的 Uri 没给写权限相机应用写不进去就主动取消。解决Intent上加FLAG_GRANT_WRITE_URI_PERMISSION同时确认FileProvider的file_paths.xml里cache-path或files-path覆盖了输出目录。还有一种情况是CAMERA权限没在运行时申请安卓 6.0 以上直接拉起会被系统拦表现为同样的静默取消所以拉起前必须先checkSelfPermission没有就requestPermissions在回调里再走拉起逻辑。4.2 FileProvider 报「Failed to find configured root」现象相机能拉起但一拍照就崩日志里IllegalArgumentException: Failed to find configured root that contains /data/user/0/...。原因是file_paths.xml里配的路径和实际输出路径对不上比如只配了external-path却往私有目录写。解决输出路径统一用getWritablePath()对应的私有目录file_paths.xml里配files-path nameinternal path. /或cache-path两者对齐即可。改完记得清一次构建缓存res/xml的改动有时不会热更。4.3 部分 ROM 裁剪后图片被旋转 90 度现象相机拍完裁剪头像躺倒了相册选的图却正常。原因是相机写入的 JPEG 带 EXIF 旋转标记系统裁剪在某些 ROM 上不读 EXIF直接按原始像素裁结果方向错。解决在原生侧读一次 EXIF 的TAG_ORIENTATION按角度对 Bitmap 做Matrix旋转后再压缩写回。这一步放在压缩方法里做最合适反正都要解码一次顺手把方向摆正。4.4 连续换头像后纹理内存上涨现象反复上传、回显跑十几轮后低端机开始掉帧甚至闪退。原因是loadRemote加载的远程图没释放纹理一直挂在assetManager上。解决每次换头像前对上一张releaseAsset或者用SpriteFrame的引用计数管理确保旧图不再被引用。另外压缩时bmp.recycle()别漏原生侧 Bitmap 不回收Java 堆和 native 内存都会涨。注意权限申请的回调是异步的requestPermissions之后不能假设立刻有结果拉起相机的代码必须放在onRequestPermissionsResult里否则第一次点拍照必然失败、第二次才成功这种「第一次不行第二次行」的现象八成就是权限时序问题。5. 把链路收成可复用组件一次封装、三处校验走到这里功能是通了但散在 JS 和 Java 两边的逻辑下次换个项目还得重抄一遍。我的习惯是把它收成一个AvatarPicker组件对外只暴露pickAndUpload()一个方法内部串起「权限检查 → 拉起 → 裁剪 → 压缩 → 上传 → 回显」调用方拿到的直接是最终 URL。收口的时候有三处校验值得固定下来能挡掉大部分线上问题。第一处是入口校验pickAndUpload开头先判断平台和权限状态非安卓或权限被永久拒绝时直接走降级分支比如提示去设置页手动开不要让用户点了没反应。第二处是产物校验原生返回路径后JS 侧用fileUtils.getFileSize确认文件存在且大于 0避免拿到一个空文件还往上送。第三处是上传后校验服务端返回的 URL 先做一次loadRemote预加载加载失败就重试一次成功再替换头像避免界面上出现裂图。// 收口后的对外方法三处校验都在里面 async function pickAndUpload(source: camera | album): Promisestring { if (!sys.isNative || sys.platform ! sys.Platform.ANDROID) { throw new Error(unsupported platform); } const path await ImageBridge.pickImage({ source, aspectX: 1, aspectY: 1, outputX: 400, outputY: 400, }); // 校验一产物存在且非空 if (!path || native.fileUtils.getFileSize(path) 0) { throw new Error(empty output); } // 校验二压缩后再传 native.reflection.callStaticMethod(com/example/game/ImagePicker, compress, (Ljava/lang/String;II)Ljava/lang/String;, path, 800, 80); const url await uploadAvatar(path); // 校验三预加载成功才返回 await new Promisevoid((resolve, reject) { assetManager.loadRemote(url, (err, asset) err ? reject(err) : resolve()); }); return url; }这套收口的好处是调用方只有一行await pickAndUpload(camera)所有平台差异、权限时序、体积控制都封在组件里换项目时把ImagePicker.java和这个 TS 文件一起拷过去改一下包名和上传地址就能用。参数上唯一需要按业务调的是outputX/outputY和压缩的maxSide/quality头像场景 400/800/80 这套组合我用了几个项目都没出过问题如果业务是商品图需要更高清把outputX提到 1024、quality提到 90同时确认服务端的上传大小限制跟得上。从那以后我每次接这类「调原生硬件 上传」的需求都会先把权限时序和 FileProvider 配置在真机上单独验一遍再往上叠裁剪和压缩——这两步不先钉死后面所有调试都会被「到底是权限问题还是路径问题」搅成一锅粥。希望这套拆法帮到你少走几趟真机反复打包的弯路。本文还有配套的精品资源点击获取
