简介：一套2023年双端获取相册通讯录系统源码，面向需要实现手机相册与通讯录读取管理功能的应用开发者，提供可直接部署的PHP后端、后台管理端和移动端示例。资源共2000个文件，核心为1589个PHP业务文件，另有510个PNG界面素材、136个PHPT模板、CSS/JS前端资源、XLSX表与SQL文件，并附APK/IPA安装包，整体约51.06MB。已有4618人学习下载，适合按教程从Apache、MySQL、PHP环境部署，完成数据库路径修改、public目录运行、伪静态设置与后台登录。安卓端可反编译替换IP指向自有服务器，便于理解客户端与PHP后台通信及双端打包流程。整套目录结构清晰，可作为课程设计或毕业设计参考，帮助快速复现完整的相册通讯录双端系统。
1. 双端获取相册通讯录：这套源码解决的远不止“读取权限”那点事
做移动端数据工具这几年，我拆过不少号称“一键导出”的通讯录源码，大多数打开就露馅：要么只有一个壳，权限声明写得满天飞，真正能跑的代码没几行；要么只适配了老版本系统，放到新机型上直接闪退。这套“2023双端完美获取相册通讯录系统源码”是我最近拆完觉得值得写一篇笔记的——它同时覆盖苹果和安卓两端，通讯录、相册两类数据都有完整的采集、解析、导出链路。所谓“完美”，指的是它绕开了传统方案里最容易被系统拦截的几个环节：授权状态检测、数据分批读取、跨端格式统一。适合谁用？自己手里有多台设备需要做数据归集的个人开发者、做手机数据迁移工具的小团队，以及想研究系统私有数据访问权限机制的学习者。它不负责教你什么是联系人字段，而是直接给你一条能跑通的采集管线。
2. 为什么这套源码能拿到数据：底层权限模型与双端实现差异
2.1 苹果端的权限申请时序：Info.plist 与首次启动的弹窗博弈
苹果端的隐私策略是所有移动平台里最严格的，系统只给一次弹窗机会，用户点了“不允许”之后，除非去设置里手动打开，否则应用再无第二次申请入口。这套源码里苹果端做对的第一件事，是把四个关键权限的用途描述字符串全部补齐了：相册用NSPhotoLibraryUsageDescription，相机用NSCameraUsageDescription，通讯录用NSContactsUsageDescription，麦克风用NSMicrophoneUsageDescription。很多开发者只写了相册和通讯录，结果一调相机就崩溃。
另一个容易翻车的地方在申请时序。苹果官方不强制要求先申请哪个权限，但实际体验上，如果把相册和通讯录的弹窗叠在一起弹，第二个弹窗会被系统直接吞掉。这套源码的处理方式是串行申请：先检测通讯录授权状态，未授权则发起申请，等回调结束再检测相册状态。下面是核心代码逻辑：
func requestAllPermissions(completion: @escaping (Bool) -> Void) { let contactStore = CNContactStore() let photoLib = PHPhotoLibrary.shared() // 第一步：先请求通讯录权限 contactStore.requestAccess(for: .contacts) { granted, _ in guard granted else { completion(false) return } // 第二步：通讯录授权完成后再请求相册 photoLib.performChanges({ PHAssetChangeRequest.creationRequestForAsset() }) { success, _ in completion(success) } } }这段代码里有个容易忽略的细节：申请相册权限用的是performChanges创建一个空资源请求，而不是直接调用requestAuthorization。原因是requestAuthorization在部分系统版本上回调时机不稳定，而performChanges会触发系统弹窗，并且回调一定在用户做出选择之后。creationRequestForAsset创建的空 asset 会在授权被拒绝时自动回滚，不会真的写入相册。这个技巧在 iOS 14 之后的系统上都验证过可用，新老版本通吃。
2.2 安卓端的通讯录采集：ContentResolver 双游标合并去重
安卓端的通讯录存储比苹果复杂一个量级，系统联系人数据库实际上由联系人表、号码表、邮箱表等多张表构成。如果只查ContactsContract.CommonDataKinds.Phone.CONTENT_URI，拿到的数据在部分国产 ROM 上会漏掉 SIM 卡联系人。这套源码的做法是双游标采集：一个查设备存储的联系人，一个查 SIM 卡联系人，然后按contactId + data1做联合去重。
ContentResolver resolver = context.getContentResolver(); // 游标1：设备联系人号码 Cursor deviceCursor = resolver.query( Phone.CONTENT_URI, new String[]{Phone.CONTACT_ID, Phone.DISPLAY_NAME, Phone.NUMBER}, null, null, null); // 游标2：SIM卡联系人（部分ROM此URI可能为空，需判空） Cursor simCursor = null; try { simCursor = resolver.query( Uri.parse("content://icc/adn"), new String[]{"_id", "name", "number"}, null, null, null); } catch (Exception ignored) { // 部分机型没有SIM卡URI，直接跳过 }这里要重点说明content://icc/adn这个地址，它属于非公开 API，在安卓 8.0 之前大部分机型可以查询，之后不少厂商做了限制。源码里对这个查询做了完整异常捕获，查不到时静默降级为仅设备联系人。见过有人在这里不做保护，直接导致低版本机型崩溃——因为某些定制 ROM 的icc/adn返回的游标列名不叫name和number，而是tag和number。稳妥做法是先检查列名，取getColumnIndex("name")不为 -1 才使用。这套源码的普适性正是体现在这些防御代码上。
2.3 相册采集的时间戳分批策略：避免内存暴涨
相册数据读取比通讯录更考验工程能力，一个现代机型上照片数量动辄上万，一次性加载缩略图或原图路径数组，内存直接吃满。这套源码用的是时间戳分段方案——以 7 天为一个窗口，按PHAsset的creationDate或安卓MediaStore的DATE_ADDED分桶查询，每桶数据量控制在几百条左右，处理完再取下一段。
fun fetchPhotosInBatches(context: Context, dayWindow: Int = 7) { val resolver = context.contentResolver val collection = MediaStore.Images.Media.EXTERNAL_CONTENT_URI val startTime = System.currentTimeMillis() / 1000 - 365 * 24 * 3600 var currentStart = startTime val endTime = System.currentTimeMillis() / 1000 while (currentStart < endTime) { val currentEnd = minOf(currentStart + dayWindow * 86400, endTime) val selection = "${MediaStore.Images.Media.DATE_ADDED} >= ? AND ${MediaStore.Images.Media.DATE_ADDED} < ?" val selectionArgs = arrayOf(currentStart.toString(), currentEnd.toString()) val cursor = resolver.query(collection, arrayOf( MediaStore.Images.Media._ID, MediaStore.Images.Media.DATA, MediaStore.Images.Media.DATE_ADDED ), selection, selectionArgs, null) // 每批处理完后立即关闭游标，释放内存 cursor?.use { c -> while (c.moveToNext()) { val id = c.getLong(c.getColumnIndexOrThrow(MediaStore.Images.Media._ID)) val path = c.getString(c.getColumnIndexOrThrow(MediaStore.Images.Media.DATA)) // 此处做业务处理：写文件、入库或上传 } } currentStart = currentEnd } }参数说明：dayWindow默认 7 天，你可以按实际场景调整。如果设备照片拍摄时间跨度大但总量少，可以改成 30 天；如果总量超过两万张，建议改成 3 天，避免单批游标过大导致TransactionTooLargeException。游标一定要用use块包住，确保遍历结束自动关闭——这是这套源码里被刻意强调的习惯，因为在循环里手动close遇到异常时容易漏关，泄漏到一定数量系统会直接杀进程。
3. 怎么部署跑通：源码目录结构与双端工程配置
3.1 拿到源码包先看什么：目录结构与核心文件清单
解压这套源码后，第一件事不是急着跑，而是先核对目录结构。正常包含ios/和android/两个顶级目录，ios/下是 Xcode 工程，android/下是 Gradle 工程。iOS 端重点看ContactExporter.swift和PhotoExporter.swift两个文件，安卓端重点看ContactService.java和MediaFetchTask.java。判断源码是否完整有一个土办法：检查是否存在.xcodeproj和build.gradle文件。如果只有.swift和.java散件缺少工程文件，说明发布者拆包时漏了工程配置，自己重建工程耗时耗力。
# 建议按此顺序检查源码包完整性 unzip -l dual_platform_contact_photo_source.zip | head -50 # 确认存在 ios/Config.xcconfig 与 android/app/build.gradle unzip -l dual_platform_contact_photo_source.zip | grep -E "xcconfig|build.gradle" # 查看关键实现文件行数，判断是否为完整实现 wc -l ios/ContactExporter.swift android/ContactService.java检查逻辑：xcconfig文件是 iOS 工程的环境配置文件，缺失说明工程依赖的编译参数不全；build.gradle是安卓工程的构建入口，缺失同样说明工程无法直接构建。两个实现文件的行数也能侧面反映实现完整度——通讯录导出和相册采集至少各需要 300 行以上才能真正跑通，如果只有几十行，大概率是接口壳或 Demo 片段。
3.2 iOS 端配置：签名、Bundle Identifier 与权限声明
iOS 工程打开后的第一坑是签名。源码包里带的签名配置全部是占位的，必须换成自己的开发者账号信息才能真机部署。具体操作：在 Xcode 中选中工程 Target → Signing & Capabilities → 勾选 Automatically manage signing，然后在 Team 下拉框选择自己的账号。Bundle Identifier 需要改成你自己的域名反写，比如com.yourcompany.dualplatform。改完后，确认Info.plist里的权限描述字段没有因为签名切换被清掉。
# 检查 Info.plist 权限字段是否完整 plutil -p ios/Info.plist | grep -E "NSPhotoLibrary|NSContacts|NSCamera" # 若输出缺少上述字段，用以下命令补入（以通讯录为例） /usr/libexec/PlistBuddy -c "Add :NSContactsUsageDescription string 获取通讯录用于导出联系人数据" ios/Info.plist部署阶段容易忽略的是最低系统版本。这套源码 iOS 端最低支持到 iOS 12，但 Xcode 默认模板会生成IPHONEOS_DEPLOYMENT_TARGET为当前新系统版本，你需要手动改回12.0。否则一套原本支持老机型的代码，编译后安装到旧设备上直接提示无法安装。修改位置在 Build Settings → Deployment → iOS Deployment Target。做完这三步——签名、Bundle ID、部署版本，iOS 端基本就能跑通了。
3.3 Android 端配置：Gradle 版本、SDK 编译版本与存储权限
安卓端打开工程后，Gradle 同步大概率会因为版本不匹配报错。这套源码基于 Gradle 7.4 编写，对应 Android Gradle Plugin 7.1.x。如果你的本机 Android Studio 版本偏新或者偏旧，需要手动调整gradle-wrapper.properties里的distributionUrl和根目录build.gradle里的插件版本号。
// android/build.gradle 关键配置 buildscript { ext { compileSdkVersion = 33 minSdkVersion = 21 targetSdkVersion = 33 } }需要注意compileSdkVersion 33对应安卓 13，这套源码在 2023 年编写时主要适配这一代 API。如果你的测试设备是安卓 14 或 15，需要检查READ_MEDIA_VISUALS和READ_CONTACTS权限声明方式。安卓 13 之后，READ_EXTERNAL_STORAGE对相册不可用，必须改为READ_MEDIA_IMAGES；但这套源码同时兼容老版本，所以在AndroidManifest.xml里两者都声明了：
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" android:maxSdkVersion="32" /> <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" /> <uses-permission android:name="android.permission.READ_CONTACTS" />maxSdkVersion="32"是这套源码里很见功底的一笔。如果不加这个限制，安卓 13 及以上系统会认为你同时申请了新老权限，部分 ROM 会在安装时直接拒绝授予相册权限。加上后，老系统走老权限，新系统走新权限，各取所需。安卓端跑通后，输出目录默认在Android/data/<包名>/files/exports/下，用文件管理器直接可见。
4. 双端采集任务调度与本地导出格式设计
4.1 统一数据模型：VCard 与 JSON 双格式输出
通讯录导出最理想的格式是 VCard，因为 iOS 和安卓原生通讯录应用都直接支持导入 VCard 文件。这套源码里定义了一个统一数据模型，先把两端通讯录数据映射为 CommonContact 对象，再序列化为 VCard 字符串。这样做的好处是，后续如果要扩展导出到 Excel，只需增加一个序列化器，不需要改采集端的任何代码。
public class CommonContact { private String name; private List<String> phones; private List<String> emails; private String remark; public String toVCard() { StringBuilder sb = new StringBuilder(); sb.append("BEGIN:VCARD").append("\n"); sb.append("VERSION:3.0").append("\n"); sb.append("FN:").append(name == null ? "" : name).append("\n"); for (String phone : phones) { sb.append("TEL;TYPE=CELL:").append(phone).append("\n"); } for (String email : emails) { sb.append("EMAIL;TYPE=INTERNET:").append(email).append("\n"); } sb.append("END:VCARD").append("\n"); return sb.toString(); } }这个toVCard方法有个关键点：字段值里如果有;或,必须转义，否则再导入时会断行错乱。常见做法是统一做replace(";", "\\;").replace(",", "\\,")。源码里已经处理过，如果自己二次开发要注意不要丢掉。VCard 版本这里用的是 3.0，兼容性最好，4.0 的某些字段老设备不认。
4.2 任务队列串行导出：防止并发写文件造成索引错乱
相册导出的场景里，如果直接用多线程并发写文件，图片多了以后会出现两个问题：一是部分图片写入时文件名重复，二是导出的索引文件与图片文件对应关系错乱。这套源码的做法是维护一个串行任务队列——HandlerThread或SerialExecutor，每张图片的任务按顺序执行，文件名用「日期_序号」规则生成，保证文件名天然有序。
private val exportExecutor = Executors.newSingleThreadExecutor() fun enqueuePhotoExport(photoId: Long, path: String, exportIndex: Int) { exportExecutor.execute { val destFile = File(exportDir, "${getDateTag(path)}_${exportIndex.toString().padStart(5, '0')}.jpg") try { FileInputStream(File(path)).use { input -> FileOutputStream(destFile).use { output -> input.copyTo(output) } } appendToIndexManifest(photoId, destFile.absolutePath) } catch (e: IOException) { Log.e("ExportTask", "photo export failed: $path", e) appendToErrorLog(photoId, path, e.message ?: "Unknown IO error") } } }这里的exportIndex是外层遍历时的全局递增序号，使用padStart(5, '0')补零到 5 位，保证 99999 张以内文件名字典序与时间序一致。appendToIndexManifest负责把原始 photoId 与导出后的绝对路径写入一个manifest.csv，这个文件是后续做增量同步或导入回设备的依据。注意src/main/assets/manifest.csv模板只在首次创建导出目录时拷贝，之后每次导出在这里做追加。
4.3 增量导出：基于上次导出时间的断点设计
这套源码最实用的一个设计是增量导出。默认配置下，每次触发导出前会读取一个last_export_timestamp文件，只有在此时间戳之后新增的照片和变更的联系人才会被导出。对于反复测试的开发者来说，这个功能省去了每次全量导出的等待时间；对于做数据备份工具的用户来说，增量导出能大幅降低重复文件占用空间。
# 伪代码展示增量判断的核心逻辑（源码用Java/Kotlin实现同样的机制） last_export = read_timestamp("last_export_timestamp") current_time = int(time.time()) # 根据最后导出时间递增查询条件 selection = "DATE_ADDED >= ?" selection_args = [str(last_export)] # 导出完成后写入当前时间作为新的断点 write_timestamp("last_export_timestamp", current_time)实现这个逻辑的关键是时间基准得用系统时间而非文件修改时间：相册在跨设备迁移时DATE_ADDED可能变，但系统时间戳不会因为文件复制而重置。首次运行且last_export_timestamp不存在时，源码会默认全量导出，并在日志中打印first_run_full_export标记。如果你在测试时想强制全量导出，直接删除或改名为这个时间戳文件即可。
5. 避坑与常见问题排查：线上环境反复踩过的五个真坑
5.1 现象：iOS 端通讯录导出后个别联系人乱码
原因：源 VCard 字段名用了中文（比如FN:张三没问题，但备注字段里有非 UTF-8 编码的字符）。这套源码在 iOS 端默认用 UTF-8 编码写入文件，但部分 Windows 下的 VCard 消费者应用默认读 GBK。解决：如果导入目标以 Windows 为主，在导出时强制用 UTF-16LE with BOM 编码，或统一把字符串按NSString dataUsingEncoding:NSUTF8StringEncoding后转写 Base64。血泪经验是每个字段做编码自检，而不是最后统一转码——因为 iOS 的CNContact取出来就是 Unicode，但拼接成字符串时如果某个字段为nil，转码会直接崩溃。
5.2 现象：安卓端通讯录导出的联系人数量总是比系统通讯录少几十个
原因：系统通讯录里有几个联系人挂在「我的档案」或者「SIM 卡」分组下，设备联系人游标查不到；另一个原因是来源 ID 为空的联系人（某些应用写入的原始数据缺少RAW_CONTACT_ID）被过滤。解决：游标查询时不要加DISPLAY_NAME IS NOT NULL的过滤条件，允许姓名为空的行也进入结果集；对 SIM 卡游标查出但设备游标没有的行单独标记来源为SIM，最后用contactId做合并时优先保留设备端数据，同时把contactId的字符串值前后 trim 干净，因为 SIM 卡里很多号码带了空格。
5.3 现象：相册导出过程中内存占用持续上涨最终 OOM
原因：导出任务虽然用了单线程，但每张图片都先缩略图预览再写原图，而预览图在循环中没有及时recycle()。安卓的Bitmap在导出任务后如果没有显式回收，内存不会自动释放，直到下一个 GC 周期，大量图片累积后撑爆堆内存。解决：每张图片处理完立即判断是否仍是MutableBitmap，是就bitmap.recycle()，再把引用置空。这套源码里MediaFetchTask在每个循环尾部做bitmap.recycle(); bitmap = null;，相当于手动干预了 GC 时机，实测导出两万张照片的内存峰值可以压在 80MB 以内。
5.4 现象：iOS 端头像照片导出后 EXIF 信息丢失
原因：直接从PHAsset取fullResolutionImage只拿到了像素数据，没有把 EXIF 写回。部分照片的日期、GPS、拍摄参数全没了。解决：导出的正确语义应该用PHImageManager的requestImageDataAndOrientation获取原始文件数据，而不是requestImage。代码如下：
PHImageManager.default().requestImageDataAndOrientation(for: asset, options: nil) { data, _, _, _ in guard let data = data else { return } try? data.write(to: destURL) }requestImageDataAndOrientation拿到的才是原始 HEIC/JPEG 二进制，包含全部 EXIF。差一行 API，导出质量天壤之别。
5.5 现象：双端导入导出后，联系人的头像全部丢失
原因：VCard 3.0 规范里头像用PHOTO字段携带 Base64 编码数据，但很多通讯录应用写 VCard 时只写FN和TEL，忽略了PHOTO。这套源码里导出的 VCard 已经包含 Base64 头像，但导入方如果是老系统通讯录应用，可能会因 Base64 数据超过字段长度限制而丢弃。解决：导入目标设备如果是老系统，建议先导出无头像精简版 VCard，确保基本字段优先；头像单独导出为avatar_<contact_id>.jpg，归入头像附件目录，再逐张回写。相当于把通讯录文本与头像二进制拆成两个通道，各自保证完整。
6. 验证导入链路与输出文件完整性：用 glob 和哈希做最后一道质检
导出完成不等于任务结束，数据能不能顺利导入目标设备才是真正的检验标准。我每次跑完全流程，都会强制走一遍三段式验证，这三段代码可以自己加到工程里，作为 CI 环节的冒烟测试。
第一段是数量一致性核对：
# 检查导出 VCard 文件数量与实际联系人数量是否一致 grep -c "BEGIN:VCARD" exports/contacts/*.vcf # 应等于安卓端导出的联系人计数（可从日志中的 exported_count 字段读取） # 若不一致，优先排查是否存在空名字联系人的抓取遗漏第二段是哈希校验相册文件的传输完整性：
# 对每张导出照片计算 SHA256，与源文件比对 find exports/photos -type f -name "*.jpg" | xargs sha256sum > exported.sha256 # 如果其中任何一张的哈希与源不一致，说明导出过程中发生了字节截断 # 常见原因是磁盘空间不足导致文件未写完整第三段是导入验证。安卓端可以用系统通讯录的.vcf导入功能直接导入，观察日志中是否出现「解析失败」条目；iOS 端用Contacts应用的导入功能，导入后随机抽查 10 个联系人，核对姓名、号码、头像三项字段。抽查这种方法听起来糙，但比全量校验更快地暴露字段错位问题。
除此之外有一个容易忽略的坑：VCard 文件编码与换行符。同一批联系人，在 Windows 上编辑过再导出，换行符变成CRLF，导入到 iOS 时部分老版本会解析异常；统一用LF换行转一遍再做导入，能省掉不少排查时间。
从拆这套源码到部署完成，我最大的感受是：双端数据采集这套逻辑，真正的复杂度不在权限申请那几行代码，而在跨版本兼容和数据一致性的边界处理。从那以后我每次写完导出流程，都会强制走一遍「最小集验证」——清空导出目录，造 3 条联系人 + 5 张图片的测试数据，从头跑一遍导入导出再回来检查输出。这套验证习惯帮我挡掉了至少三次发布事故。希望这篇笔记能让你在动手前看清这套源码的真实面貌，少走我已经走过的弯路。
本文还有配套的精品资源，点击获取
