UNI-APP 打包构建 APK

前言

• 由于使用 HbuilderX 的图形化界面有相对完整的教程，这里不在赘述
• 本文主要使用 Android Studio 进行打包和使用纯命令的进行打包
• 同步可以参考UNI-APP 官方 App 离线打包教程：
  • Android 原生工程配置
  • Android 打包发行
  • 本地 Android 环境配置时可参照App 云端打包环境

一、WINDOWS（在线 - 纯命令版）

依赖

• HbuilderX 编辑器（根目录自带 CLI）

其他前置准备

• 登录 HbuilderX 的 DCloud 账号

实现原理

• 利用 RPC 调用 HbuilderX 编辑器的功能
• 相当于手动打开 HbuilderX 并触发“发行”功能，所以极度依赖 WINDOWS 的图形化界面

操作步骤

1. 编写配置文件，放在项目根目录即可¹

// hxconfig.json

{
    //项目名字或项目绝对路径
    "project": "project-name",
    //打包平台 默认值android  值有"android","ios" 如果要打多个逗号隔开打包平台
    "platform":"android",
    //是否使用自定义基座 默认值false  true自定义基座 false自定义证书
    "iscustom": false,
    //打包方式是否为安心打包默认值false,true安心打包,false传统打包
    "safemode": true,
    //android打包参数
    "android": {
      //安卓包名
      "packagename":"com.company.www",
      //安卓打包类型 默认值0 0使用自有证书 || 1使用公共证书 || 2使用老版证书 || 3使用云端证书
      "androidpacktype":"0",
      //安卓使用自有证书自有打包证书参数
      //安卓打包证书别名,自有证书打包填写的参数
      "certalias":"test",
      //安卓打包证书文件路径,自有证书打包填写的参数
      "certfile":"C:/Users/15770/Desktop/project/test-store.keystore",
      //安卓打包证书密码,自有证书打包填写的参数
      "certpassword":"cert-pwd",
      //安卓平台要打的渠道包 取值有"google","yyb","360","huawei","xiaomi","oppo","vivo"，如果要打多个逗号隔开
      "channels":""
    },
    //是否混淆 true混淆 false关闭
    "isconfusion":false,
    //开屏广告 true打开 false关闭
    "splashads":false,
    //悬浮红包广告true打开 false关闭
    "rpads":false,
    //push广告 true打开 false关闭
    "pushads":false,
    //加入换量联盟 true加入 false不加入
    "exchange":false
}

2. 添加 CLI 的环境变量
3. 执行以下前 3 条命令即可完成打包

# 1. 打开 HbuilderX
cli open

# 2. 打开项目（由于 cli 所在的位置不是项目路径，所以基于 cli 的命令只能用绝对路径，以下同理）
cli project open --path C:/Users/15770/Desktop/project

# 3. 读取配置文件进行打包
cli pack --config C:/Users/15770/Desktop/project/hxconfig.json

# 4. 关闭项目
cli project close --path C:/Users/15770/Desktop/project

4. 最终效果如图，路径project\dist\release\apk

二、WINDOWS（离线 - Android Studio 版）

依赖（首次构建需要联网安装依赖）

• 【可选】Chocolatey（Software Management for Windows）：这是 WINDOWS 软件包管理工具，在本文中的唯一作用就是为下面的工具包提供方便的安装途径
• 【必选 1/5】JDK：可用JDK 13（手动安装）
• 【必选 2/5】Gradle：可用Gradle 6.5，核心工具，用途类似maven（可以通过 AS 自动拉取）
• 【必选 3/5】gradle-plugin：可用com.android.tools.build:gradle:4.1.1（可以通过 AS 自动拉取）
• 【可选】Android SDK：主要提供sdkmanager命令执行的环境（可以通过 AS 自动拉取）
  • 【必选 4/5】android：可用platforms;android-30，开发者可以根据需要下载和安装不同的平台版本，以便为特定版本的 Android 系统开发和测试应用。包含了该版本的 Android 核心库、资源和 API，确保应用能够使用该版本特有的功能
  • 【必选 5/5】build-tools：可用build-tools;30.0.3，用于构建和打包 Android 应用的工具集合。这些工具包括编译器、打包工具等，帮助开发者将应用的源代码转换成可以在设备或模拟器上运行的 APK 或 AAR 文件

其他前置准备

• 制作 Android 的项目模板，请参照《第五章：Android 项目模板制作》

实现原理

• 通过 Android Studio 图形化界面构建 APK

操作步骤

1. 安装 Chocolatey CLI【可自行选择其他方式安装依赖】

