本地打包

本地打包是 uniapp 开发工具的核心功能，允许您在本地环境中将 uniapp 项目打包成 Android APK 或 iOS IPA 文件。

概述

本地打包的优势

🚀 更快速: 无需排队等待云端资源
🔒 更安全: 代码不离开本地环境
💪 更可控: 完全掌控打包参数和流程
📦 更稳定: 不受网络波动影响

打包流程

mermaid

graph LR
    A[准备项目] --> B[配置参数]
    B --> C[选择平台]
    C --> D[开始打包]
    D --> E[编译构建]
    E --> F[签名打包]
    F --> G[生成安装包]

前置准备

在开始打包前，确保已完成：

Android 打包

1. 打开打包界面

在 uniapp 开发工具中：

打开您的项目
点击菜单"构建" > "Android 打包"
或使用快捷键 Ctrl/Cmd + Shift + A

2. 选择打包类型

调试包（Debug）:

用于开发和测试
包含调试信息
可以通过 USB 调试
文件较大

正式包（Release）:

用于发布
已优化和混淆
需要签名
文件较小

建议

开发阶段使用调试包，发布前使用正式包。

3. 配置打包参数

基本参数：

参数	说明	示例
应用名称	安装后显示的名称	我的应用
版本名称	用户可见版本	1.0.0
版本号	内部版本号	100
包名	应用唯一标识	com.example.app

构建参数：

最小 SDK 版本: 推荐 21 (Android 5.0)
目标 SDK 版本: 推荐 33 (Android 13)
CPU 架构:
- armeabi-v7a: 兼容性最好
- arm64-v8a: 性能最好（推荐）
- x86: 模拟器支持
- x86_64: 64位模拟器

CPU 架构选择

对于现代设备，推荐只打包 arm64-v8a，可显著减小包体积。

签名配置（正式包）：

密钥库文件: 选择 .keystore 文件
密钥库密码: 输入密码
密钥别名: 输入别名
密钥密码: 输入密钥密码

4. 高级选项

代码混淆：

启用 ProGuard 混淆
保护代码不被反编译
减小 APK 体积

资源优化：

移除未使用的资源
压缩图片和资源文件
启用资源混淆

多渠道打包：

为不同分发渠道生成带标识的包：

渠道列表：
- official（官网）
- huawei（华为应用市场）
- xiaomi（小米应用市场）
- oppo（OPPO 软件商店）

勾选"多渠道打包"并填入渠道列表。

5. 开始打包

检查所有参数
点击"开始打包"按钮
查看打包进度

6. 打包进度

打包过程包括以下步骤：

环境检查 (5%)
- 验证 SDK 配置
- 检查 JDK 版本
- 验证项目结构
依赖安装 (15%)
- 安装 npm 依赖
- 下载原生插件
代码编译 (40%)
- 编译 Vue/JS 代码
- 转换为原生代码
- 生成资源文件
原生构建 (70%)
- 运行 Gradle 构建
- 编译 Java/Kotlin 代码
- 生成 APK
签名打包 (90%)
- 对齐 APK
- 签名 APK
- 优化输出
完成 (100%)

提示

首次打包会下载 Gradle 和依赖，耗时较长（10-30分钟）。后续打包会快很多。

7. 获取安装包

打包完成后：

在界面中点击"打开文件夹"
或前往项目目录下的 unpackage/release/apk/
找到生成的 APK 文件：
- 调试包: app-debug.apk
- 正式包: app-release.apk
- 多渠道: app-huawei-release.apk

iOS 打包

1. 系统要求

重要

iOS 打包只能在 macOS 系统上进行。

必需软件：

macOS 10.15 或更高版本
Xcode 14.0 或更高版本
Apple 开发者账号（发布时必需）

2. 打开打包界面

打开项目
点击"构建" > "iOS 打包"
或快捷键 Cmd + Shift + I

3. 选择打包类型

开发版本（Development）:

用于真机调试
需要开发证书
设备需在描述文件中

Ad Hoc 版本:

用于内测分发
可安装到已注册设备
最多 100 台设备

App Store 版本:

