vue3 ts cli uniapp 项目中如何使用 uni ext api

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

好的，我们来分析一下你在 Vue3 + TypeScript 的 uni-app 项目中使用 uni ext api 时遇到 uni-[对应api的name] not found 异常的问题。

根据你的问题描述和知识库中的内容，这个报错通常指向两个核心原因：API 的引入方式不正确，或者运行环境没有包含该 API。

核心原因与解决方案

uni ext api 是一类特殊的 API，它们虽然仍以 uni. 开头调用，但已经被剥离为独立的 uni_modules 插件，不再跟随 HBuilderX 或 uni-app 的内核一起发布。这导致它们的使用方式和内置 API 有本质区别。

1. 必须像使用普通插件一样，从插件市场下载并配置到项目中

uni ext api 不能直接像 uni.getSystemInfo() 这样调用。你必须先从 DCloud 插件市场将该 API 对应的 uni_modules 插件安装到你的项目中。

例如，如果你想使用 uni.getBatteryInfo (获取设备电量)，你需要找到对应的 uni-getBatteryInfo 插件，并将其导入到你的 uni_modules 目录下。知识库明确指出：“不常用的API剥离为uni_modules插件，但仍使用uni.开头的API”。

2. 确认 package.json 中的注册声明已正确配置

这是最关键的一步。uni ext api 需要在插件的 package.json 文件中编写注册声明，才能将方法挂载到 uni 对象上。知识库原文强调：“在入口文件export的API，必须在package.json中编写注册声明”。

当你从插件市场导入 ext api 插件后，请检查其 package.json 文件，确保其中包含了正确的注册声明。这个声明通常由插件作者编写，如果你是自己开发或修改了插件，需要自行添加。缺少这个声明是导致 not found 错误的常见原因。

3. 注意 UTS 插件的运行限制

如果这个 ext api 是用 UTS 实现的，你需要特别注意以下几点（均来自知识库）：

• iOS 真机运行必须打包自定义基座。
• Android 上涉及 aar、jar、so 等三方 SDK 时，也需要打包自定义基座才能真机运行。
• 如果你的项目是通过 CLI 创建的，需要确保所有 @dcloudio 相关的依赖版本完全一致，否则可能出现编译失败。你可以参照知识库中提供的版本检查和修复方法。

操作步骤建议

1. 确认插件来源：去 DCloud 插件市场 搜索你需要的 ext api，例如你要找的是电量 API，就搜索 uni-getBatteryInfo。
2. 下载并导入：在 HBuilderX 中，通过插件市场将对应的 uni_modules 插件导入到你的项目。
3. 检查配置：打开该插件目录下的 package.json 文件，确认其中是否包含了将 API 注册到 uni 对象的声明。如果是官方提供的插件，这一步通常已经完成。
4. 重新运行：在 HBuilderX 中停止当前运行，并重新运行到你的目标平台。如果是 iOS 或使用了三方 SDK 的 Android，记得先打包自定义基座。
5. CLI 项目特别注意：如果你使用 CLI 创建的项目，请检查 package.json 中 @dcloudio/uni-uts-v1 的版本是否与其他 @dcloudio/ 依赖（如 @dcloudio/uni-app）的版本号完全一致。不一致会导致编译失败。

总的来说，uni-[api的name] not found 这个错误，核心就是 uni-app 运行时在 uni 对象上找不到你调用的方法，根本原因是该 ext api 插件没有被正确安装或注册。按照上述步骤排查，问题应该就能解决。