# 使用 cmd 进行安装，直接在小黑窗中执行以下命令
@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

2. 基于 choco 安装 JDK（五大核心依赖之一：JDK）

choco install openjdk13
# 所在路径 C:\Program Files\OpenJDK\jdk-13.0.2

3. 使用 Android Studio 打开《第五章：Android 项目模板制作》创建的模板，并配置好SDK（五大核心依赖之二：android & build-tools）

4. 打开设置，修改指定版本的JDK

5. 点击构建项目，构建成功后继续生成 APK，按以下步骤选择和填充信息即可，这一步依赖于前面的准备工作，并且会联网拉取最终的两个依赖（五大核心依赖之二：Gradle & gradle-plugin）

6. 最终效果如图，路径HBuilder-Integrate-AS\simpleDemo\release

三、WINDOWS（离线 - 纯命令版）

依赖

• 【可选】Chocolatey（Software Management for Windows）：这是 WINDOWS 软件包管理工具，在本文中的唯一作用就是为下面的工具包提供方便的安装途径
• 【必选 1/5】JDK：可用JDK 13（手动安装）
• 【必选 2/5】Gradle：可用Gradle 6.5，核心工具，用途类似maven（可以通过代码自动拉取）
• 【必选 3/5】gradle-plugin：可用com.android.tools.build:gradle:4.1.1（可以通过代码自动拉取）
• 【可选】Android SDK：主要提供sdkmanager命令执行的环境（手动安装，并在local.properties指定SDK路径）
  • 【必选 4/5】android：可用platforms;android-30，开发者可以根据需要下载和安装不同的平台版本，以便为特定版本的 Android 系统开发和测试应用。包含了该版本的 Android 核心库、资源和 API，确保应用能够使用该版本特有的功能
  • 【必选 5/5】build-tools：可用build-tools;30.0.3，用于构建和打包 Android 应用的工具集合。这些工具包括编译器、打包工具等，帮助开发者将应用的源代码转换成可以在设备或模拟器上运行的 APK 或 AAR 文件

其他前置准备

• 制作 Android 的项目模板，请参照《第五章：Android 项目模板制作》

实现原理

• 通过 windows 的gradlew脚本处理构建 APK

操作步骤

1. 安装 Chocolatey CLI【可自行选择其他方式安装依赖】

# 使用 cmd 进行安装，直接在小黑窗中执行以下命令
@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "[System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

2. 基于 choco 安装 JDK（五大核心依赖之一：JDK）

choco install openjdk13
# 所在路径 C:\Program Files\OpenJDK\jdk-13.0.2

3. 基于 choco 安装 Gradle（五大核心依赖之一：Gradle）

choco install gradle
# 所在路径 C:\ProgramData\chocolatey\bin

4. 基于 choco 安装 Android SDK

choco install android-sdk
# 所在路径 C:\Android\android-sdk

5. 基于 android-sdk 安装 androd：sdkmanager "platforms;android-30"（五大核心依赖之一：androd）
6. 基于 android-sdk 安装 build-tools：sdkmanager "build-tools;30.0.3"（五大核心依赖之一：build-tools）
7. cd 进入《第五章：Android 项目模板制作》创建的模板，在根目录HBuilder-Integrate-AS执行以下命令

• gradlew assembleRelease

8. 最终效果如图，路径HBuilder-Integrate-AS\simpleDemo\build\outputs\apk\release

四、LINUX（离线 - 纯命令版）

依赖（以下各工具版本相互依赖）²

其他前置准备

• 制作 Android 的项目模板，请参照《第五章：Android 项目模板制作》

实现原理

• 通过 linux 的gradlew脚本处理构建 APK

操作步骤

步骤一：安装 JDK 17【可自行选择其他方式安装依赖】

1. 下载 JDK 压缩包

2. 上传到服务器后解压缩到指定文件夹，cd 到对应目录后执行命令tar -zxvf jdk-17_linux-x64_bin.tar.gz -C /usr/lib/

3. 配置环境变量

# 编辑环境变量
vim ~/.bashrc

# 刷新环境变量（生效）
source ~/.bashrc

# 确认环境变量是否生效（看清楚只有一个横杆）
java -version

# vim ~/.bashrc 编辑环境变量参考内容
# JAVA
export JAVA_HOME=/usr/lib/jdk-17.0.12

# PATH
export PATH=$JAVA_HOME/bin:$PATH

4. 确认环境变量是否生效

步骤二：下载 Gradle 7.5，上传到服务器

