UTS 插件基座制作简明指南（Android + iOS）

适用范围：uni-app x uni-app项目中的 UTS 插件 调试、试用、自定义基座制作。
适用平台：Android、iOS。
建议工具版本：HBuilderX 5.07 及以上。

1. 什么情况下要做自定义基座

满足下面任一情况，直接制作 自定义调试基座：

• 插件试用/插件普通授权
• 插件集成了第三方原生 SDK。
• 插件新增了 aar、jar、framework、xcframework 等原生依赖。
• 插件修改了 AndroidManifest.xml、Info.plist、权限、URL Scheme 等原生配置。
• 插件包含或修改了 kotlin/java、swift/oc 原生代码。
• 你在 Windows 环境下验证 iOS 插件。
• HBuilderX 或 uni-app x SDK 升级后，提示基座版本不一致。

如果只是纯页面调试，且插件不依赖原生资源或原生配置，可以先尝试标准基座。

2. 制作前先做这三件事

2.1 绑定正确的项目 AppID

在插件市场试用插件时，先确认绑定的是当前实际运行的项目 AppID。
AppID 绑错后，后续下载、打包、运行都会对不上。

2.2 把插件下载到项目

下载完成后，确认插件已进入项目的 uni_modules 目录，例如：

uni_modules/
└─ your-plugin/

2.3 先在页面里真实调用插件

不要只下载插件就开始做基座，先在页面里真实引入并调用一次插件 API。
建议准备一个最小验证页，至少包含：

• 页面加载时调用一次。
• 点击按钮时再调用一次。
• 把成功或失败结果打印到页面和控制台。

示例：

import { FloatWindow } from '@/uni_modules/android-floatwindow'

这样做的目的只有一个：后面能快速判断基座里到底有没有带上插件能力。

3. 制作前检查

3.1 项目检查

• 项目必须是 uni-app x uni-app 项目。
• 插件目录结构完整。
• 插件已被页面真实引用，而不是只下载未使用。
• 原生依赖、资源文件、原生代码都已放到正确位置。

3.2 平台环境检查

Android

• Android 开发环境可用。
• 真机或模拟器能被 HBuilderX 识别。
• 包名、签名信息已确认。

iOS

• Mac 环境下先确认 Xcode 可用。
• Windows 环境下调试 iOS，通常需要依赖云端生成的自定义基座。
• 证书、Bundle Identifier、描述文件已准备好。

3.3 配置检查

• manifest.json 中应用名称、包名、证书等信息已确认。
• 插件需要的权限已明确。
• 如果依赖第三方 SDK，Android 和 iOS 两端配置都已补齐。

4. 自定义基座制作步骤

第一步：打开云打包

在 HBuilderX 中进入：

发行 -> 原生App-云打包

第二步：勾选制作自定义调试基座

在云打包面板中：

• 选择目标平台。
• 勾选 制作自定义调试基座。

Android 和 iOS 可以分别制作。

第三步：填写平台信息

Android 重点确认

• 应用包名。
• 证书别名、证书密码。
• 插件依赖的权限是否已配置。

iOS 重点确认

• Bundle Identifier。
• 证书和描述文件。
• URL Scheme、推送、定位等能力配置是否完整。

第四步：提交云端打包

提交后等待云端完成。常见状态有：

• 打包中
• 打包成功
• 打包失败

如果失败，优先检查：

• 包名与证书是否匹配。
• 原生配置格式是否正确。
• 插件依赖是否缺失。

第五步：使用自定义基座运行

打包成功后，在 HBuilderX 中按下面路径运行：

运行 -> 运行到手机或模拟器 -> 运行到 App 基座 -> 使用自定义基座运行

这里必须明确选择 使用自定义基座运行，否则仍然可能跑到标准基座，插件能力不会生效。

然后：

• 选择设备。
• 选择刚生成的自定义基座。
• 安装并运行项目。

如果设备里已经装过旧基座，处理时按下面规则执行：

• 如果这次制作基座没有修改版本号，必须先卸载手机里之前安装的基座，再安装新的基座。
• 即使修改了版本号，发现运行结果异常时，也建议先卸载旧基座再重装最新基座。

5. 做完基座后怎么验证

按下面顺序验证即可：

1. 确认当前运行方式确实是 使用自定义基座运行，这一步是必须项。
2. 打开最小验证页。
3. 先看页面加载时的调用结果。
4. 再点按钮触发一次调用。
5. 同时检查页面输出和控制台日志。

如果页面能调用、日志正常、功能生效，说明插件能力已经进入当前基座。

6. 哪些改动后要重做基座

下面这些改动通常不能靠热更新生效，改完后要重新制作基座：

• Android kotlin/java
• iOS swift/oc
• 第三方原生 SDK
• AndroidManifest.xml
• Info.plist
• aar、jar、framework、资源文件
• 权限、URL Scheme、白名单等原生配置

另外，HBuilderX 或 uni-app x SDK 升级后，也建议重新制作。

7. 常见问题

7.1 提示“当前运行的基座未包含 API”

通常是下面几种原因：

• 跑的是标准基座，不是自定义基座。
• 用的是旧基座。
• 新增了原生能力，但没有重做基座。

处理顺序：

1. 先确认当前运行方式是不是 使用自定义基座运行。
2. 再确认当前安装的是不是最新基座。
3. 如果刚改过原生层，重新打一次基座。

7.2 Android 报类找不到或依赖找不到

通常检查这三项：

• aar/jar 是否放对位置。
• 插件配置是否完整。
• 当前是否仍在使用旧基座。

7.3 iOS 安装成功但功能不生效

通常检查这三项：

• 证书、Bundle Identifier、描述文件是否匹配。
• iOS 原生依赖是否已正确进入基座。
• 当前安装的是不是最新生成的基座。

8. 记住这几个结论

• 先把插件真实引入页面，再做基座。
• 只要涉及原生依赖或原生配置，优先用自定义基座。
• 运行项目时，必须选择 使用自定义基座运行。
• 如果重做基座时没有修改版本号，先卸载手机里的旧基座再安装新基座。
• 改了原生层代码或配置后，通常要重新制作基座。
• 出现“API 不存在”或“功能不生效”时，先检查是不是跑在最新的自定义基座上。