uni-app x 的 uni.installApk() 安装 APK 指南：从 API 参数到 Android 底层实现
uni-app x 的 uni.installApk() 安装 APK 指南从 API 参数到 Android 底层实现【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-app x 内置的uni.installApk(options)用于在 Android 平台直接安装本地 APK 文件是 App 内「检测更新 → 下载 → 静默跳转安装」链路的关键一环。本文以本仓库中的官方 API 文档为主体结合uni-installApkUTS 插件的真实源码完整讲解该 API 的兼容性边界、参数与回调约定、错误码体系、Android 底层实现原理Intent FileProvider 流程并给出可直接运行的示例与 App 升级场景的最佳实践。读完本文你将掌握在 uni-app x 项目中安全、规范地触发 APK 安装的全部要点。API 概览与兼容性uni.installApk(options)的职责非常简单安装 apk。它接收一个InstallApkOptions参数对象无返回值。平台兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | x | 3.94 | x | x |兼容性表格的含义Android从uni-app x 3.94版本起支持源码中interface.uts的uniPlatform注解同样标注为uniVer: 3.94、unixVer: 3.94见 interface.utsWeb / 微信小程序 / iOS / HarmonyOS均不支持表格中的x表示无此能力。uni-installApk插件的 readme.md 开头也明确写道「实现安装apk功能仅Android平台支持」。因此在实际工程中调用前通常应使用条件编译#ifdef APP或#ifdef APP-ANDROID包裹相关代码避免在其他平台误触发。重要使用限制注意仅支持本地文件路径网络路径需先通过 uni.downloadFile 下载到本地再调用此 API 安装。这是本 API 最核心的一条约束。APK 无法直接以 URL 形式传入完整流程必须是uni.downloadFile下载 APK 到本地 → 拿到本地filePath→ 调用uni.installApk。相关下载 API 的细节可参阅仓库中的 download-file.md。典型应用场景App 升级安装 APK 最常见的业务场景是App 的版本升级。对此官方文档的建议是更推荐直接使用 uni 的App 升级中心它是一个云端一体开源项目如果完全靠手写去达到该项目的体验细节版本检测、强制升级、增量更新、下载进度、安装引导等需要大量代码不如直接拿来使用。也就是说uni.installApk更适合作为自定义升级逻辑中的最后一公里而完整升级方案优先考虑 App 升级中心。参数与回调详解参数总览| 名称 | 类型 | 必填 | 兼容性 | | :- | :- | :- | :-: | | options |InstallApkOptions| 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x |options 的属性描述| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 | | :- | :- | :- | :- | :-: | :- | | filePath | string | 是 | | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | apk文件地址仅支持本地文件路径 | | success | (res: InstallApkSuccess) void | 否 | null | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 接口调用成功的回调函数 | | fail | (err: InstallApkFail) void | 否 | null | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 接口调用失败的回调函数 | | complete | (res: any) void | 否 | null | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 接口调用结束的回调函数调用成功、失败都会执行 |各字段在插件源码 interface.uts 中有完全一致的类型定义filePath: string必填仅支持本地文件路径success/fail/complete三个回调均为可选默认值nullcomplete的类型被定义为any无论成功还是失败都会执行适合做统一的收尾处理如隐藏 loading。InstallApkSuccess 的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | errMsg | string | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 安装成功消息 |成功回调中只有一个errMsg字段。从 Android 实现看成功回调在context.startActivity(intent)之后立即触发errMsg固定为字符串success见 index.uts。需要说明的是此处成功仅代表安装 Intent 已成功发出系统安装器界面是否被用户确认安装、最终是否安装完成并不在本 API 的回调能力范围内。InstallApkFail 的属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | errCode | number | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 错误码- 1300002 找不到文件 | | errSubject | string | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 统一错误主题模块名称 | | data | any | 否 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 错误信息中包含的数据 | | cause | Error | 否 | | 源错误信息可以包含多个错误详见SourceError | | errMsg | string | 是 | Web: x; 微信小程序: x; iOS: x; HarmonyOS: x | 错误描述 |错误对象遵循 uni-app x 的统一错误规范详见 err-spec.md 中的UniError定义关键字段在 unierror.uts 中均有落地errSubject固定为uni-installApk即模块的统一错误主题名称errCode当前仅定义1300002对应英文错误消息No such file含义是找不到文件errMsg由errCode映射而来cause源错误对象可包含多个错误详情SourceError仅在捕获到底层异常时填充。源码级原理Android 端是如何安装 APK 的本仓库中uni.installApk的真实实现位于 UTS 插件 src/uni_modules/uni-installApk/ 目录结构如下utssdk/app-android/index.utsAndroid 平台核心实现UTS 编译为 Kotlin 运行utssdk/app-android/AndroidManifest.xmlAndroid 权限声明utssdk/interface.utsAPI 类型与平台兼容性注解utssdk/unierror.uts统一错误实现。路径归一化与 assets 目录的特殊处理installApk函数的第一步是调用UTSAndroid.convert2AbsFullPath(options.filePath)把传入的相对/绝对路径转换为绝对完整路径随后存在一个特殊分支index.uts若路径以/android_asset/开头说明 APK 打包在应用 assets 资源目录内实现会先将其拷贝到应用私有缓存目录getCacheDir()/apks/fileName逐块 1024 字节读写再以该副本作为安装源其余情况直接以new File(filePath)构造文件对象。这个设计解释了为什么示例里可以把 APK 放在static目录下随包发布即便资源位于 assets 中API 也能自动解出真实文件再安装。对Build.VERSION.SDK_INT 24的低版本设备拷贝完成后还会递归执行chmod -R 777以保证文件可读index.uts。文件存在性校验与错误抛出文件对象构造完成后立即校验apkFile.exists()与apkFile.isFile()index.uts校验不通过时创建InstallApkFailImpl(1300002)错误对象errSubject uni-installApkerrMsg No such file依次触发fail与complete回调后return 提前结束这也是errCode 1300002找不到文件唯一的产生来源。Intent FileProvider 安装流程校验通过后进入核心安装逻辑index.uts整体遵循 Android 标准安装套路创建IntentsetAction(Intent.ACTION_VIEW)并添加FLAG_ACTIVITY_NEW_TASK因为调用方是应用而非 Activity 上下文按系统版本分支处理 UriBuild.VERSION.SDK_INT 24Android 7.0使用FileProvider.getUriForFile(context, context.getPackageName() .dc.fileprovider, apkFile)生成content://Uri并addFlags(FLAG_GRANT_READ_URI_PERMISSION)临时授予安装器读取权限setDataAndType(uri, application/vnd.android.package-archive)低版本 24直接使用Uri.fromFile(apkFile)生成file://Uri 并设置同样的 MIME 类型context.startActivity(intent)拉起系统安装器构造{ errMsg: success }并依次触发success、complete回调。权限声明REQUEST_INSTALL_PACKAGES插件的 AndroidManifest.xml 声明了关键权限uses-permission android:nameandroid.permission.REQUEST_INSTALL_PACKAGES /REQUEST_INSTALL_PACKAGES是 Android 8.0API 26起要求的安装未知来源应用权限。当目标设备的系统版本 26 且用户在系统设置中关闭了允许安装未知应用开关时startActivity可能抛出SecurityException或直接无响应。因此生产环境建议在调用安装前引导用户到系统设置页开启该权限可配合uni.openAppAuthorizeSetting等授权类 API 实现参考仓库中 docs/api/open-app-authorize-setting.md。完整可运行示例官方文档给出的示例与本仓库中的真实演示页 src/pages/API/install-apk/install-apk.uvue 保持一致APK 文件放置于 src/static/app-android/test.apk即编译后位于应用 static 资源目录。完整代码如下template !-- #ifdef APP -- scroll-view styleflex: 1 !-- #endif -- view page-head :titletitle/page-head view classuni-common-mt view classuni-padding-wrap view classuni-btn-v button typeprimary tapinstallApk installApk /button /view /view /view /view !-- #ifdef APP -- /scroll-view !-- #endif -- /template script setup languts const title ref(installApk) const installApk () { uni.installApk({ filePath: /static/app-android/test.apk, complete(res : any) { console.log(res); } }) } /script要点拆解模板使用!-- #ifdef APP --条件编译包裹页面因为该 API 不支持 Web 平台请运行到 App 平台体验页面脚本采用script setup languts语法ref为 uts 内置响应式 APIfilePath使用应用内静态资源路径/static/app-android/test.apk配合上文提到的 assets 自动拷贝逻辑可正常触发安装complete回调统一打印结果对象无论成败都会执行。生产级写法下载后安装针对仅支持本地路径的限制实战中标准的升级安装流程如下伪代码思路基于 docs/api/download-file.md 的uni.downloadFileuni.downloadFile({ url: https://example.com/app-release.apk, // APK 的远程地址 success: (res) { const filePath res.tempFilePath // 下载到本地的临时文件 uni.installApk({ filePath: filePath, success: () { /* 已拉起安装界面 */ }, fail: (err) { console.error(err.errCode, err.errMsg) // 例如 1300002 找不到文件 } }) } })若希望下载后 APK 文件不被临时目录清理可结合uni.getFileSystemManager()将临时文件另存到持久目录如_doc或_downloads后再安装具体文件系统规范参见 docs/api/file-system-spec.md。错误码速查| errCode | errSubject | errMsg | 触发时机 | | :- | :- | :- | :- | | 1300002 | uni-installApk | No such file | 本地文件不存在或不是普通文件apkFile.exists()或apkFile.isFile()校验失败 |当前InstallApkErrorCode类型仅包含1300002一个取值见 interface.uts。开发者可在fail回调中依据errCode做分支提示例如向用户反馈安装包文件不存在请重新下载。Tips版本演进与安装方式变化官方文档补充了一个重要的历史版本说明HBuilderX 3.99 以前uni.installApk 是 ext api需单独下载。从 HBuilderX 3.99 起 uni-app x 内置了该 API无需再单独下载。也就是说使用HBuilderX 3.99 及以上版本开发时uni.installApk开箱即用无需额外安装插件若你的 HBuilderX 版本低于 3.99需要先将uni-installApk作为扩展插件单独引入本仓库中该插件目录 src/uni_modules/uni-installApk/ 即标准 uni_modules 结构包含package.json、changelog.md、utssdk实现目录再按 uni_modules 插件方式使用。通用类型参考本 API 相关的错误回调与成功回调均派生自以下通用类型约定GeneralCallbackResult| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 |InstallApkSuccess.errMsgsuccess与InstallApkFail.errMsg错误描述都遵循该字段约定便于在统一封装的回调处理函数中按errMsg或errCode分发逻辑。总结uni.installApk是 uni-app x 在 Android 平台触发 APK 安装的标准入口仅 Android3.94可用仅接受本地文件路径出错时通过errCode 1300002反馈文件缺失。底层实现封装了ACTION_VIEWIntent、Android 7.0 起的 FileProvider 安全 Uri 授予、assets 资源自动解包以及REQUEST_INSTALL_PACKAGES权限声明调用方只需关注先下载到本地、再传入路径、最后处理回调三段式流程。对于完整的版本升级体验检测、强制升级、下载进度等优先选用 uni App 升级中心方案而uni.installApk则是一切自定义升级逻辑最可靠的落地点。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考