我是跟野兽差不了多少上次给社团做签到应用，需要在活动现场实时生成一个二维码，让到场的人扫一下就能完成签到。AppInventor2本身没有现成的二维码组件，我在社区里翻了一圈，最后选定QRCodeGenerator这个拓展——根据给定文本生成二维码，编译apk也不报错。整个用下来确实省心，但中间也踩过几个和"打包"相关的坑。这篇就把完整过程写出来：拓展从哪里拿、怎么导入、块逻辑怎么搭，以及为什么有些项目一模一样的写法，别人编译顺利，到你这里就卡住。
适合正在做AI2项目、需要在应用里动态生成二维码的开发者，尤其适合被"AI伴侣里一切正常，一编译APK就报错"折磨过的朋友。
1. 为什么"生成二维码"在AppInventor2里这么绕
AppInventor2本身不提供生成二维码的组件，这算是平台的先天限制。做这类功能通常有三条路：调用在线API、用WebView里塞JavaScript、或者用拓展。
调用在线API最省事，但问题也最明显。二维码内容要发给第三方服务器，应用一断网就变成白屏；在线接口通常有每分钟调用次数限制，签到场景几十个人同时操作的时候，很容易触发限流。WebView里跑JavaScript是另一条路，要自己维护一套HTML模板，还要处理AI2和JS之间的数据传递，写起来绕，调试起来更绕。拓展方案把编码逻辑全部放在本地执行，不依赖网络，没有调用次数限制，只需要关心"传文本进去、拿图片出来"，这个思路明显更干净。
QRCodeGenerator拓展的底层核心是ZXing库，也就是Zebra Crossing——业界非常成熟的条码图像处理库。二维码的生成原理不复杂：把一段文本按照QR码的编码规则拆分成数据段，加入纠错码，再按矩阵排列成黑白方块。ZXing把这一整套逻辑封装好了，拓展作者再把ZXing打包进Android拓展里，暴露成AI2能调用的方法。
这里有个关键点需要提前理解：AI2拓展不是随便把Java类扔进去就能用的，它对API访问权限有白名单限制，很多Java类在拓展里根本调不了。二维码生成涉及图形处理，恰恰需要用到一些不在白名单里的类，所以拓展必须把需要的ZXing核心类整个打包进.aix文件里，而不是依赖外部环境。这正是很多拓展"编译APK时出问题"的根源，后面会详细说。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 拓展的获取、导入与版本鉴别
QRCodeGenerator拓展并不是AI2官方内置的组件，需要自己下载.aix文件再导入。获取渠道主要是MIT App Inventor的官方拓展库和社区论坛，搜一下就能找到。
下载的时候要留个心眼，别看到"QRCode"就点。社区的拓展分好几个版本，有些是老作者维护的历史版，有些是后来人改的维护版，还有的人会拿不同ZXing版本重新编译。我的建议是优先选更新时间最近的版本，因为新版会适配当前的构建服务器，报错概率低得多。如果你拿到一个拓展没有文档而且下载时间是三年前的，建议直接换一个。
导入步骤本身没什么难度：
- 打开项目，进入Designer界面
- 在右侧面板找到Extensions（拓展）分类
- 点击Import（导入），选择下载好的.aix文件
- 导入成功后，Palette面板里会出现一个新的非可视组件，名字通常叫QRCodeGenerator、QrCodeGenerator或者类似写法
导入之后，把组件拖到Screen上，在列表里能看到这个组件的属性和方法列表。不同作者命名的差异很常见，比如方法的命名有的叫GenerateQRCode，有的叫CreateQRCode，参数顺序也未必一样。所以动手写块之前，先点一下组件的帮助文档或者查看方法签名，确认参数含义，这一步能省掉后面大量试错时间。
版本鉴别有个土办法，但很管用：把.aix文件的后缀改成.zip然后解压，看里面的目录结构。一个结构完整的二维码拓展，解压后应该能看到包含zxing相关类的库文件。如果你解压后只有个空壳子，方法声明存在但代码逻辑不完整，这种包装进去迟早出问题。另外，版本信息在component.json文件里也能看到，通过versionName和versionCode能判断新旧。
还有一个注意事项：同一个项目里不要同时导入多个功能重叠的二维码拓展。有的项目一开始加了一个，后来觉得不好用又加了一个，两个拓展同时存在，最后的构建阶段很容易因为类名冲突报Duplicate class错误。这个坑我踩过，后面排查链路里会详细讲。
3. 块逻辑怎么搭：从"文本输入"到"屏幕出码"
拓展导入成功后，块逻辑反而没什么复杂的。以一个最常见的场景为例：用户在一个文本输入框里填内容，点按钮，二维码就显示在旁边的图片组件上。
需要的组件一共四个：
- TextBox：输入内容
- Button：触发生成
- Image：显示二维码图片
- QRCodeGenerator1：非可视组件
在Blocks界面里，给Button的Click事件添加逻辑，过程是：调用QRCodeGenerator1的生成方法，把TextBox的文本作为参数传进去，得到返回值，然后赋值给Image的Picture属性。
一个值得注意的细节是，不同版本的返回类型有差异。有的拓展直接返回图片Base64字符串，这种最方便，直接赋给Image.Picture就能显示。有的拓展返回的是图片路径（比如存储在临时目录里的文件路径），这时候需要把路径传给Image.Picture，而不是传Base64。还有一些版本会提供输入文本、宽度、高度三个参数的重载方法，生成更大规格的二维码。
如果你第一次用某个拓展，不确定返回值类型，我的做法是先用一个Label组件把返回值显示出来看一眼，看到"data:image/png;base64,"开头就知道是Base64格式，如果看到"/storage/emulated/0/..."这种路径开头，就知道是文件路径。这个方法土，但比翻源码快。
在AI伴侣里测试的时候，第一次生成可能会感觉有半秒到一秒的延迟，这是正常的，ZXing在做编码计算。如果延迟超过两三秒，多半是传入的文本过长，QR码的容量有限。一个二维码最多能存约3KB的二进制数据，正常场景下存几百个字符完全够用。但你要是把一篇文章整篇塞进去，生成时间会明显变长，而且二维码会变得非常密集，手机经常扫不出来。
关于扫码识别率，我推荐在生成文本里控制内容长度。比如签到场景，存一个ID或者短链接就行，不要存一长串JSON。二维码边长建议设在300像素以上，太小的码密集区域会被压缩到看不清。块逻辑里如果拓展支持自定义尺寸，直接用默认值就行，这些参数是扩展作者测试过的。
4. "AI伴侣能跑、打包就挂"的根因拆解
这个标题既然说"编译apk不报错"，就说明很多人确实遇到过编译报错。AI2项目在AI伴侣里运行和在编译APK时，其实走的不是完全一样的机制，这是个非常容易忽视的差异点。
AI伴侣运行项目时，项目数据传给伴侣App，伴侣App本身是一个包含大量通用组件的巨大运行时。拓展的代码是基于这个运行时加载的，很多类在伴侣App里已经存在了，所以哪怕拓展本身有一些依赖缺失，AI伴侣里也能跑起来，因为缺失的部分碰巧被伴侣App里的其他组件覆盖了。
编译APK时情况完全不同。构建服务器要把你的项目代码和所有拓展代码冻结成一个单独的APK，服务器会重新对整个项目做一次打包。如果拓展的.aix文件里没有包含完整的依赖类，服务器编译阶段可能不会立即报错，但这个APK一运行，只要调到那个缺失的类，立刻NoClassDefFoundError崩给你看。更惨的是编译阶段直接失败，屏幕上只有一句笼统的错误信息。
QRCodeGenerator拓展能"编译apk不报错"，说明这个拓展的作者把所有需要的ZXing核心类都完整打包进了.aix文件，依赖是自包含的，构建服务器不需要额外下载任何东西。这就是为什么这个拓展口碑好的核心原因——不是作者编码多厉害，而是打包方式专业，做足了自包含。
反过来看那些会报错的拓展，问题往往就出在依赖没打全。有些作者在本地编译环境能跑，是因为本地Gradle缓存里有那些依赖库，但服务器上没有，一编译就缺类。所以判断一个拓展能不能用来编译APK，最关键的就是看它是不是自包含的。
还有一个细节影响编译是否报错：项目的编译设置。AI2的构建服务器默认有一组编译参数，大部分项目保持默认就好。你如果在项目里手动改过一些高级设置，比如开启Android SDK的某些选项，反而可能触发和拓展不兼容的问题。这类情况不算常见，但值得注意。
我在实际项目里的习惯是：导入一个新的拓展后，先不做任何逻辑，直接编译一次空APK。目的是验证这个拓展本身能不能被服务器正常处理。如果空项目都编译不过，果断换拓展版本，别再往项目里加逻辑了，否则排查起来会非常痛苦。
5. 编译APK报错排查链路
虽然QRCodeGenerator本身编译顺利，但项目里同时存在其他拓展或者历史遗留问题时，还是可能遇到报错。这里整理一条完整的排查链路，按照顺序走，能解决大部分编译失败的问题。
第一步，记录错误信息的核心词汇。AI2编译失败的页面只有一句错误提示，但里面的关键词非常重要。最常见的是"Program type already present"或者"Duplicate class"两种，都指向同一个问题：类重复。
"Duplicate class"的典型场景就是我前面说的，项目里同时导入了两个二维码拓展，或者导入了一个二维码拓展，又导入了另一个内部也包含ZXing代码的其他拓展（比如某些扫码枪组件）。解决方法很简单：把多余的拓展从项目中移除。在Designer界面里删除对应组件，然后重新导入需要的那个。
第二步，如果你的错误信息里有"Could not find class"或者"NoClassDefFoundError"，这种情况通常不是编译阶段报出来的，而是打包好的APK运行时崩溃。要处理的办法是换一个完整打包依赖的拓展版本。判断是否完整，可以用解压软件看.aix内容，找一下有没有zxing相关的类文件。
第三步，错误信息里出现"Invalid resource"或者某个图片资源找不到，这种一般是拓展里引用了特定的图标文件，但.aix打包时漏掉了。遇到这种情况基本也是换版本。
第四步，如果你确认拓展没问题，项目也没重复导入，但编译还是失败，把项目里所有其他拓展暂时移除，只保留QRCodeGenerator一个，再编译一次。如果成功了，说明是拓展之间的兼容问题。逐一把其他拓展加回来，每加一个编译一次，很快就能锁定是哪个拓展冲突。
第五步，清理浏览器缓存和构建缓存。AI2构建服务器端会缓存部分编译结果，偶尔在服务器更新后，旧的缓存记录会导致新的构建失败。退出项目回到项目列表，重新进入项目，再试一次。这个方法听着不靠谱，但确实解决过我的一次编译问题。
还有一类情况容易被人忽略：你下载的.aix文件本身下载不完整，文件被拦截或者字节缺失。用压缩软件打开时如果提示文件损坏，直接重新下载。这类问题也遇到过，排查到最后发现是下载环节出了问题。
总之，编译报错九成是拓展依赖或拓展冲突，剩下的一成才是项目本身的配置问题。理清这个思路，排查起来会快很多，不会病急乱投医。
6. 进阶玩法：批量出码与图片保存的小技巧
二维码生成逻辑跑通后，实际项目里很快会遇到下一个需求：批量生成。比如要给一个活动准备100个签到码，每个码对应不同的用户ID，让你手动输入100次显然不现实。
AI2处理批量任务的思路和普通编程类似——用循环。先把100个用户的ID放到一个List里，然后用foreach循环，每次取一个ID，调用QRCodeGenerator生成二维码，再保存到文件。保存文件需要用到File组件。给每个文件命名时加上用户ID做区分，避免互相覆盖。
批量生成时有一个性能问题值得提前知道：QRCodeGenerator在短时间内连续生成大量二维码，内存占用会上升，设备较差的情况下甚至可能出现卡顿。我的处理方式是做一个定时器控制节奏，每生成一个二维码后等待一小段时间再生成下一个，不要让循环一口气跑完。时间间隔设300到500毫秒，用户基本察觉不到延迟，又能显著降低卡死风险。
图片保存的位置也有讲究。AI2里保存文件到私有目录（private data）是最安全的选择，不需要申请权限，应用卸载时文件也会一并清理。但如果这批二维码要导出给其他人用，还是得保存到公共存储空间的选择，比如"下载"目录，这样用户能直接通过文件管理器找到。这种情况下需要处理存储权限，Android 11及以上版本的存储分区机制对公共目录的写入限制比较严格，有个简单的办法是把文件保存到应用专属的外部目录，然后通过系统分享功能把文件发出去，能绕开大多数权限限制。
还有一个很实用的小技巧：如果在二维码中间加Logo或者想提高容错率，得看拓展是否支持设置容错等级。ZXing的容错等级有L（约7%）、M（约15%）、Q（约25%）、H（约30%）四档。等级越高，二维码越密集，但识别时越抗遮挡和污损。日常场景用M就够，但如果二维码会打印出来贴在不平整的物体表面，建议用H。部分QRCodeGenerator拓展把容错等级当参数暴露出来了，有的没有，这个要看具体版本。
如果你拿到一个QRCodeGenerator拓展，想要中间带Logo的效果，最简单的替代方案是：先用拓展生成二维码，再把Logo图片和处理后的二维码在另一款图像合成工具里合并。AI2项目里可以把二维码Base64字符串传给其他组件做进一步处理，不过这会增加复杂度，我的建议是别在AI2里折腾Logo合成，用外面工具合成好，再作为资源放进来，稳定性高得多。
关于二维码色彩，保持经典的黑白配色最稳妥。深色背景配浅色方块、或者反色二维码，虽然视觉上更酷，但很多扫码App对反色码的支持并不好。普通用户用的微信、支付宝扫反色码，经常无法识别。QRCodeGenerator拓展一般生成的是默认黑色，你只需要保证背景是白色就行。
我个人的习惯是，每次拿到新的生成函数，都会先用固定的文本生成一次，然后用不同手机的扫码功能各扫一遍。因为二维码的实际效果和生成器设置、扫码App的宽容度都有关系，扫得出来才是硬道理。生成逻辑改过之后也要重新扫码验证，尤其是改了容错等级或者尺寸参数之后。
最后分享一个踩坑经验：如果项目在AI伴侣里运行一切正常，不要以为就万事大吉了，一定要在正式发布之前做一次完整的APK编译。编译通过后再把APK装到手机上跑一遍，确认生成的二维码能被正常识别。有的问题只在完整包运行时才会暴露，而这个拓展之所以值得推荐，就是因为它真的能做到"编译apk不报错"，这一条对AI2开发者来说太宝贵了。