小鹅通1. 先分清一件事：测试版本不是"能装上手机就能用"
开发uniapp的Android端，很多人最早搞混的就是测试包和正式包。我见过不止一个项目，开发阶段在HBuilderX里点"运行到手机"，装到设备上一切正常，就以为大功告成；结果走完"发行"流程打出一个release包，装上之后登录失效、接口全挂、第三方分享点不动，甚至直接闪退，然后在群里问"为什么正式包和调试包行为不一样"。
这不是玄学，而是测试版本和发行版本在Android平台上本来就是两套逻辑。先把这个底层差异讲透，后面很多坑你就能自己判断了。
1.1 同一个uniapp项目，为什么会有这么多包
一个uniapp项目在Android端交付时，至少会出现这些形态：
- HBuilderX直接点运行生成的调试包，依赖的是标准调试基座或自定义调试基座；
- 云打包生成的测试安装包（一般也叫test包、或者你手动打的release包但未上架）；
- 云打包或离线打包生成的发行包，用于上传各大安卓应用市场；
- 如果分了渠道，还有各市场的渠道包（小米、华为、OPPO、vivo、应用宝等）。
很多人把"云打包"直接等同于"正式版"，这是个误区。云打包只是构建方式，打出来的包本身并没有自动区分"测试"和"发行"——真正区分它们的是基座类型、签名证书、打包配置这三样东西。后面的章节我会逐个展开。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
1.2 测试版和发行版在Android端的三层差异
第一层是运行环境。调试包跑在调试基座里，调试基座相当于一个壳，集成了官方模块、调试服务、以及连接HBuilderX的通道。你点"运行"的时候，HBuilderX会先把这个壳装到手机上，再把JS代码同步进去。所以你在调试包里能用的能力，取决于基座里有没有编译对应模块。而发行包是把你的页面和原生模块一起打包成一个独立App，不依赖任何基座。
第二层是签名。Android系统要求所有安装包必须有签名。调试阶段HBuilderX默认使用调试证书（debug.keystore），所有用调试证书签名的包都能覆盖安装；但到了发行阶段，你必须用自己的正式证书签名。正式证书和调试证书的SHA1、包名组合一旦不同，系统就会认为这是两个App，直接覆盖安装会报"安装失败：签名不一致"。
第三层是配置与权限。打包时选择的模块权限、targetSdkVersion、渠道信息、隐私弹窗、混淆配置，都会影响最终包体的行为。很多release包出问题，不是代码问题，而是打正式包时漏勾了某个模块权限，或者targetSdkVersion调整后运行时权限行为变了。
| 对比项 | 测试/调试包 | 发行包 |
|---|---|---|
| 基座依赖 | 依赖标准或自定义调试基座 | 独立APK，不依赖任何壳 |
| 签名证书 | 调试证书（debug.keystore） | 正式证书（需自行生成） |
| 包名限制 | 基座包名固定，不能用于上架 | 可自定义包名，但要全网唯一 |
| 调试能力 | 支持remotedebug、HBuilderX日志输出 | 默认关闭调试日志 |
| 应用市场 | 无法上架（签名/包名不合规） | 可上架审核 |
1.3 什么时候该用测试版，什么时候该切发行版
我的经验是分阶段管理，不要混着用：
- 功能开发阶段：直接用HBuilderX真机运行，标准基座够用，追求"改代码秒同步"，不要频繁打正式包。
- 集成原生插件/第三方SDK阶段：标准基座没有内置对应模块，必须做自定义基座，否则运行时会提示模块不存在。这个阶段你打的包还属于测试包，但基座换成自定义的。
- 功能验证、联调、提测阶段：用云打包出一个release测试包发给测试同事。注意，这个包虽然叫测试包，但建议直接用正式证书签名，因为要验证证书、权限、targetSdkVersion等真实发行环境的问题。
- 上架阶段：云打包或离线打包生成正式发行包，渠道包分开打。
这里有个很容易踩的坑：测试同事装的是你调试证书签名的包，后面你换了正式证书再打包，测试手机必须卸载旧包才能安装新包。如果测试机上有多个环境的包，千万记得每台设备上只保留一个签名来源的安装包，否则安装失败会浪费一整天去排查。
2. 开发阶段的"测试版本"体系：从标准基座到自定义基座
2.1 标准基座和自定义基座：开箱即用的代价
HBuilderX里"运行到手机或模拟器"时，默认使用的基座叫标准基座。它的好处是免配置，装上就能跑uniapp页面。坏处是只包含基础模块和一些官方常用模块——比如你要用蓝牙、NFC、原生扫码、第三方登录等，标准基座未必有编译入口。
判断标准很简单：你项目里用了某个plus API或uni API，运行到手机时报"xxx is not a function"，或者日志里出现模块未打包的提示，那基本就是基座里没这个能力。这时候你就得切到自定义基座。
标准基座适合纯页面级开发和只用到基础API的项目。它内置的模块能覆盖90%常见的业务开发，像网络请求、本地存储、地图、支付、推送这些其实都有，但原生插件和自定义原生功能它一概不支持。
2.2 什么时候必须做自定义基座
触发自定义基座需求的情况通常有三种：
- 项目里引入了uniapp原生插件（不管是DCloud插件市场的，还是自己写的），标准基座不知道你的插件代码，运行不了。
- manifest.json里勾选了需要原生层面的模块，这些模块在标准基座里没有对应实现，需要在自定义基座中重新编译。