用于提交 App Store
需要发布证书
通过 App Store 分发

企业版本（Enterprise）:

企业账号专用
可安装到任意设备
不通过 App Store 分发

4. 配置打包参数

基本信息：

Bundle ID: com.example.app
版本号: 1.0.0
构建号: 1
显示名称: 我的应用

证书和描述文件：

选择证书
- 开发证书: iPhone Developer
- 发布证书: iPhone Distribution
选择描述文件
- 确保与 Bundle ID 匹配
- 确认未过期
自动签名（推荐）
- 勾选"自动管理签名"
- 登录 Apple ID
- Xcode 自动处理证书

5. 构建设置

部署目标：

最低 iOS 版本: 11.0 或更高

设备支持：

iPhone
iPad
Universal（通用）

架构：

arm64（必选）
armv7（可选，支持旧设备）

6. 开始打包

确认配置无误
点击"开始打包"
输入钥匙串密码（首次需要）

7. 打包进度

iOS 打包步骤：

环境检查 (5%)
- 验证 Xcode
- 检查证书
- 验证描述文件
依赖安装 (15%)
- 安装 CocoaPods
- 下载原生插件
代码编译 (35%)
- 编译前端代码
- 生成原生代码
Xcode 构建 (75%)
- 编译 Swift/ObjC 代码
- 链接库文件
- 生成 App
签名打包 (95%)
- 代码签名
- 生成 IPA
完成 (100%)

8. 获取安装包

完成后：

点击"打开文件夹"
或前往 unpackage/release/ios/
找到 IPA 文件：
- app.ipa

安装测试

Android 安装

方式一：USB 安装

bash

# 连接设备后
adb install app-release.apk

方式二：直接传输

将 APK 传输到设备
在设备上打开 APK 文件
允许安装未知来源应用
点击安装

方式三：扫码安装

使用工具生成二维码，用户扫码下载。

iOS 安装

开发版/Ad Hoc:

使用工具如 Apple Configurator、iMazing 或 Xcode：

bash

# 使用 Xcode 安装
xcrun simctl install booted app.ipa

TestFlight（推荐）:

将 IPA 上传到 App Store Connect
添加内测用户
用户通过 TestFlight 安装

企业版:

部署到 Web 服务器，通过 Safari 安装。

优化建议

减小包体积

代码优化：

启用代码混淆和压缩
移除无用代码和日志
使用摇树优化（Tree Shaking）

资源优化：

压缩图片（使用 WebP 格式）
移除未使用的字体和资源
使用矢量图标（图标字体或 SVG）

库优化：

按需引入第三方库
使用轻量级替代方案
避免重复依赖

架构优化：

只打包必需的 CPU 架构
使用 App Bundle（Android）
动态下载资源

提升打包速度

使用 Gradle 缓存
gradle
```
org.gradle.caching=true
```
增加 Gradle 内存
gradle
```
org.gradle.jvmargs=-Xmx4096m
```
使用本地 Maven 仓库
gradle
```
mavenLocal()
```
启用并行构建
gradle
```
org.gradle.parallel=true
```

提高应用性能

启动优化：

延迟加载非必需模块
优化启动页显示
预加载关键资源

运行优化：

使用原生插件处理耗时操作
优化图片加载和缓存
减少页面层级和渲染开销

常见问题

Android 打包失败

问题: Gradle 构建失败

解决方案:

检查网络连接（下载依赖）
清理 Gradle 缓存：
bash
```
./gradlew clean
```
增加 Gradle 内存
检查 JDK 版本（推荐 JDK 11）

iOS 签名失败

问题: 代码签名错误

解决方案:

确认证书未过期
检查 Bundle ID 匹配
重新下载描述文件
尝试"自动签名"

清理 Xcode 缓存：

bash

rm -rf ~/Library/Developer/Xcode/DerivedData

包体积过大

问题: APK/IPA 文件太大

解决方案:

移除未使用的资源和库
启用代码和资源压缩
使用 WebP 格式图片
检查是否重复打包了依赖
只打包必需的 CPU 架构

打包过程卡住

