- 先搞清楚 .aix 是什么、有哪些环节会失败
- 第一步:导入报 “null”,先看体积
- 第二步:检查包结构和 components.json
- 第三步:导入成功但编译报 d8 failed / defined multiple times
- 第四步:确认这个扩展到底能不能用在你的设备上
- 懒人办法:aix 扩展检查器一步到位
- 常见问题
一句话结论:.aix 导入失败报 “null” 大概率是扩展体积超限或包结构不规范,编译时报 d8/重复类是两个扩展带了同名类——按「体积 → 包结构 → 重复类 → 权限」四步排查,或者把文件丢进 aix 扩展检查器,30 秒出诊断结果。
以下内容基于我们站内实测环境:App Inventor 2 中文网(Android 编译目标),测试机型为小米和华为各一台,测试的 .aix 来自社区常见扩展和自己用 Ant/JDK 打包的扩展。
先搞清楚 .aix 是什么、有哪些环节会失败
.aix 本质是一个 zip 包,里面装着:
classes.jar:扩展的 Java 代码assets/:扩展自带的素材components.json:组件描述文件(告诉 App Inventor 有哪些属性、事件、方法)
所以「导入失败」可能发生在三个环节:
- 导入环节:拖进扩展面板就报错,常见报错就是一句 “null”。
- 编译环节:导入成功,但打包 APK 时报 d8 failed / defined multiple times。
- 运行环节:装到手机上没反应,多数是权限或只支持 Android 的问题。
先弄清你卡在哪一环,再对症下药。
第一步:导入报 “null”,先看体积
导入失败只给一句 “null”、没有任何详细信息,这是 App Inventor 内部解析异常时抛出的空指针,被外层吞掉了。根据海外社区多年的反馈和我们的实测,单个 .aix 超过约 4MB 就经常导入失败,报的就是这个含糊的 null。
实测数据供参考:一个 7.6MB 的扩展(其中 classes.jar 约 2.2MB,其余是素材)在 MIT 官方版和中文网上都无法导入;压到 3.5MB 以内后正常导入。
排查与解决办法:
- 把 .aix 后缀改成 .zip,解压看看里面什么东西占了大头。
- 如果是 assets 里的图片、音频、模型文件太大:压缩图片(改 WebP)、音频降码率,或干脆不带素材、运行时从网上下载。
- 如果是 classes.jar 本身太大:说明打包时把整个依赖库都塞进去了。比如引了某个 SDK 却没排除它的依赖传递,jar 里可能带着整套 org.json、OkHttp 之类 App Inventor 已经内置的库。用 ProGuard/R8 做裁剪混淆,通常能砍掉一大半。
- 压完重新打包,再导入试试。
另外注意:项目整体超过 30MB 也会导致编译失败,原因和处理思路(压缩素材、改用原生组件)是一样的——原生组件的库不计入项目体积,能用内置组件替代的部分尽量用内置。
第二步:检查包结构和 components.json
体积没问题还报 null,多半是包本身不规范。逐项核对:
- Java 包名:必须是至少两级的形式(如
com.yourname.myext),不能是默认包。很多人自己打包时类放在默认包里,导入直接失败。 - components.json 必须存在且在包根目录,格式正确。手工编辑过的 components.json 特别容易出 JSON 语法错(多个逗号、漏个引号),报错同样是 null。
- @DesignerComponent / @SimpleObject 注解:扩展类必须带这些注解,纯 Java 类没有注解信息就无法生成组件描述。
- 打包方式:直接用 IDE 的「导出 jar」往往不行,要用 Ant 或命令行按 App Inventor 扩展的目录结构打,确认 zip 里第一层就是 assets/ 和 components.json,而不是多套了一层文件夹。
第三步:导入成功但编译报 d8 failed / defined multiple times
这个错误的含义很明确:项目里有两个来源带了同一个类。典型场景:
- 扩展 A 和扩展 B 都打包了同一个第三方库(比如都带了 gson 或某个 utils 类)。
- 扩展打包时把 App Inventor 已内置的库(org.json、HTTP 客户端等)也塞进了 classes.jar。
解决办法只有一个方向:去掉其中一个重复来源。
- 两个扩展冲突:删掉其中一个扩展,或找作者要一个「瘦身版」(没把依赖打进去的版本)。
- 单个扩展和内置库冲突:让扩展作者重新打包,打包时 exclude 掉 App Inventor 已有的依赖。
- 自己打包:在构建脚本里把公共依赖设为 provided,不要打进去。
第四步:确认这个扩展到底能不能用在你的设备上
两个常见「坑」,导入编译都正常、用的时候才发现:
- .aix 扩展只能用于 Android。iOS 和鸿蒙目标不加载扩展,如果你的项目还要编译 iOS IPA 或鸿蒙 HAP,就要优先考虑原生组件替代方案。
- 权限问题。蓝牙、定位、相机类扩展在 Android 6.0 以上需要运行时申请权限(Screen 的 AskForPermission),Android 12 以上蓝牙还需要 BLUETOOTH_SCAN / BLUETOOTH_CONNECT 权限。导入扩展时检查器列出的权限清单,就是你判断「这扩展要什么权限、会不会被国产手机后台干掉」的依据——华为、小米的省电策略对后台应用较严,涉及蓝牙后台收发的扩展尤其要留意。
懒人办法:aix 扩展检查器一步到位
上面四步每一步都要解压、翻文件、肉眼比对,其实可以交给工具:我们在 aix 扩展检查器里做了自动化诊断,把 .aix 拖进去就能看到:
- 能否正常解析(定位导入报 null 的具体原因)
- classes.jar 里的类清单,自动比对是否与其它扩展或内置库重复(对应 d8 报错)
- 实际体积和超限预警
- 声明的权限清单
文件在浏览器本地处理,不会上传。你拿到别人发的扩展、论坛下载的扩展,先过一遍检查器再导入,能省掉大部分反复试错的时间。
常见问题
问:报 “null” 有没有日志可以看? 目前编辑器端没有开放导入失败的详细日志,这也是社区一直反馈的问题。所以只能靠外部诊断:解压看包结构,或用检查器直接分析。
问:4MB 是硬限制吗? 不是官方公布的硬性数字,是实践中高于这个值失败概率明显上升的经验值。能否导入还和包内容有关,4MB 以内也不能保证百分之百成功,所以规范打包很重要。
问:别人的扩展我拿不到源码,怎么办? 拿不到源码也能排查体积和重复类问题(解压看 jar 内容即可)。如果是代码内部问题,只能联系作者。另外提醒一句:.apk 不能还原成 .aia,同理,拿不到源码的扩展出了问题也修复不了,选扩展时尽量选有源码、有维护的。
问:怎么判断该用扩展还是原生组件? 先查我们的组件中文文档——中文网已把 SQLite、MQTT、低功耗蓝牙、二维码生成等大量常用第三方扩展做成了原生组件,Android 全支持、多数同时支持 iOS 和鸿蒙,且不占项目体积。文档里没有的(如云推送、广告类),再考虑第三方 .aix。
扫码添加客服咨询