1. 下载 Gradle 7.5，创建文件夹存储 gradle

mkdir /Android/gradle -p

步骤三：安装 SDK 环境

1. 从 Android Studio 的官方网站下载sdkmanager的命令行工具，上传到服务器

2. 解压缩命令行工具³

# 安装 zip 格式解压缩工具
apt install unzip

# 解压缩到指定文件夹
unzip commandlinetools-linux-11076708_latest.zip -d /Android/sdk

3. 修改SDK目录结构⁴

cd /Android/sdk/cmdline-tools/
mkdir latest
mv !(latest) latest/

4. 修改后的目录结构如图

5. 安装platforms;android-30

cd /Android/sdk/cmdline-tools/latest/bin/
./sdkmanager "platforms;android-30"

6. 安装build-tools;30.0.3

cd /Android/sdk/cmdline-tools/latest/bin/
./sdkmanager "build-tools;30.0.3"

7. 最终SDK目录

步骤四：验证环境

1. 至此，所有环境配置完成，修改项目代码SDK配置，并验证环境是否有问题。先创建文件夹，然后上传《第五章：Android 项目模板制作》准备好的代码模板

mkdir /Android/code

2. 找到代码文件路径HBuilder-Integrate-AS\local.properties，修改SDK引用路径

sdk.dir=/Android/sdk

3. 找到代码文件HBuilder-Integrate-AS/gradle/wrapper/gradle-wrapper.properties，修改Gradle引用路径，如果这里不修改，首次构建会从线上拉取

distributionUrl=file:///Android/gradle/gradle-7.5-bin.zip

4. 【高版本需同时修改以下三个文件】本案例中用的环境相对都是比较高的版本，需要同时修改相应的文件才能调用相关的 API，并且需要满足一些新版本特殊设置

• HBuilder-Integrate-AS/build.gradle

• HBuilder-Integrate-AS/simpleDemo/build.gradle

• /Android/code/HBuilder-Integrate-AS/simpleDemo/src/main/AndroidManifest.xml

android:exported="true"

5. 修改gradlew脚本权限，并测试是否能正常使用

cd /Android/code/HBuilder-Integrate-AS/
ls -al gradlew
chmod +x gradlew
ls -al gradlew
./gradlew tasks

6. 出现assemble证明环境验证通过

步骤五：构建打包 APK

1. 执行以下打包命令，首次打包会联网下载依赖

cd /Android/code/HBuilder-Integrate-AS/
./gradlew assembleRelease

2. 最终效果如图，路径HBuilder-Integrate-AS/simpleDemo/build/outputs/apk/release

五、Android 项目模板制作

操作步骤一：将 UNI-APP 项目打包成 Android 可用的资源

1. cd 到 UNI-APP 项目的根目录，执行 package.json 中的打包命令，生成 Android 可用使用的代码包：npm run build:app-plus

2. 构建完成在目录 dist/build/app-plus 中会有一份编译后的代码，放入根目录的新文件夹中（使用 manifest.json 中的 appid 一样），并将其 app-plus 重命名为 www

mkdir __UNI__664E2AC
move dist/build/app-plus __UNI__664E2AC\www

操作步骤二：制作 APK 构建模板

1. 下载 UNI-APP 官方提供的离线 SDK，并使用任意编辑器打开
2. 找到 HBuilder-Integrate-AS 项目，将【步骤一】生成的 __UNI__664E2AC 整个替换到
   HBuilder-Integrate-AS 项目的示例位置 simpleDemo/src/main/assets/apps/__UNI__A

3. 【修改文件 1/4】HBuilder-Integrate-AS\simpleDemo\build.gradle，修改红框部分，其余内容可以按需修改，比如修改 versionCode，字面意思版本号

• 第 1 处替换为包名，跟 DCloud 平台设置的一致即可
• 第 2 处放入自己生成的签名证书，生成方式参考附录
• 第 3 处按签名证书修改对应的内容即可

4. 【修改文件 2/4】HBuilder-Integrate-AS\simpleDemo\src\main\AndroidManifest.xml，package跟第 3 步的包名保持一致，andorid:value替换为自己的 AppKey

5. 【非必须】HBuilder-Integrate-AS\simpleDemo\build.gradle，跟第 4 步同个文件，红框部分可自定义生成的 APK 名称

6. 【非必须】HBuilder-Integrate-AS\simpleDemo\src\main\res\values\strings.xml，修改红框部分，这是最终安装到手机后看到的 APP 的名字

7. 【非必须】HBuilder-Integrate-AS\simpleDemo\src\main\res\drawable\*，修改红框部分

