简介面向安卓开发者的相机相册集成资料聚焦 Cocos Creator 与安卓原生混合开发中的头像上传下载场景。内容完整覆盖运行时权限申请包括清单声明与动态请求处理、以系统意图启动相机与相册、调用系统裁剪工具并设置宽高比例与输出尺寸、位图压缩与本地存储、使用网络请求库构建多部分表单上传、依据返回地址发起下载并保存文件同时给出统一管理类封装便于直接复用到个人资料页或用户头像模块。压缩包共三百二十一个文件大小约五点一二兆字节主要包含配置数据文件、Java 与 TypeScript 逻辑源码、第三方依赖库、界面布局与图片资源、构建脚本等类型覆盖从权限清单到网络请求的完整实现要点内含可直接安装运行的演示程序可对照源码分析调用流程、裁剪参数配置和上传下载封装方式。目前已有2445人学习下载适合具备基础安卓开发经验、希望快速实现相册相机选图与头像上传下载能力的开发者参考。1. 为什么说 creator 调用相机相册是“半原生”工程做 Cocos Creator 项目时很多开发者以为调起相机、选张相册图、裁个图再传服务器是“前端三五行代码的事”。真动手才发现采集端的坑一个接一个Android 版本不同导致 Intent 返回路径不一致、裁剪框尺寸不对导致上传后头像拉伸、临时文件权限没处理导致 IPC 崩溃。这些问题的根源在于Cocos Creator 引擎本身不提供相机与相册能力我们实际上是在 JavaScript 层通过 JSBJavaScript Binding调用 Android 原生 Java 代码再由原生层拼装 Intent 拉起系统应用。换句话说这是半个原生工程不是纯 JS 工程。这套方案的价值在于它把 Android 原生代码封装成一个 JS 可调用的桥接模块creator 里只需一行native.callCamera()就能进入系统相机拿到返回的图片路径后统一走裁剪、压缩、上传、下载流程。适合做带头像上传的社交类、工具类、直播互动类项目也适合需要“拍照即上传”的业务场景。全文我会先拆桥接原理再逐个击破相机相册调用、裁剪参数、上传下载实现最后给出四个高频踩坑点和一套验证方法。2. 桥接层设计JS 与 Android 原生双向通信2.1 JSB 绑定方式选型手动绑定与反射调用creator 项目接入 Android 原生常见做法有三种官方扩展插件、手动 JSB 绑定、反射调用。插件方式适合团队里有 Android 原生开发者、需要复用原生模块的场景手动 JSB 绑定适合需要高频调用的场景性能和类型安全都更好反射调用则适合快速验证原型、不想动工程构建配置的场景。我一般推荐小团队用反射调用起步。维护成本低creator 工程打 Android 包时无需额外编写 JNI 层代码量集中在 JavaScript 与 Java 两个文件里。核心思路是通过importClass导入 Java 类用new关键字实例化原生对象再直接调用其公共方法。这种方式在 Cocos Creator 2.x 的 Android 构建产物中运行稳定3.x 版本也保持兼容。反射调用的边界在于只能调用公共方法、无法处理需要继承或回调接口的复杂场景。但在相机相册这个场景里我们只需要“打开 Intent → 等待 Activity 结果 → 返回数据”天然适合反射调用。2.2 桥接模块的 Java 侧骨架先写 Java 侧的核心模块。新建一个CameraBridge.java对外暴露两个方法openCamera()和openAlbum()以及一个静态的onActivityResult处理入口。public class CameraBridge { private static Activity currentActivity; private static String pendingCallback; public static void init(Activity activity) { currentActivity activity; } public static void openCamera() { Intent intent new Intent(MediaStore.ACTION_IMAGE_CAPTURE); Uri fileUri createImageUri(); intent.putExtra(MediaStore.EXTRA_OUTPUT, fileUri); currentActivity.startActivityForResult(intent, REQUEST_CAMERA); } public static void openAlbum() { Intent intent new Intent(Intent.ACTION_PICK, MediaStore.Images.Media.EXTERNAL_CONTENT_URI); currentActivity.startActivityForResult(intent, REQUEST_ALBUM); } private static Uri createImageUri() { File dir new File(currentActivity.getExternalFilesDir(null), camera_cache); if (!dir.exists()) dir.mkdirs(); File image new File(dir, pending_avatar_ System.currentTimeMillis() .jpg); return FileProvider.getUriForFile(currentActivity, currentActivity.getPackageName() .fileprovider, image); } }这段代码用MediaStore.ACTION_IMAGE_CAPTURE拉起系统相机用ACTION_PICK拉起相册。注意createImageUri()里用了FileProvider这是因为 Android 7.0 之后不允许直接暴露file://协议给其他应用必须通过FileProvider生成content://URI否则相机一启动就抛FileUriExposedException。参数说明EXTRA_OUTPUT指定相机照片写入的路径不设置的话系统只返回缩略图REQUEST_CAMERA和REQUEST_ALBUM是两个请求码常量用于在onActivityResult里区分来源getExternalFilesDir指向应用专属外部存储目录卸载后不会残留垃圾。2.3 JS 侧封装与回调机制Java 侧没有 JS 回调能力需要 JS 侧轮询或者通过事件机制获取结果。我用的是一个简单的方案Java 侧在处理完结果后把结果路径写入静态字段JS 侧通过定时轮询获取。const CameraBridge { _pollTimer: null, _lastResult: null, callCamera() { const bridge importClass(com.example.camera.CameraBridge); bridge.openCamera(); this._startPolling(); }, callAlbum() { const bridge importClass(com.example.camera.CameraBridge); bridge.openAlbum(); this._startPolling(); }, _startPolling() { if (this._pollTimer) return; const bridge importClass(com.example.camera.CameraBridge); this._pollTimer setInterval(() { const result bridge.getResult(); if (result result ! ) { this._lastResult result; this._stopPolling(); this._onCallback(result); } }, 300); }, _stopPolling() { clearInterval(this._pollTimer); this._pollTimer null; }, _onCallback(path) { console.log(获取到图片路径:, path); } };这段轮询逻辑每隔 300 毫秒检查一次 Java 侧的结果字段。如果用户取消了拍照getResult()返回空字符串超时后自动停止轮询。参数_pollTimer是用作防止重复创建定时器的标识_lastResult保存最近一次结果方便后续上传失败重试复用。轮询方案虽然不够优雅但在 creator 的 JS 环境下实现起来最快不需要额外写原生回调接口。如果后续要处理连续拍照、多图选择再改成原生回调接口也不迟。3. 调起相机与相册Intent 选择、临时文件与内存黑匣子3.1 系统相机行为差异与适配不同厂商 ROM 对系统相机的处理差异很大。ACTION_IMAGE_CAPTURE返回时标准做法是从onActivityResult的data.getData()拿 URI但实际上部分 ROM 这个字段为 null真正有效的图片地址是我们之前传入EXTRA_OUTPUT的那个 URI。所以我在代码里优先读取fileUri路径只有当fileUri为空时才回退到data.getData()解析。拍摄后的图片是原图分辨率动辄 4000×3000直接上传非常浪费流量而且部分服务器对图片大小有限制。常见的做法是拿到路径后先做一个压缩把最长边限制到 1280 或 1920质量压到 80%。这个压缩步骤放在裁剪之前还是之后取决于业务场景先裁剪后压缩能省去大图解码的内存峰值先压缩后裁剪则能保证裁剪时有足够的像素信息。我在这个项目里采用的顺序是拿到原图路径 → 先按最长边 1920 压缩 → 再进裁剪流程 → 最后按上传要求做二次压缩。3.2 相册选择与 ContentResolver 解析从相册选图时返回的是一个content://URI需要跨进程读取图片数据。这里有个关键点相册图片可能是 HEIC 格式iPhone 导出后传到 Android 的情况也可能带有 EXIF 旋转信息。忽略 EXIF 会导致上传到服务器后图片方向不对——在手机本地看是正的服务端看图却是横的。protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (resultCode ! Activity.RESULT_OK) return; String sourcePath; if (requestCode REQUEST_CAMERA) { sourcePath mCameraImagePath; } else { sourcePath resolveContentUri(data.getData()); } String rotatedPath ImageOrientationCorrector.correct(sourcePath); String compressedPath ImageCompressor.compress(rotatedPath, 1920, 80); processResult(compressedPath); }resolveContentUri内部通过ContentResolver打开输入流先写入应用缓存目录的临时文件再读取MediaStore.Images.Media.ORIENTATION字段做旋转校正。参数1920是压缩后最长边像素值80是 JPEG 压缩质量百分比这两个值要按服务器能力和业务需求调不是固定不变的。如果服务器支持 WebP 格式可以把压缩器换成 WebP 编码体积能再小 30%。3.3 内存峰值控制大图解码的血泪教训6000×4000 的图片解码成 Bitmap 后占用的内存约 96MB6000×4000×4 字节。如果不做采样压缩直接进裁剪界面低端机尤其容易 OOM。常见做法是先用BitmapFactory.Options.inJustDecodeBoundstrue读一遍宽高再计算采样率inSampleSize最后才真正解码。BitmapFactory.Options options new BitmapFactory.Options(); options.inJustDecodeBounds true; BitmapFactory.decodeFile(path, options); int sampleSize calculateInSampleSize(options.outWidth, options.outHeight, 1920); options.inJustDecodeBounds false; options.inSampleSize sampleSize; Bitmap bitmap BitmapFactory.decodeFile(path, options);calculateInSampleSize的逻辑是如果原始宽高中较大者的 1/2 仍然大于目标值就把采样率翻倍循环直到小于目标值。inSampleSize是 2 的幂次倍时解码效率最高非 2 的幂次倍也能工作但会退化为逐像素采样性能较差。还有一个细节解码前记得设置options.inPreferredConfig Bitmap.Config.RGB_565能把单像素内存占用从 4 字节降到 2 字节对不需要透明通道的 JPEG 图完全够用。4. 裁剪逻辑系统裁剪框与尺寸参数的设置4.1 调起系统裁剪 ActivityAndroid 系统自带的裁剪功能通过com.android.camera.action.CROP拉起。它会弹出一个带网格线的裁剪框用户拖动确定保留区域返回裁剪结果。这个方案最省事但裁剪框的宽高比需要在intent.putExtra(aspectX, 1); intent.putExtra(aspectY, 1)里指定否则部分 ROM 会使用默认的方形裁剪框。Intent cropIntent new Intent(com.android.camera.action.CROP); cropIntent.setDataAndType(sourceUri, image/*); cropIntent.putExtra(crop, true); cropIntent.putExtra(aspectX, 1); cropIntent.putExtra(aspectY, 1); cropIntent.putExtra(outputX, 512); cropIntent.putExtra(outputY, 512); cropIntent.putExtra(return-data, true); currentActivity.startActivityForResult(cropIntent, REQUEST_CROP);参数aspectX1, aspectY1表示裁剪框锁定为正方形适合做头像。outputX512, outputY512是输出尺寸这里写的是像素值。如果业务需要长方形头图比如个人主页横幅就改成aspectX16, aspectY9输出尺寸对应改为 1280×720。return-datatrue会让裁剪结果以 Bitmap 形式直接放进 Intent 返回但这种方式在图片稍大时非常容易导致 Binder 缓冲区溢出实际开发中我一般会改成return-datafalse让裁剪结果写入指定 URI。4.2 结果回调与 Bitmap 回收当return-datafalse时裁剪结果是一个content://URI需要自己解析成文件路径。这个路径指向的是一个临时文件如果不及时拷贝到应用目录下回收站清理或其他应用访问时可能被删除造成上传时文件丢失。if (requestCode REQUEST_CROP resultCode Activity.RESULT_OK) { String croppedPath resolveContentUri(data.getData()); String finalPath moveToAppDirectory(croppedPath, avatar_512.jpg); CameraBridge.setResult(finalPath); }moveToAppDirectory先把裁剪结果从临时目录复制到filesDir/avatar下再删除临时文件。复制操作要注意用FileOutputStream逐块写不要用File.renameTo()——因为它跨目录移动时在不同文件系统上会失败返回 false 但不会抛异常很容易被忽略。4.3 裁剪尺寸与业务要求的匹配陷阱很多产品经理给的头像尺寸是 100×100CSS 像素但服务器端实际存储的是原图前端用 CSS 缩放展示。如果裁剪时直接输出 100×100上传到服务器后再放大做高清展示画质会明显发虚。我一般建议裁剪输出至少 512×512服务端再按需生成不同尺寸的缩略图。这样既保证了清晰度上限又不会让原图过大。另一个坑是裁剪框的宽高比和输出尺寸宽高比不一致。比如aspectX1, aspectY1但outputX512, outputY480部分 ROM 会把裁剪框内的图等比缩放后再居中裁掉多余部分表现是“你看到的裁剪区域和你实际得到的结果不一致”。规避方式是保持裁剪框宽高比与输出宽高比完全统一要么全用 1:1要么全用 16:9。5. 上传下载与头像持久化路径管理、失败重试与缓存策略5.1 上传接口设计与 Multipart 组装拿到裁剪后的图片文件路径后下一步是上传到服务器。项目里用的是multipart/form-data格式字段名为avatar额外附带一个userId参数识别上传者。creator 的XMLHttpRequest在原生环境不支持直接设置multipart边界常见做法是用纯 Java 实现一个轻量级 HTTP POST。public static void uploadAvatar(String filePath, String userId) { String boundary Boundary- System.currentTimeMillis(); HttpURLConnection connection (HttpURLConnection) new URL(UPLOAD_URL).openConnection(); connection.setRequestMethod(POST); connection.setRequestProperty(Content-Type, multipart/form-data; boundary boundary); String prefix -- boundary \r\n; String entity prefix Content-Disposition: form-data; name\userId\\r\n\r\n userId \r\n; String fileHeader prefix Content-Disposition: form-data; name\avatar\; filename\avatar.jpg\\r\n Content-Type: image/jpeg\r\n\r\n; DataOutputStream out new DataOutputStream(connection.getOutputStream()); out.writeBytes(entity); out.writeBytes(fileHeader); out.write(Files.readAllBytes(Paths.get(filePath))); out.writeBytes(\r\n-- boundary --\r\n); out.flush(); out.close(); int code connection.getResponseCode(); connection.disconnect(); }这块代码手写了 multipart 报文没有依赖 OkHttp 等库减小包体积。boundary是一个随机字符串用于分割 multipart 中的不同字段Content-Disposition里的name对应服务端接收字段名filename是服务端看到的文件名。要注意的是HttpURLConnection默认不启用输出缓存如果图片较大建议设置connection.setChunkedStreamingMode(1024 * 64)先把文件流分块写入避免大文件一次性占用太多内存。5.2 下载头像与缓存目录策略用户再次进入应用时需要从服务器拉取头像进行展示。下载不只是 GET 一个文件那么简单至少要处理三件事断点续传、缓存去重、文件名安全。function downloadAvatar(userId, onSuccess) { const cachePath native.getAvatarCachePath(); const fileName ${userId}_avatar.jpg; const savePath native.joinPath(cachePath, fileName); if (native.fileExists(savePath)) { onSuccess(file://${savePath}); return; } const xhr new XMLHttpRequest(); xhr.open(GET, ${SERVER_URL}/avatar?userId${userId}, true); xhr.responseType arraybuffer; xhr.onload function () { const data new Uint8Array(xhr.response); native.writeFile(savePath, data); onSuccess(file://${savePath}); }; xhr.send(); }逻辑上先查本地有没有同名文件有就直接返回省一次网络请求。没有的话走下载流程拿到arraybuffer后写入缓存目录。参数fileName用userId做前缀可以防止多用户登录时缓存互相覆盖SERVER_URL里的avatar路径按服务端实际接口调整。这里还有一层安全考虑下载路径不能直接用服务器返回的文件名拼路径否则遇到../../这种字符串会造成路径穿越写入到非预期目录。文件名固定为userId_avatar.jpg是为了避免这个问题。5.3 缓存清理与版本更新头像缓存文件长时间不清理会越来越大我通常会加一个简单的 LRU 清理逻辑每次启动时扫描缓存目录把创建时间最早的、总大小超过 50MB 的文件逐个删除直到低于阈值。这块逻辑放在 Java 侧写比较方便因为File.lastModified()和File.length()在 JS 层拿不到。public static void purgeCacheIfNeeded() { File dir getAvatarCacheDir(); long totalSize 0; ArrayListFile files new ArrayList(); for (File f : dir.listFiles()) { if (f.isFile()) { files.add(f); totalSize f.length(); } } if (totalSize MAX_CACHE_SIZE) return; files.sort(Comparator.comparingLong(File::lastModified)); for (File f : files) { if (totalSize MAX_CACHE_SIZE * 0.8f) break; totalSize - f.length(); f.delete(); } }MAX_CACHE_SIZE我一般设置为 50MB删除到 80% 阈值就停避免用户每进一次应用都触发全量清理。参数Comparator.comparingLong(File::lastModified)按修改时间升序排列最老的排在最前面优先删除。6. 避坑清单四个高频踩坑点与排查路径6.1 Android 7.0 之后 FileUriExposedException现象开发者反馈相机一打开就闪退日志中可以看到FileUriExposedException。原因应用向系统相机传递file://协议的 Uri系统为了安全阻止了这种跨应用暴露。解决统一改用FileProvider.getUriForFile()生成content://协议 Uri并在 Manifest 里注册provider节点、配置file_paths.xml。provider android:nameandroidx.core.content.FileProvider android:authorities${applicationId}.fileprovider android:exportedfalse android:grantUriPermissionstrue meta-data android:nameandroid.support.FILE_PROVIDER_PATHS android:resourcexml/file_paths / /providerfile_paths.xml里需要声明external-files-path namecamera_cache pathcamera_cache/ /这样才能把相机缓存目录映射成可访问的content://地址。漏掉这一步的表现是FileProvider 报找不到路径因为默认只开放了getCacheDir()下的路径。6.2 裁剪返回 empty data现象部分华为、小米机型上调用系统裁剪后返回的数据是空的。原因厂商修改了裁剪 Activity 的返回逻辑return-data不再返回 Bitmap或者 Intent 里根本没放入 data。解决不要依赖return-datatrue改成return-datafalse后从EXTRA_OUTPUT指定的路径读取裁剪结果。这一步是经验之谈标准 Android 文档里CROP本身就是非公开接口不同 ROM 实现差异极大最保险的是完全不依赖系统裁剪返回的 data。6.3 相册图片方向翻转现象用户选择竖拍照片后上传到服务器变成横图。原因相册里的 JPEG 图片带有 EXIF orientation 信息解码时BitmapFactory不会自动校正方向只有部分图像加载库如 Glide在加载时会做校正。解决读取MediaStore.Images.ImageColumns.ORIENTATION字段或从 EXIF 解析方向角然后对 Bitmap 做Matrix.postRotate()旋转。ExifInterface exif new ExifInterface(filePath); int orientation exif.getAttributeInt(ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL); 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; }处理完旋转后记得把校正后的 Bitmap 重新写回文件否则下次加载时问题依旧。注意ExifInterface在 Android 10 之前是android.media.ExifInterface10 之后 API 层面有调整建议用androidx.exifinterface.media.ExifInterface统一。6.4 上传超时与失败重试现象弱网环境下上传头像失败率高用户反复点击上传按钮造成重复请求。原因HttpURLConnection默认超时时间为 0无限等待用户等不到反馈就重复触发。解决设置connectTimeout和readTimeout并在超时后返回明确的错误码给 JS 层提示。connection.setConnectTimeout(10000); connection.setReadTimeout(15000);我还习惯在上传按钮处做一层节流点击后立即disabled上传成功的回调里恢复失败则允许再次点击。connectTimeout10000是连接建立时限readTimeout15000是数据读取时限这两个参数分别对应“服务器连不上”和“服务器卡住不回包”两种场景分开设置比统一设一个timeout更精准。7. 进阶验证方法从功能能用到异常可控前面几章解决了功能链路“跑得通”的问题但头像上传这种核心链路必须在发布前做一轮系统的异常验证。我常用的方法分三步制造异常输入、验证降级策略、检查资源释放。第一步制造异常输入。我用一个伪造的路径file:///sdcard/nonexistent_avatar.jpg直接调上传接口看服务端返回什么、客户端是否崩溃。正确做法是上传前检查new File(path).exists()不存在时走默认头像逻辑。第二步验证降级策略。当服务器返回 5xx 或网络超时客户端要自动重试两次两次仍失败则提示“上传失败请检查网络”而不是默默把错误吞掉。function uploadWithRetry(path, retryCount) { return uploadAvatar(path).catch(err { if (retryCount 0) { return uploadWithRetry(path, retryCount - 1); } throw err; }); }第三步检查资源释放。每拍一张照片、每调一次相册、每完成一次裁剪都要确认临时文件是否被清掉、Bitmap 是否已经recycle。用 adb 查看应用目录adb shell run-as com.example.project ls -R files/avatar adb shell run-as com.example.project ls -R cache/camera_cache如果目录里积累了大量未清理的临时图片说明回收逻辑有遗漏。我一般会写一个定时器在应用退到后台时扫一遍缓存目录删掉超过 24 小时的临时文件——这是为了避免上一次异常中途退出导致的文件泄漏。从那以后我每次做完采集上传功能都会强制走一遍这套验证流程先构造错误路径、再断网测重试、最后查缓存残留。三关都过才敢交给测试。希望帮到你。本文还有配套的精品资源点击获取
 方法源码详解)