问题: 进度长时间不动

解决方案:

查看详细日志（点击"查看日志"）
检查网络连接
检查磁盘空间
重启工具重试
清理构建缓存

打包日志

查看日志

打包过程中，点击"查看日志"可以看到详细输出。

日志位置：

Windows: %APPDATA%\uniapp-tools\logs\
macOS: ~/Library/Logs/uniapp-tools/

日志文件：

build-android.log: Android 打包日志
build-ios.log: iOS 打包日志

日志分析

遇到错误时，重点查看：

错误信息（通常带有 ERROR 或 FAILED）
堆栈跟踪（定位具体问题）
警告信息（可能影响打包）

CI/CD 集成

命令行打包

工具支持命令行模式，方便集成到 CI/CD：

Android:

bash

uniapp-tools build android \
  --project /path/to/project \
  --type release \
  --keystore /path/to/key.keystore \
  --keystore-password yourpassword \
  --key-alias youralias \
  --key-password keypassword

iOS:

bash

uniapp-tools build ios \
  --project /path/to/project \
  --type appstore \
  --certificate "iPhone Distribution: Your Name" \
  --provisioning-profile /path/to/profile.mobileprovision

环境变量

bash

export UNIAPP_TOOLS_APPKEY="your_appkey"
export ANDROID_HOME="/path/to/android/sdk"
export JAVA_HOME="/path/to/jdk"

示例：GitHub Actions

yaml

name: Build App

on: [push]

jobs:
  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build Android
        run: |
          uniapp-tools build android \
            --project . \
            --type release \
            --keystore ${{ secrets.KEYSTORE_FILE }} \
            --keystore-password ${{ secrets.KEYSTORE_PASSWORD }}

打包检查清单

开始打包前，确认：

[ ] 开发环境已正确配置
[ ] 项目配置完整无误
[ ] 证书和签名已配置（发布时）
[ ] 版本号已更新
[ ] 图标和启动页已设置
[ ] 必要的权限已声明
[ ] 代码已测试无误
[ ] 敏感信息已移除（API Key 等）

下一步

打包完成后，您可以：

安装到设备测试
发布到应用商店
探索 VIP 功能
学习原生插件开发
使用 AI 辅助开发

本地打包 ​

概述 ​

本地打包的优势 ​

打包流程 ​

前置准备 ​

Android 打包 ​

1. 打开打包界面 ​

2. 选择打包类型 ​

3. 配置打包参数 ​

4. 高级选项 ​

5. 开始打包 ​

6. 打包进度 ​

7. 获取安装包 ​

iOS 打包 ​

1. 系统要求 ​

2. 打开打包界面 ​

3. 选择打包类型 ​

4. 配置打包参数 ​

5. 构建设置 ​

6. 开始打包 ​

7. 打包进度 ​

8. 获取安装包 ​

安装测试 ​

Android 安装 ​

iOS 安装 ​

优化建议 ​

减小包体积 ​

提升打包速度 ​

提高应用性能 ​

常见问题 ​

Android 打包失败 ​

iOS 签名失败 ​

包体积过大 ​

打包过程卡住 ​

打包日志 ​

查看日志 ​

日志分析 ​

CI/CD 集成 ​

命令行打包 ​

环境变量 ​

示例：GitHub Actions ​

打包检查清单 ​

下一步 ​

本地打包

概述

本地打包的优势

打包流程

前置准备

Android 打包

1. 打开打包界面

2. 选择打包类型

3. 配置打包参数

4. 高级选项

5. 开始打包

6. 打包进度

7. 获取安装包

iOS 打包

1. 系统要求

2. 打开打包界面

3. 选择打包类型

4. 配置打包参数

5. 构建设置

6. 开始打包

7. 打包进度

8. 获取安装包

安装测试

Android 安装

iOS 安装

优化建议

减小包体积

提升打包速度

提高应用性能

常见问题

Android 打包失败

iOS 签名失败

包体积过大

打包过程卡住

打包日志

查看日志

日志分析

CI/CD 集成

命令行打包

环境变量

示例：GitHub Actions

打包检查清单

下一步