• icon.png为应用的图标
• push.png为推送消息的图标
• splash.png为应用启动页的图标

8. 【修改文件 3/4】HBuilder-Integrate-AS\simpleDemo\src\main\assets\data\dcloud_control.xml，修改红框部分，和原来的 UNI-APP 项目 manifest.json 中的 appid 保持一致

9. 【非必须】HBuilder-Integrate-AS\gradle\wrapper\gradle-wrapper.properties，修改红框部分，可以替换为本地gradle，为全离线打包做准备

10. 【修改文件 4/4】（通过 AS 打开会自动生成）HBuilder-Integrate-AS\local.properties，在根目录新增local.properties文件，引入 SDK

六、构建生成 APK 环境的 Docker 镜像【拓展】

• 本章节为拓展章节，需要自行补充相关知识，这里不做说明
• 为了方便和保证运行环境，特地构建了Docker镜像提供稳定的SDK环境
• 主要做一个DEMO通过局域网（首次构建需要联外网）调用API的方式实现APK的生成和下载
• 具体API服务请自行改写或者通过Jenkins实现自动化流程，本样例不考虑异常情况

1. 最终目录结构展示

2. 为了保证关键的环境版本正确，我先下载了对应版本安装包到本地，可以自行改写Dockerfile从线上直接拉取

• package放了对应的安装包

• Dockerfile内容

FROM ubuntu:latest

# 复制本地的压缩包
COPY package/node-v18.20.3-linux-x64.tar.xz package/jdk-17_linux-x64_bin.tar.gz package/commandlinetools-linux-11076708_latest.zip package/gradle-7.5-bin.zip /tmp/

# 设置环境变量
ENV NODE_HOME=/usr/lib/node-18
ENV JAVA_HOME=/usr/lib/jdk-17
ENV ANDROID_SDK_ROOT=/Android/sdk
ENV PATH=$PATH:$NODE_HOME/bin:$JAVA_HOME/bin

# 安装基础包
RUN apt-get update && apt-get install -y wget unzip gzip xz-utils vim iputils-ping git lsof

# 安装Python环境
RUN apt-get install -y python3 python3-tornado

# 安装Node.js环境
RUN mkdir -p $NODE_HOME && \
    cd $NODE_HOME && \
    tar -xf /tmp/node-v18.20.3-linux-x64.tar.xz --strip-components=1 && \
    rm /tmp/node-v18.20.3-linux-x64.tar.xz
RUN npm config set registry https://registry.npmmirror.com/ && \
    npm install -g yarn

# 安装JDK 17
RUN mkdir -p $JAVA_HOME && \
    cd $JAVA_HOME && \
    tar -zxf /tmp/jdk-17_linux-x64_bin.tar.gz --strip-components=1 && \
    rm /tmp/jdk-17_linux-x64_bin.tar.gz

# 安装Android SDK环境
RUN mkdir -p $ANDROID_SDK_ROOT && \
    cd $ANDROID_SDK_ROOT && \
    unzip /tmp/commandlinetools-linux-11076708_latest.zip && \
    rm /tmp/commandlinetools-linux-11076708_latest.zip && \
    cd $ANDROID_SDK_ROOT/cmdline-tools/ && \
    mkdir latest && \
    mv $(ls | grep -v latest) latest/ && \
    cd $ANDROID_SDK_ROOT/cmdline-tools/latest/bin/ && \
    yes | ./sdkmanager --licenses && \
    ./sdkmanager "platforms;android-30" "build-tools;30.0.3"

# 导入Gradle压缩包
RUN mkdir -p /Android/gradle && \
    mv /tmp/gradle-7.5-bin.zip /Android/gradle/

# 复制项目文件到容器中
ADD code /Android/code

# 打包构建APK，初始化gradle-plugin等依赖
RUN cd /Android/code/apk-template/ && \
    chmod +x gradlew && \
    ./gradlew assembleRelease

# 设置工作目录
WORKDIR /Android/code/server

# 运行应用
CMD python3 main.py

3. 因为测试要频繁构建和部署，为了少打几行命令，我写了几个脚本用来辅助构建和运行镜像，自行编写即可，以下提供参考样例

• 基于Dockerfile构建镜像，build.sh如下

# 最后那一个点（.）不少别漏了
echo "构建镜像中..."
docker build -f Dockerfile -t apk:1.0 .
echo "构建结束"

• 部署脚本，deploy.sh如下

