uni.getcontact仅android有效,需先调用uni.authorize申请scope.contact权限并配置manifest.json,再调用uni.getcontact;ios、h5、小程序均不支持,推荐使用兼容性更好的uni.choosephonecontact。

uni-app 调用 uni.getContact 前必须处理权限,否则直接失败
Android 和 iOS 都不会在首次调用时自动弹出通讯录授权框——uni.getContact 是个“静默失败型” API:没权限就返回 { errMsg: "getContact:fail auth deny" } 或空数组,不报错也不提醒你缺权限。
必须先用 uni.authorize 或 uni.openSetting 主动拉起授权。但注意:scope.contact 在 iOS 上无效(苹果根本不允许网页/小程序类容器读通讯录),所以这个 API 实际只对 Android 生效。
- Android 真机需在
manifest.json中勾选“联系人”权限(HBuilderX 可视化操作,或手动加"permissions": { "android": ["android.permission.READ_CONTACTS"] }) - iOS 下
uni.getContact永远不可用,别浪费时间测试 - H5、微信小程序等平台不支持该 API,调用会直接报
getContact:fail not supported
Android 上正确调用 uni.getContact 的三步顺序
不是“直接调就完事”,顺序错了照样拿不到数据。尤其要注意:授权和拉起选择器必须分两步,且不能跳过授权检查。
- 第一步:用
uni.authorize({ scope: 'scope.contact' })检查并申请权限;失败时用uni.openSetting引导用户手动开启 - 第二步:确认授权成功后,再调
uni.getContact({ type: 'addressBook' });type只能是'addressBook',传'weixin'会静默失败 - 第三步:结果里每个联系人字段不统一——
name、mobile、tel都可能为空;部分手机(如华为)会把号码存在tel而非mobile,得都判空取
uni.authorize({ scope: 'scope.contact' })
.then(() => uni.getContact({ type: 'addressBook' }))
.then(res => {
const contacts = res.contactList || []
contacts.forEach(c => {
const phone = c.mobile || c.tel || ''
console.log(c.name, phone)
})
})
.catch(err => {
if (err.errMsg.includes('auth deny')) {
uni.openSetting({}).then(res => {
if (res.authSetting['scope.contact']) {
// 再试一次
}
})
}
})
替代方案:为什么多数场景该用 uni.choosePhoneContact
如果你实际只需要让用户选一个联系人(比如填紧急联系人、邀请好友),别硬刚 uni.getContact。它要权限、兼容差、数据杂,而 uni.choosePhoneContact 是系统级联系人选择器,在 Android 和 iOS 上都可用,且无需提前申请通讯录权限。
- 调用后直接弹出原生联系人列表,用户点选即返回
{ name, mobile, tel },字段更干净 - iOS 下也能用(因为走的是系统 picker,不读全量通讯录)
- 不依赖
manifest.json权限配置,H5 和小程序平台也兼容(H5 会降级为手动输入) - 注意:它不返回联系人列表,只返回单个选中的对象;需要多选?不存在的,API 不支持
真机调试时常见错误和对应解法
模拟器永远返回空或报错,一切以真机为准。遇到问题先看错误信息本身:
-
getContact:fail auth deny→ 没授权,检查manifest.json和uni.authorize是否执行 -
getContact:fail not supported→ 当前平台不支持(H5 / 微信小程序 / iOS),别再试了 - 返回空数组但无报错 → 手机通讯录确实为空,或厂商限制(如小米「隐私保护」里禁用了应用读取联系人)
- 字段缺失(如只有
name没号码)→ 检查联系人原始数据是否存了号码,部分手机把号码存在tel字段而非mobile
安卓不同厂商 ROM 对通讯录访问控制差异很大,测试至少覆盖华为、小米、OPPO、vivo 的最新系统版本。有些机型即使开了权限,也要在设置里单独给 uni-app 开“读取联系人”开关——这个容易被忽略。










