欢迎到专业群（ uni-app 官方技术交流群 1 ） 咨询，群中有相关专业的管理员和群友。

这个问题很常见，核心原因不是 plus.runtime.install 失效，而是 Android 系统对“应用内安装 APK”的限制，尤其是小米、vivo、iqoo 这类国产 ROM。

你现在遇到的现象可以分成两类：

1. 小米手机下载完成但不安装

最常见原因是：

没有“安装未知来源应用”权限

从 Android 8 开始，系统不再只看一个总开关，而是按应用单独授权。
也就是说，即使你的 App 已经声明了权限，用户还必须手动允许：

设置 -> 应用管理 -> 你的 App -> 安装未知来源应用 -> 允许

如果这个权限没开，plus.runtime.install 经常表现为：

• 下载成功
• 安装界面不弹出
• 没有明显报错
• 或者一闪而过

小米/红米系统拦截更严格

小米 MIUI / HyperOS 对应用内安装 APK 限制更严格，常见情况有：

• 禁止后台拉起安装界面
• 禁止从未知来源安装
• 安装器被系统安全策略拦截
• 多次触发后被系统限制

所以你会看到荣耀、vivo 正常，小米不行。

2. 你 iqoo 手机反复测试后也不能安装了

这个也很像 系统风控/安装器限制。

国产 ROM 常见机制是：

• 某个 App 频繁调起安装
• 系统认为存在异常安装行为
• 临时禁止它继续拉起安装器
• 或者把“允许安装未知来源”的授权状态重置/隐藏

所以不是代码突然坏了，而是手机系统把你的 App 限制了。

你可以先在 iqoo 手机上检查：

1. 设置里找到你的 App
2. 查看“安装未知来源应用”是否还允许
3. 清除 App 数据或卸载重装
4. 重启手机
5. 换另一个测试 App 或换个包名测试

如果卸载重装后又可以，基本就能确认是系统限制。

正确做法

一、先区分你下载的是 APK 还是 WGT

这个非常关键。

如果是整包升级

也就是下载 .apk，那么：

• plus.runtime.install 只是尝试拉起系统安装器
• 最终能不能安装，取决于系统权限和厂商限制
• 不能强制安装成功

如果是热更新

也就是下载 .wgt，那么：

• plus.runtime.install 是安装资源包
• 不走系统 APK 安装器
• 更适合做应用内升级

你现在的代码如果是下载 APK 后安装，本质上是“引导用户手动安装”，不是静默安装。

二、先检查权限配置

如果你使用的是 离线打包，需要确认 AndroidManifest 中配置了安装权限和 FileProvider。

知识库中明确提到，离线打包如果无法调起安装界面，需要添加：

<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES"/>

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

以及 provider：

<provider  
    android:name="io.dcloud.common.util.DCloud_FileProvider"  
    android:authorities="${apk.applicationId}.dc.fileprovider"  
    android:exported="false"  
    android:grantUriPermissions="true">  
    <meta-data  
        android:name="android.support.FILE_PROVIDER_PATHS"  
        android:resource="@xml/dcloud_file_provider" />  
</provider>

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

其中 ${apk.applicationId} 要替换成你的应用包名。

参考文档：
android > 离线打包无法调起应用安装界面

如果你是 云打包，通常不需要你手动处理 provider，但仍然受系统“未知来源安装”限制。

三、安装前主动引导用户打开“允许安装未知来源”

这是目前最实用的方案。

在调用 plus.runtime.install 前，先判断并提示用户去开启权限。
因为仅靠代码无法绕过系统限制。

你可以这样处理流程：

1. 下载 APK 完成
2. 先提示用户：
   • “请允许当前应用安装未知来源应用”
3. 跳转到系统设置页
4. 用户开启后再返回 App
5. 再调用 plus.runtime.install

四、代码上建议加失败回调，不要只写成功回调

你现在的代码只处理了成功，建议改成这样：