# 为了方便，我这里挂载了宿主机的代码，按需自行调整即可
echo "部署中..."
docker run -d -p 31234:8888 --name apk_container -v $(pwd)/code:/Android/code apk:1.0
echo "部署结束"

• 删除容器脚本和进入容器脚本如下

# remove.sh
echo "停止容器中..."
docker stop apk_container
echo "删除容器中..."
docker rm apk_container
echo "删除容器结束"

# enter.sh
docker exec -it apk_container /bin/bash

4. 在code文件夹中，自行准备以下代码

• Android 的项目模板，请参照《第五章：Android 项目模板制作》
• UNI-APP 的项目源代码（你自己的项目自己写…）
• 生成APK和下载APK的服务，以下提供样例，不作解释

# main.py
# 主服务文件，自己写即可，代码中的脚本参考下一个代码片段（这一步建议使用 Jenkins 实现，别学我）
import tornado.ioloop
import tornado.web
import subprocess
import logging
import os
import json


logging.basicConfig(level=logging.DEBUG)


# DEMO 示例
class DemoHandler(tornado.web.RequestHandler):
    def post(self):
        self.write('halo!')


# 生成 APK 文件
class GenerateHandler(tornado.web.RequestHandler):
    def post(self):
        try:
            data = json.loads(self.request.body) if self.request.body else {}
            result = subprocess.run(['/bin/bash', 'generate-apk.sh', data.get('env', 'dev')], capture_output=True, text=True)
            output = result.stdout
            self.write('success!!!!!\n')
            self.write(output)
        except Exception as e:
            self.set_status(500)
            self.write('fail!!!!!')


# 异步生成 APK 文件，这一步的日志可以自行通过 docker logs apk_container -f 查看
class GenerateAsyncHandler(tornado.web.RequestHandler):
    def post(self):
        try:
            data = json.loads(self.request.body) if self.request.body else {}
            process = subprocess.Popen(['/bin/bash', 'generate-apk.sh', data.get('env', 'dev')])
            self.write('generating...')
        except Exception as e:
            self.set_status(500)
            self.write('fail!!!!!')


# 下载 APK 文件
class DownloadHandler(tornado.web.RequestHandler):
    def get(self):
        file_path = "release-v1.0.apk"
        if os.path.exists(file_path):
            with open(file_path, 'rb') as file:
                self.set_header('Content-Type', 'application/octet-stream')
                self.set_header('Content-Disposition', 'attachment; filename="release-v1.0.apk"')
                self.write(file.read())
        else:
            self.set_status(404)
            self.write("File not found")


if __name__ == '__main__':
    app = tornado.web.Application([
        (r'/demo', DemoHandler),
        (r'/generate', GenerateHandler),
        (r'/generateAsync', GenerateAsyncHandler),
        (r'/download', DownloadHandler),
    ])
    # 监听8888端口
    app.listen(8888)
    # 定义ioloop实例，并启动服务
    print('running on port 8888')
    tornado.ioloop.IOLoop.current().start()

env=${1:-dev}

echo "git pull..."
cd /Android/code/project
git pull

echo "installing..."
yarn install

echo "building..."
yarn run build:app-plus:$env
rm -rf __UNI__664E2AC
mkdir __UNI__664E2AC
cp -r dist/build/app-plus __UNI__664E2AC/www

echo "android source moving..."
rm -r /Android/code/apk-template/simpleDemo/src/main/assets/apps/*
cp -r __UNI__664E2AC /Android/code/apk-template/simpleDemo/src/main/assets/apps/

echo "apk generating..."
cd /Android/code/apk-template
# 这里我挂载的是宿主机的路径，提前 chmod +x gradlew
./gradlew assembleRelease

echo "apk moving..."
rm /Android/code/server/*.apk
cp -r /Android/code/apk-template/simpleDemo/build/outputs/apk/release/*.apk /Android/code/server/

echo "end"

5. 最终效果如下

七、基于 Jenkins 自动化打包【拓展，待补充…】

附录

• 生成 keystore 签名证书

// keytool 依赖 JDK
// 生成命令
keytool -genkey -alias test -keyalg RSA -keysize 2048 -validity 36500 -keystore company-test.keystore

// 查看命令
keytool -list -v -keystore company-test.keystore

• gradlew 常用命令

// 用于清理项目构建过程中生成的临时文件和输出文件，说人话就是会删除整个 build 文件夹
gradlew clean

// 列出可用的构建任务，主要看看 assemble 在不在，不在的话就不用白费力气打包了
gradlew tasks

// 编译打包构建 APK
gradlew assemble
gradlew assembleDebug
gradlew assembleRelease

其他参考网址