核心路径是uni-app-cli命令行构建:需配置UNI_PLATFORM、ANDROID_HOME/Java环境,动态注入渠道参数,签名与分包由Gradle/gym接管,CI中须锁定Node版本、管控缓存及私钥权限。

uni-app 项目要真正落地 CI/CD 自动打包,核心不是“能不能”,而是“在哪打、怎么注入配置、如何避免环境污染”。云打包服务(如 DCloud)虽快,但无法接入流水线;本地安心打包又受限于平台(iOS 必须 Mac);最可控、最通用的路径是 uni-app-cli + npm run build:app-plus 驱动的命令行构建,再配合平台特定的签名与分包逻辑。
用 uni-app-cli 替代 HBuilderX 打包
CI 环境里没有图形界面,HBuilderX 的“发行 → 原生 App 云打包”按钮完全不可用。必须退回到 CLI 层面,靠脚本驱动构建流程:
-
npm install -g @dcloudio/vue-cli-plugin-uni不需要全局安装插件,项目依赖中已含@dcloudio/uni-cli-shared - 确保
package.json中有类似"build:app-plus": "cross-env NODE_ENV=production UNI_PLATFORM=app-plus vue-cli-service uni-build"的 script - Android 构建需提前设置
ANDROID_HOME和JAVA_HOME,否则会卡在Could not find tools.jar或No Android SDK found - iOS 构建必须在 macOS 上运行,且 Xcode CLI 工具已安装(
xcode-select --install),否则gym或xcodebuild会直接报错退出
渠道参数和 Openinstall AppKey 怎么动态注入
硬编码在 manifest.json 里的 android:value 或 ios:OpeninstallAppKey 会导致所有渠道包共用同一份配置,失去追踪意义。必须在构建前完成替换:
- 不要直接改
manifest.json—— Git 会把它标为 dirty,破坏构建可重现性;推荐用json5+fs.writeFileSync脚本,在 CI 启动时按$CHANNEL环境变量写入对应值 - Android 渠道号建议走
build.gradle的buildConfigField注入,再在 Java 层读取,比改AndroidManifest.xml更安全 - iOS 的 Openinstall AppKey 可通过
fastlane的update_info_plist插件动态写入Info.plist,避免手动修改源码 - 注意:uni-app 的
UNI_PLATFORM=app-plus构建过程会把manifest.json编译进assets/data,所以替换必须在vue-cli-service uni-build之前完成
签名、混淆、多 APK 分包这些事谁来干
CLI 构建只产出未签名的 .apk(Android)或 .ipa(iOS)原始包,签名和优化必须由后续步骤接管:
- Android:用
jarsigner+zipalign是基础,但推荐用 Gradle 的assembleRelease任务替代 CLI 构建,更可控;关键配置在app/build.gradle的signingConfigs块里,密钥密码应从keystore.properties加载,该文件不进 Git - iOS:
gym默认调用xcodebuild archive,签名靠match同步证书,export_method决定是app-store还是ad-hoc;若用企业签名,export_options.plist必须显式指定method: enterprise - APK 分包(ABI split)需在
app/build.gradle中开启splits { abi { enable true } },否则一个包含所有 so 库,体积暴涨 - 混淆:Android 的
minifyEnabled true必须配proguardFiles,uni-app 的 JS 混淆靠terser-webpack-plugin,但原生层混淆要单独处理
GitHub Actions / Jenkins 里最容易漏掉的三件事
很多团队跑通了“能打包”,却在交付环节翻车,问题往往出在构建上下文丢失、缓存污染或权限错配:
- Node.js 版本必须锁定:uni-app CLI 对 Node.js 有明确兼容范围(v16.14+ ~ v20.x),CI 中用
actions/setup-node@v4指定node-version-file: '.nvmrc',比写死版本更可靠 - Gradle / CocoaPods 缓存不能全盘复用:Android 的
~/.gradle/caches和 iOS 的Pods/目录若被跨分支复用,可能引发Could not resolve androidx.xxx或incompatible Swift version - 私钥和证书权限:Jenkins 里
.jks文件权限若为 644,jarsigner会拒绝使用;GitHub Actions 中secrets注入的 key 文件需用base64 -d解码并chmod 600,否则签名失败静默无提示
真正难的从来不是“怎么触发一次打包”,而是让每次构建输出都具备可追溯性(Git commit、build number、channel)、可验证性(签名指纹、渠道标识是否写对)、可回滚性(产物命名带时间戳和 hash)。这些细节不写进脚本,就永远在 release 前半小时手动救火。