plus.runtime.install(  
  res.tempFilePath,  
  { force: true },  
  () => {  
    uni.showToast({  
      title: "已调起安装",  
      duration: 1500,  
    });  
  },  
  (err) => {  
    console.log('安装失败', err);  
    uni.showModal({  
      title: '安装失败',  
      content: '请检查是否允许“安装未知来源应用”权限',  
      showCancel: false  
    });  
  }  
);

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

这样至少能知道是：

• 没权限
• 文件损坏
• 包不合法
• 系统拦截

五、不要在安装成功后立刻 restart

如果你安装的是 APK 整包，这里其实不应该直接：

plus.runtime.restart();

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

因为 APK 安装是走系统安装流程，安装完成后通常由用户手动打开新应用。
你立即重启当前 App，没有实际意义，还可能造成误解。

APK 整包升级建议写法

plus.runtime.install(res.tempFilePath, { force: true }, () => {  
  uni.showToast({  
    title: "请按系统提示完成安装",  
    duration: 2000,  
  });  
}, (err) => {  
  uni.showToast({  
    title: "安装调起失败",  
    icon: "none"  
  });  
});

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

WGT 热更新才适合 restart

plus.runtime.install(res.tempFilePath, { force: true }, () => {  
  plus.runtime.restart();  
}, (err) => {  
  console.log(err);  
});

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

推荐的升级方案

方案一：APK 整包升级

适合版本变化大、必须整包替换的场景。

流程：

1. 请求服务器检查版本
2. 下载 APK
3. 引导用户允许“安装未知来源”
4. 调起系统安装器
5. 用户手动确认安装

这是安卓最常见方案，但要接受一个事实：

不同手机系统表现不一致，无法保证所有机型都自动弹出安装界面。

方案二：WGT 热更新

适合只更新前端资源、页面、JS 逻辑，不涉及原生能力变更。

优点：

• 用户体验好
• 不需要系统安装器
• 不受“未知来源安装”影响那么大

官方知识库中也给了标准流程：

// #ifdef APP-PLUS  
plus.runtime.getProperty(plus.runtime.appid, function(widgetInfo) {  
  uni.request({  
    url: 'http://www.example.com/update/',  
    data: {  
      version: widgetInfo.version,  
      name: widgetInfo.name  
    },  
    success: (result) => {  
      var data = result.data;  
      if (data.update && data.wgtUrl) {  
        uni.downloadFile({  
          url: data.wgtUrl,  
          success: (downloadResult) => {  
            if (downloadResult.statusCode === 200) {  
              plus.runtime.install(downloadResult.tempFilePath, {  
                force: false  
              }, function() {  
                console.log('install success...');  
                plus.runtime.restart();  
              }, function(e) {  
                console.error('install fail...');  
              });  
            }  
          }  
        });  
      }  
    }  
  });  
});  
// #endif

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

参考：
怎么获取最新的wgt包的版本

方案三：使用 uni-upgrade-center

如果你不想自己维护版本接口、下载逻辑、强制更新、静默更新等，可以直接用官方升级中心。

它支持：

• APK 整包更新
• WGT 热更新
• 强制更新
• 静默更新
• 版本管理

文档：
App升级中心 uni-upgrade-center

针对你现在问题的结论

你的问题根因大概率是：

1. 小米手机

• 系统禁止应用内安装 APK
• 或没有开启“安装未知来源应用”
• 或 MIUI/HyperOS 拦截安装器

2. iqoo 手机

• 因频繁测试触发系统限制
• 或权限被系统重置
• 卸载重装/重启后通常能恢复验证

建议你最终这样改

如果是 APK 整包更新

• 不要依赖 plus.runtime.install 一定成功
• 增加失败回调
• 增加“去开启安装权限”的引导
• 安装后不要立刻 restart

如果想提升体验

• 能热更新的部分走 wgt
• 必须整包更新时才下载 apk

如果你愿意，我可以直接给你一套 uniapp 安卓 APK 整包升级完整可落地代码，包含：

• 版本检测
• 下载进度
• 安装失败回调
• 引导开启“未知来源安装”
• 小米/vivo/iqoo 兼容处理逻辑