简介：这份资源是 UNIAPP 安卓离线 SDK 的完整开发包，版本号为 Android-SDK@3.96.81954-20231106，面向使用 uni-app 进行跨平台开发、需要脱离网络环境构建与调试 Android 应用的开发者，尤其适合仍需维护旧版本打包插件、关注版本兼容性的团队。压缩包共 421 个文件，约 275.91MB，以 152 个 aar 库文件为核心，涵盖 uniapp-v8、百度、高德、直播推流、媒体处理等模块，另含 97 个 js、14 个 java、12 个 gradle 及 xml、json、properties 等配置与资源文件，构成完整的本地编译与运行环境。目前已有 772 人学习下载。借助该 SDK，读者可获得离线打包所需的编译器、运行时与 API 接口，在无网络条件下完成应用构建、调试与打包，并利用其对旧版插件的兼容能力，降低因 SDK 升级引发的适配风险，保证项目在不同 Android 版本上的稳定运行。
1. 离线打包这件事，为什么总在“最后一公里”翻车
做过 uni-app 跨平台项目的同学，大概率都经历过这样的场景：HBuilderX 云打包排队排到怀疑人生，证书突然失效，或者企业内网根本不允许把代码传到云端。这时候，安卓离线 SDK 就成了绕不开的选项。标题里的Android-SDK@3.96.81954-20231106，本质上就是一套让 uni-app 项目脱离云端、在本地 Android 工程里跑起来的工具包。它解决的不是“能不能开发”的问题，而是“能不能自主可控地出包”的问题。适合谁？适合需要私有化部署、需要集成原生插件、或者被云打包配额卡住脖子的团队。但离线 SDK 的坑，从来不在下载和解压，而在版本对齐、资源替换和原生工程配置这三件事上。下面我按自己踩过的顺序，把这条路拆开讲。
2. 先把版本号拆明白：3.96.81954 到底锁了什么
2.1 版本号不是随便起的，它对应 HBuilderX 的发行批次
很多人拿到 SDK 压缩包，第一反应是直接解压丢进 Android Studio，结果一编译就报资源找不到。问题出在没搞懂版本号的对应关系。3.96.81954里的3.96是主版本线，81954是构建号，20231106是日期戳。这套 SDK 必须和同批次的 HBuilderX 配合使用——你用 3.99 的 HBuilderX 生成本地打包资源，却拿 3.96 的 SDK 去编译，大概率会在app-plus资源解析阶段翻车。
常见做法是：先确认你团队当前锁定的 HBuilderX 版本，然后去官方归档里找对应批次的 SDK。如果找不到完全一致的，宁可升级 HBuilderX 到 SDK 对应的版本，也不要混用。我一般会在项目根目录放一个version.lock文件，把 HBuilderX 版本、SDK 构建号、AGP 版本三样东西写死，避免半年后换人接手时一脸懵。
2.2 SDK 包里的目录结构，哪些必须动，哪些碰都别碰
解压后你会看到类似这样的结构：
Android-SDK@3.96.81954-20231106/ ├── SDK/ │ ├── libs/ │ ├── assets/ │ ├── res/ │ └── AndroidManifest.xml ├── HBuilder-Integrate-AS/ │ ├── app/ │ ├── build.gradle │ └── settings.gradle └── Readme.txtSDK/目录是核心，里面的libs放的是uniapp-v8-release.aar这类运行时库，assets放的是data目录下的 JS 引擎资源和apps目录下的应用资源。HBuilder-Integrate-AS/是一个最小化的 Android 工程模板，用来演示怎么把 SDK 嵌进去。
必须动的只有三处：assets/apps/你的应用ID/www/目录，这里要放 HBuilderX 导出的本地打包资源；AndroidManifest.xml里的包名和权限；build.gradle里的applicationId和签名配置。其他文件，尤其是libs下的 aar，除非官方明确说可以替换，否则不要动。我见过有人为了“精简包体积”删了assets/data下的某个.so，结果真机上一启动就黑屏，查了两天才发现是 V8 引擎的依赖被误删。
2.3 本地打包资源怎么导出，路径别搞错
在 HBuilderX 里，选中项目 → 发行 → 原生App-本地打包 → 生成本地打包App资源。导出后会得到一个__UNI__XXXXXX格式的文件夹，里面是www目录。这个文件夹要整个复制到SDK/assets/apps/下，并且把AndroidManifest.xml里的dcloud_appkey和package改成你自己的。
这里有个细节：assets/apps/下可以放多个应用资源，SDK 会根据dcloud_appkey去匹配。如果你只放了一个，但AndroidManifest.xml里的 key 写错了，运行时会直接提示“未找到对应资源”。我一般会在复制完之后，用adb shell进到设备里ls /data/data/你的包名/看一眼，确认apps目录被正确解压过去了。
3. 把 SDK 嵌进 Android Studio：从零到出包的最小步骤
3.1 新建工程还是直接用模板，我建议用模板改
如果你手上没有现成的 Android 工程，直接用HBuilder-Integrate-AS模板最省事。用 Android Studio 打开这个目录，等待 Gradle 同步完成。同步过程中最容易卡在compileSdkVersion和targetSdkVersion上——模板里写的可能是 30 或 31，而你本地装的是 33 或 34。改app/build.gradle里的这两个值，改成你本地已安装的版本，别硬下新 SDK。
// app/build.gradle 关键片段 android { compileSdkVersion 33 defaultConfig { applicationId "com.example.yourapp" // 改成你自己的包名 minSdkVersion 21 targetSdkVersion 33 versionCode 1 versionName "1.0" ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' // 按需保留 } } signingConfigs { release { storeFile file("../your.keystore") storePassword "yourpassword" keyAlias "youralias" keyPassword "yourpassword" } } buildTypes { release { signingConfig signingConfigs.release minifyEnabled false // 离线 SDK 不建议开混淆，除非你很清楚规则 } } }abiFilters这一项，如果你的应用不需要支持 32 位设备，可以只留arm64-v8a，包体积能小不少。但要注意，如果你的原生插件里有 32 位的.so，只留 64 位会在运行时崩。minifyEnabled我建议先关掉，等整个流程跑通再考虑开混淆，否则报错信息会被混淆得亲妈都不认识。
3.2 把 SDK 作为 module 引入，而不是直接拷 aar
模板工程里已经配好了settings.gradle，把SDK目录作为一个 module 引入：
// settings.gradle include ':app', ':SDK' project(':SDK').projectDir = new File('../SDK')然后在app/build.gradle的dependencies里加：
implementation project(':SDK')这样做的好处是，SDK 的AndroidManifest.xml会和主工程的合并，权限、Activity 声明自动带进来。如果你直接拷 aar 到libs再implementation files('libs/xxx.aar')，合并规则会变得很麻烦，尤其是provider和service的声明容易丢。
3.3 第一次编译报错，先看这三个地方
编译失败时，按这个顺序排查：
第一，看SDK/build.gradle里的compileSdkVersion是否和主工程一致。不一致会报Manifest merger failed。
第二，看AndroidManifest.xml里的package属性是否和applicationId一致。不一致会报Namespace not specified。
第三，看assets/apps/下的应用资源目录名是否和dcloud_appkey匹配。不匹配会在运行时报Failed to find app resource。
我一般会在app/build.gradle里加一段applicationVariants.all，把每次编译的dcloud_appkey和资源路径打印出来，方便核对：
android.applicationVariants.all { variant -> variant.outputs.all { println "dcloud_appkey: ${variant.mergedFlavor.manifestPlaceholders.dcloud_appkey}" println "assets path: ${project.projectDir}/src/main/assets/apps" } }这段代码不参与打包逻辑，只是调试用，跑通后可以删掉。
4. 避坑：离线 SDK 最常见的五个翻车现场
4.1 白屏，但日志里没有任何报错
现象：应用启动后停在启动图，或者直接白屏，logcat里只有I/WebView之类的系统日志。
原因：assets/apps/下的www目录没有被正确解压到应用私有目录。离线 SDK 在首次启动时会把assets里的资源拷贝到/data/data/包名/apps/下，如果拷贝过程中断了，或者www目录里缺了manifest.json，就会白屏。
解决：用adb shell进到设备，ls /data/data/你的包名/apps/__UNI__XXXXXX/www/，看manifest.json和app-service.js在不在。不在的话，检查assets/apps/下的目录名是否和dcloud_appkey完全一致，包括大小写。
4.2 原生插件调用失败，提示“未找到模块”
现象：JS 里调用uni.requireNativePlugin('XXX')返回null，或者直接报module not found。
原因：原生插件的 aar 没有被打进 APK，或者插件的package名和dcloud_uniplugins.json里注册的不一致。
解决：在app/build.gradle里确认插件的 aar 被implementation了。然后检查assets/dcloud_uniplugins.json，这个文件是 SDK 用来注册原生插件的，格式如下：
{ "nativePlugins": [ { "plugins": [ { "type": "module", "name": "YourPlugin", "class": "com.example.plugin.YourPlugin" } ] } ] }name要和 JS 里requireNativePlugin的参数一致，class要是完整的类路径。这个文件如果漏了，插件就算打进 APK 也调不到。
4.3 真机安装后闪退，模拟器正常
现象：Android Studio 的模拟器上跑得好好的，一装到真机就闪退。
原因：abiFilters和真机的 CPU 架构不匹配。模拟器通常是 x86_64，而真机是 arm64-v8a。如果你的abiFilters只写了x86_64，真机必崩。
解决：把abiFilters改成'armeabi-v7a', 'arm64-v8a'，或者用splits按 ABI 分包。我一般会在defaultConfig里加：
ndk { abiFilters 'armeabi-v7a', 'arm64-v8a' }然后flutter或react-native项目里如果有 x86 的.so，记得排除掉。
4.4 热更新失效，提示“wgt 包不合法”
现象：用plus.runtime.getProperty拿到版本号后，下载 wgt 包安装失败。
原因：离线 SDK 的 wgt 热更新依赖assets/apps/下的www目录作为基准版本。如果你在AndroidManifest.xml里改了versionCode或versionName，但没有同步更新www/manifest.json里的版本号，SDK 会认为 wgt 包和当前版本不匹配。
解决：每次发版，www/manifest.json里的version.name和version.code必须和build.gradle里的versionName、versionCode一致。我一般会写一个sync_version.sh脚本，在 CI 里自动同步这两个值。
4.5 打包后 APK 体积暴涨，超过 100MB
现象：一个简单的 uni-app 项目，离线打包后 APK 有 100 多 MB。
原因：assets/apps/下放了多个历史版本的应用资源，或者libs里保留了所有 ABI 的.so。
解决：清理assets/apps/下不需要的__UNI__XXXXXX目录，只保留当前版本。然后在build.gradle里加splits：
splits { abi { enable true reset() include 'armeabi-v7a', 'arm64-v8a' universalApk false } }这样会按 ABI 打出多个 APK，单个体积能降 30% 到 40%。如果必须打一个通用包，那就只能接受体积，或者用abiFilters只留arm64-v8a。
5. 进阶：把离线打包塞进 CI，以及一个验证清单
5.1 用命令行出包，摆脱 Android Studio
Android Studio 的图形界面适合调试，但 CI 里必须用命令行。在工程根目录执行：
./gradlew assembleRelease \ -Pandroid.injected.signing.store.file=../your.keystore \ -Pandroid.injected.signing.store.password=yourpassword \ -Pandroid.injected.signing.key.alias=youralias \ -Pandroid.injected.signing.key.password=yourpassword这四个参数分别对应签名文件、签名密码、别名、别名密码。如果build.gradle里已经配了signingConfigs，可以省略这些参数，直接./gradlew assembleRelease。产物在app/build/outputs/apk/release/下。
CI 里还需要注意：local.properties里的sdk.dir要指向 CI 环境的 Android SDK 路径，或者用ANDROID_HOME环境变量。我一般会在 CI 脚本里加一句echo "sdk.dir=$ANDROID_HOME" > local.properties，避免路径写死。
5.2 一个可以贴在墙上的验证清单
每次出包前，按这个清单过一遍，能省掉 80% 的返工：
| 检查项 | 正确状态 | 常见错误 |
|---|---|---|
| HBuilderX 版本 | 与 SDK 构建号一致 | 混用不同批次 |
assets/apps/目录名 | 与dcloud_appkey一致 | 大小写不匹配 |
www/manifest.json版本号 | 与build.gradle一致 | 忘记同步 |
abiFilters | 包含真机架构 | 只留 x86_64 |
dcloud_uniplugins.json | 插件类路径完整 | 漏写或拼错 |
| 签名配置 | signingConfigs已配 | 用 debug 签名发版 |
minifyEnabled | 先关后开 | 一上来就开混淆 |
这张表我打印出来贴在工位上，每次发版前扫一眼，比看文档快。
5.3 一个我踩过的坑：别在assets里放中文文件名
有一次为了图方便，把应用资源目录命名成了我的应用，结果在 Windows 上编译正常，到 macOS 的 CI 上就报Invalid file path。原因是assets目录下的文件名会被原样打进 APK，而不同系统对中文路径的编码处理不一致。后来统一改成__UNI__加数字的格式，再也没出过问题。
离线 SDK 这条路，说到底就是“版本对齐、资源放对、签名配好”三件事。但每件事下面都有十几个小坑，踩过一次就记住了。我现在的习惯是，每次升级 SDK 之前，先在一个独立分支上跑通最小 Demo，确认没问题再合到主分支。希望帮到你。
本文还有配套的精品资源，点击获取
