跳转至

Android（安卓）上架流程与构建文档

适用工程：open_h5（Vue3 + Vite + Capacitor 7 的 H5 主工程），Android 外壳工程位于 open_h5/android。 文档构成： - 第一部分：从零注册开发者账号 → 申请/生成签名认证文件 → 提交审核上架的完整流程； - 第二部分：迁移自原 open_h5/README.md 的 Android 环境、构建、打包、调试操作文档； - 第三部分：常见坑速查。

重要说明（核实状态）：第一部分涉及外部平台的注册、认证、费用与政策要求，已于 2026-09-03 联网逐条核实，来源为各平台官方文档（developer.android.google.cn、华为开发者文档 / AppGallery Connect 帮助、Apple Developer 帮助）。已核实的条目直接给出官方口径并标注「已核实」。

本网络环境无法访问、因而仍标注「未验证」的项：support.google.com/googleplay/android-developer（Play Console 帮助中心）与 play.google.com（注册页、开发者分发协议）连接均失败，故 Google Play 注册费、封闭测试人数与时长门槛、审核时长、AAB 强制上传时间点 未能从官方页面确认；beian.miit.gov.cn 返回 HTTP 521，工信部备案规则改以华为官方《APP 备案指引》为来源。平台政策会变，实操前仍请以官方最新页面为准。

目录

第一部分 上架完整流程

1. 流程总览

准备资质材料
   └─ 营业执照 / 身份证、软件著作权、隐私政策、App 备案
        ↓
注册开发者账号（Google Play / 华为 / 小米 / OPPO / vivo / 应用宝 / 荣耀）
        ↓
开发者实名认证（个人）或企业认证（对公打款 / 授权函）
        ↓
生成签名密钥库 release.jks（keytool 或 Android Studio）
        ↓
把签名配置写进 android/app/build.gradle
        ↓
构建 H5 产物 → 同步到 Android → 打签名包（AAB 上架 / APK 测试）
        ↓
商店后台创建应用 → 填写商店信息 → 上传包 → 上传资质
        ↓
提交审核 → 通过 → 发布上架

一次完整的首次上架，卡点通常不在打包，而在「实名/企业认证」和「资质材料」这两步，需要预留时间。已核实（华为《实名认证》文档）：企业打款认证最快 30 分钟、人工审核 1~2 个工作日；个人人脸识别或个人银行卡认证即时完成、人工审核 1~2 个工作日。商店审核时长各平台官方文档均未给出承诺值（未验证）。

2. 上架前需要准备的材料

材料 用途 说明
营业执照（企业）或身份证（个人） 开发者账号实名/企业认证 企业还需法人身份证、对公银行账户
对公银行账户 企业认证打款验证 部分平台以打款小额随机金额方式验证
开发者资质授权函 企业认证 平台提供模板，需盖章
软件著作权登记证书 或 软件版权声明 上架资质 已核实，华为官方原文口径为软著属「非必选资质」，但建议申请《计算机软件著作权登记证书》《APP电子版权证书》或《软件著作权认证证书》以保护知识产权；游戏品类必需（软著 + 版号）。证书上的软件名称须与上架应用名称一致，著作权人须与开发者名称一致。软著登记周期较长，建议提前办
App 备案号（工信部） 国内商店上架 已核实：备案不在应用商店做，在云服务商（接入商）的备案系统做 —— 华为云/阿里云/腾讯云/移动云/天翼云/联通云。存在多个包名时所有包名均需备案；备案的包名、应用名称、主体信息必须与在架信息一致。无需备案的两类：单机应用（未通过公共互联网提供互联网信息服务）、境外应用（境外主体运营且服务器仅置于境外）。未备案会导致商店搜索与展示受限、安装时提示「应用未核准（备案）」
ICP 备案 / 域名备案 应用内访问的服务端域名 服务端域名需已备案
隐私政策页面（可公网访问的 URL） 商店信息填写 + 审核 需说明收集的个人信息、用途、第三方 SDK 清单
应用图标、应用截图、应用介绍 商店详情页 图标与截图尺寸各平台不同，按后台提示准备
测试账号 提交审核 需要登录才能用的 App 必须提供可用测试账号，否则会因「无法测试」被驳回
签名密钥库 release.jks 打包签名 见第 4 节

本工程为需要登录的企业应用（登录页在 src/views/tenants/*/login），提交审核时必须提供测试账号和服务器地址，否则审核方无法进入主界面。

3. 注册开发者账号

3.1 Google Play（海外分发）

  1. 准备一个 Google 账号（建议用公司邮箱，不要用个人私有账号）。
  2. 打开 Google Play Console 注册页：https://play.google.com/console/signup。
  3. 选择账号类型：
  4. 个人账号（Personal）：认证材料相对简单；
  5. 组织账号（Organization）：需要 D-U-N-S 编号（邓白氏编码；Apple 官方口径为「大多数司法管辖区免费申请」，未验证：申请周期约 5~30 个工作日），用公司名称作为发布者名称必须走这条路。
  6. 缴纳注册费。未验证：一次性 25 美元，需国际信用卡。说明：本次核实时 play.google.com/console/signup 与 support.google.com/googleplay/android-developer 从本网络均无法连接，developer.android.google.cn 上的 Play 管理中心相关页面不含任何费用信息，因此该金额未能从官方页面确认。
  7. 完成身份验证：上传身份证明、地址证明；组织账号还需验证组织信息与法人。
  8. 填写开发者资料：开发者名称（展示给用户）、联系邮箱、联系电话、网站。
  9. 认证通过后即可创建应用。

Google Play 的签名机制（重点）：Google Play 默认启用 Play App Signing（Play 应用签名）。这时存在两把 key： - 上传密钥（upload key）：就是你本地的 release.jks，用来给上传到 Play 的 AAB 签名； - 应用签名密钥（app signing key）：由 Google 托管，最终分发给用户的 APK 用它签名。

好处是上传密钥丢了可以向 Google 申请重置；但应用签名密钥一旦确定不可更换。

3.2 华为应用市场（AppGallery）

  1. 注册华为开发者账号：https://developer.huawei.com/consumer/cn/。
  2. 实名认证：
  3. 已核实（华为《实名认证》文档）：企业三选一 —— ① 打款认证（官方推荐，最快 30 分钟）：企业对公账号 + 法定代表人姓名 + 身份证号；② 人工审核（1~2 个工作日）：营业执照原件扫描件或照片 + 法定代表人手持身份证正反面照片或人脸识别；③ 华为云授权认证（账号已在华为云实名为企业客户）。个人四选一 —— 人脸识别（推荐，即时完成）、个人银行卡（推荐，即时完成）、人工审核（1~2 个工作日）、华为云授权认证。
  4. 官方认证方式列表中不含任何收费项，此前"企业认证需支付认证费"的说法未在官方文档中出现，已删除。
  5. 企业认证暂不支持电子营业执照，须提供最新「三证合一」营业执照照片或扫描件，且信息与国家企业信用信息公示系统一致；法人为港澳台人士可提交手持通行证或护照照片，海外人士提供手持护照照片。不支持港澳台、海外企业及海外个人注册认证中国大陆开发者联盟账号（须走海外官网）。
  6. 进入 AGC（AppGallery Connect）：https://developer.huawei.com/consumer/cn/service/josp/agc/index.html。
  7. 创建应用。已核实的当前路径（AGC 帮助《创建应用》，更新于 2026-07-22）：先在「证书、APP ID 和 Profile > APP ID」新建 APP ID（填应用类型、应用名称、应用包名、应用分类），再在 APP ID 列表中点「发布」为该 APP ID 关联创建待发布应用（填支持设备、默认语言），完成后才会出现在「APP 与元服务」列表中；旧版「我的应用 → 新建」已不是当前入口。本工程 Android 包名为 com.example.app。

    包名与应用分类一旦创建均不可修改，务必先确认。包名命名规范（段数、字符、保留字）见鸿蒙文档第 5.1 节。

  8. 填写应用信息：图标、简介、详细介绍、截图、隐私政策 URL、版本说明、应用权限说明。
  9. 上传软著/著作权声明、App 备案号等资质。
  10. 上传签名包（未验证：华为 Android 应用以 APK 为主）。
  11. 提交审核。

3.3 小米应用商店

  1. 注册小米开放平台账号：https://dev.mi.com/。
  2. 完成开发者实名认证（个人/企业），企业需营业执照 + 对公账户。
  3. 「应用管理」→ 创建应用，填写包名、应用名。
  4. 上传 APK、应用图标、截图、简介、隐私政策链接、软著、备案号。
  5. 提交审核。

3.4 OPPO / vivo / 应用宝 / 荣耀

流程与小米高度一致：注册 → 实名/企业认证 → 创建应用 → 上传 APK 与资质 → 提交审核。入口：

商店 开放平台地址
OPPO 软件商店 https://open.oppomobile.com/
vivo 应用商店 https://dev.vivo.com.cn/
应用宝（腾讯） https://open.qq.com/
荣耀应用市场 https://developer.honor.com/

国内多渠道分发时，同一个 App 在所有渠道必须使用同一个签名密钥库，否则用户无法跨渠道覆盖安装升级。

4. 生成签名认证文件（密钥库 .jks）

Android 的「认证文件」就是一个 Java 密钥库（keystore），扩展名一般是 .jks 或 .keystore，里面存放签名用的私钥和自签名证书。Android 不需要向平台申请证书（这一点和 iOS、鸿蒙不同），密钥库由开发者自己生成，平台只校验签名一致性。

4.1 方式一：Android Studio 图形界面生成

  1. 菜单 Build → Generate Signed App Bundle / APK。

Generate Signed App Bundle or APK

  1. 首次没有密钥库时，点击 Create new... 新建。

首次需要先创建密钥库文件

  1. 在 New Key Store 弹窗里填写各字段，字段含义见下图标注：

New Key Store 字段说明

4.2 方式二：keytool 命令行生成（推荐，可复现）

keytool 随 JDK 提供，确认 java/keytool 在 PATH 中即可：

keytool -genkeypair -v \
  -keystore release.jks \
  -storetype PKCS12 \
  -keyalg RSA -keysize 2048 \
  -validity 10950 \
  -alias release

执行后会依次询问密钥库口令、姓名（CN）、组织单位（OU）、组织（O）、城市（L）、省份（ST）、国家代码（C）。

  • -validity 10950 约 30 年。已核实（developer.android.google.cn 应用签名文档）：签名密钥的有效期必须在 2033 年 10 月 22 日以后结束，此项由 Google Play 强制执行，官方建议使用 25 年或以上的有效期，因此不要用默认的很短有效期。
  • 本工程现有密钥库放在 open_h5/android/app/release.jks，别名为 release。

4.3 密钥库字段说明

字段 含义 建议
Key store path 密钥库文件保存路径 放到工程外的安全目录，不要提交到仓库
Password / Confirm（上半部分） 密钥库口令 用密码管理器保存
Alias 密钥别名 本工程用 release
Password / Confirm（Key 部分） 密钥口令 可与密钥库口令不同
Validity (years) 证书有效年限 ≥ 25 年
First and Last Name (CN) 通用名 一般填应用名或负责人
Organizational Unit (OU) 部门 如 Mobile
Organization (O) 组织/公司全称 会写进证书，用户可见
City / State / Country Code 城市/省/国家码 国家码用两位，如 CN

4.4 提取公钥与证书指纹

第三方 SDK（地图、推送、登录等）常需要提供签名的 MD5/SHA1/SHA256 指纹：

# 方式一：直接列出密钥库中证书的全部指纹
keytool -list -v -keystore release.jks -alias release

# 方式二：先导出 PEM 公钥证书，再 dump 指纹（原 README 中记录的做法）
keytool -exportcert -rfc -keystore release.jks -alias release > cert.pem
certutil -dump cert.pem

# 方式三：直接校验已打好的 APK 用的是哪把 key
<Android SDK>/build-tools/<版本>/apksigner verify --print-certs app-release.apk

4.5 保管要求

  • release.jks 和两个口令丢失即无法再更新已上架的应用（Google Play 走 Play App Signing 时可申请重置上传密钥，国内商店基本无解，只能改包名重新上架）。
  • 密钥库文件、口令不能进开源仓库，应加入 .gitignore，通过公司内部密钥管理渠道分发。

5. 把签名配置接入工程

签名配置写在 open_h5/android/app/build.gradle：

android {
    signingConfigs {
        release {
            storeFile file("release.jks")
            storePassword "******"
            keyAlias "release"
            keyPassword "******"
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

开源注意：当前工程里这四个值是明文硬编码在 build.gradle 中的。开源前必须改为从工程外部读取（例如 keystore.properties 或环境变量），并把 release.jks、cert.pem、keystore.properties 加入 .gitignore，仓库里只保留 keystore.properties.example 模板。

推荐写法（对外开源版本）：

// android/app/build.gradle
def keystorePropertiesFile = rootProject.file("keystore.properties")
def keystoreProperties = new Properties()
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        release {
            storeFile file(keystoreProperties['storeFile'] ?: 'release.jks')
            storePassword keystoreProperties['storePassword'] ?: ''
            keyAlias keystoreProperties['keyAlias'] ?: ''
            keyPassword keystoreProperties['keyPassword'] ?: ''
        }
    }
}

# keystore.properties.example（提交到仓库，不含真实值）
storeFile=release.jks
storePassword=
keyAlias=release
keyPassword=

另外 android/local.properties 里记录的是本机 Android SDK 路径，属于本地环境文件，不应提交仓库。

6. 产物格式选择：AAB 还是 APK

Build → Generate Signed App Bundle / APK 的第一步就是选格式：

选择 Android App Bundle 还是 APK

  • Android App Bundle（.aab）：上架用。未验证：Google Play 自 2021 年 8 月起要求新应用必须以 AAB 上传 —— 该说法所在的 Play Console 帮助中心从本网络不可达，未能核实。
  • APK：给真机装包测试、内部分发用。国内商店目前主要收 APK（未验证）。

命令行对应关系：

# APK（release，已签名）
./gradlew assembleRelease      # Windows: .\gradlew assembleRelease

# AAB（release，已签名）
./gradlew bundleRelease        # Windows: .\gradlew bundleRelease

产物位置：

类型 路径
release APK android/app/build/outputs/apk/release/app-release.apk
release AAB android/app/build/outputs/bundle/release/app-release.aab
debug APK android/app/build/outputs/apk/debug/app-debug.apk

7. 商店后台创建应用并提交审核

以国内商店为例的通用步骤：

  1. 后台创建应用，填入包名（本工程 com.example.app）与应用名（本工程 <应用名>，定义在 capacitor.config.ts 与 android/app/src/main/res/values/strings.xml）。
  2. 上传签名包。上传后后台会自动解析包名、版本号（versionCode / versionName，定义在 android/app/build.gradle）、目标 SDK。
  3. 已核实，且本工程当前不合规（developer.android.google.cn《满足 Google Play 的目标 API 级别要求》官方原文）：自 2026 年 8 月 31 日起，新应用和应用更新必须以 Android 16（API 级别 36）或更高版本为目标平台，才能提交到 Google Play；Wear OS 与 Android Automotive OS 应用除外，须以 API 35 及以上为目标；Android TV 与 Android XR 应用也除外，须以 API 34 及以上为目标。现有应用若要对更高版本系统设备的新用户可用，targetSdk 须不低于 35。
  4. 本工程当前 compileSdk/targetSdk 为 35、minSdk 为 23（见 android/variables.gradle）。截至本文档写作日 2026-09-03，上述时间点已过，本工程已不满足向 Google Play 提交的要求，需将 targetSdk 升到 36。官方留有延期通道：可在 Play 管理中心的应用延期表单申请延期至 2026 年 11 月 1 日。唯一豁免是「仅限特定组织内部用户使用且仅供内部分发的永久专用应用」。
  5. 升级 targetSdk 属工程改动，本次未执行。
  6. 填写商店详情：图标、截图、一句话简介、详细介绍、更新说明、分类、关键词。
  7. 填写合规信息：隐私政策 URL、权限使用说明、个人信息收集清单、第三方 SDK 清单、是否含广告、年龄分级。
  8. 本工程申请的权限见 android/app/src/main/AndroidManifest.xml，其中 MANAGE_EXTERNAL_STORAGE（访问公共目录）在各商店尤其是 Google Play 审核非常严格，如果业务不必须，建议上架前移除。
  9. 上传资质：软著或电子版权证书（华为口径为非必选资质，游戏品类必需）、App 备案号、行业许可证（如需要）。华为侧上传入口为「AGC > APP与元服务 > 点击应用名称 > 版本信息 > 版权信息」；资质图片要求：原件拍照或彩色扫描件（或加盖公章的复印件）、在有效期内、不可隔屏拍摄、边角完整内容清晰（国徽不得遮挡）、无反光、水印只能一行且不遮挡重要信息，支持 JPG / PNG / BMP / PDF。
  10. 提交审核 → 等待结果 → 通过后选择立即发布或定时发布。

8. 常见驳回原因

  • 未提供测试账号，或提供的账号无法登录（本工程必须提供）；
  • 权限申请与功能不匹配，尤其是 MANAGE_EXTERNAL_STORAGE、CAMERA、定位类权限；
  • 隐私政策缺失、无法访问，或未列明第三方 SDK；
  • 缺少 App 备案号（国内强制，未备案会提示「应用未核准（备案）」并影响商店搜索与展示）；软著在华为口径下属「非必选资质」，但部分商店与部分品类（尤其游戏）仍强制要求；
  • 应用内含"更新提示/自更新"能力被判定为绕过商店分发。本工程集成了 @capgo/capacitor-updater 热更新（只更新 H5 资源，不替换原生包），需在审核说明中解释清楚"仅更新 Web 资源、不下发可执行代码"，Google Play 对此尤其敏感；
  • 明文 HTTP 请求。本工程 capacitor.config.ts 中 server.androidScheme: "http"、android.allowMixedContent: true，并配了 network_security_config，如被判定为不安全传输需给出说明或改为 HTTPS。

9. 上架后的版本更新

  1. 提升版本号：android/app/build.gradle 中 versionCode（整数，每次必须递增）和 versionName（展示字符串）。
  2. 重新走第二部分的构建打包流程，必须用同一个 release.jks 签名。
  3. 后台新建版本 → 上传新包 → 填写更新说明 → 提交审核。

第二部分 构建与打包操作文档

本部分内容迁移自 open_h5/README.md，仅做拆分、补全与路径占位化处理，操作步骤保持原样。

10. 环境要求

  1. Node / NPM 版本 >= 20
  2. Java / JDK 版本 >= 17（Android 构建依赖）
  3. Android SDK（建议通过 Android Studio 安装与管理）
  4. Capacitor CLI（管理 capacitor）

拉到项目后先安装依赖：

npm install
# 原文档补充：若使用本地组件库，需 npm link 到本项目
npm link

Capacitor 官方文档：https://capacitorjs.com/docs/plugins

工程结构（Capacitor 部分）

  • android：Android 平台的构建文件；
  • ios：iOS 平台的构建文件；
  • capacitor.config.ts：Capacitor 配置文件，包含应用的基本信息、权限配置等；
  • src/capacitor：本项目中使用到的 Capacitor 插件的功能封装文件。

本项目用到的 Capacitor 插件

插件 作用
@capacitor/core Capacitor 核心库
@capacitor/app 应用生命周期管理
@capacitor/camera 拍照和选择图片
@capacitor/filesystem 文件读写
@capacitor/haptics 震动
@capacitor/keyboard 键盘
@capacitor/splash-screen 启动画面
@capacitor/status-bar 状态栏
@capacitor/share 分享
@capacitor/dialog 原生弹窗
@capacitor/assets 图标/启动页资源生成
@capgo/capacitor-updater 热更新，远端拉取 dist.zip 并切换版本

11. 开发工具

  1. Android Studio（包含 SDK Manager）
  2. Android SDK 版本根据需求选择，可以下载内置的也可以单独下载然后引入；
  3. SDK Manager 里安装 platform-tools、对应 API Level、build-tools。

SDK Manager

  1. 真机（建议 Android 8+）

12. 构建步骤

# 1. 如果没有 Android 平台目录：先执行（仅首次）
npx cap add android

# 2. 项目打包（生成 dist）
npm run build

# 3. 同步 Web 产物与插件到 Android
npx cap sync android

# 4. 打开 Android Studio
npx cap open android
  1. 首次构建后要在 AndroidManifest.xml 中配置需要的权限，例如网络、存储等：

权限配置

关于首次构建的 public 目录：与 iOS 一致——如果在 cap add android 之前项目中已存在 webDir（dist），Capacitor 会在 add 阶段自动拷贝一次 Web 资源到原生工程的 public 目录；若 cap add android 在 npm run build 之前执行，就不会带上资源，需要执行 npx cap sync android 才会同步。

从 git 上拉取的代码已带配置好的 android 目录，不要再执行 npx cap add android，可能会导致重置、丢失已有配置。

13. 打包

图形界面方式

  1. 在 Android Studio 中选择 Build → Generate Signed Bundle / APK；
  2. 选择 AAB（上架）或 APK（真机测试）；
  3. 选择/创建密钥库并填入口令；
  4. 配置完成后点击 Next，选择 Build Variant = release，点击 Create 开始创建正式包：

选择 release 并创建

命令行方式

# 开发包打包命令
.\gradlew assembleRelease

完整流程（原文档记录的 full 环境流程）：

npm run build:full
npx cap sync android
cd android
.\gradlew assembleRelease

产物位置：android/app/build/outputs/apk/release/

14. 真机调试

  1. 手机打开开发者选项与 USB 调试，用可传输数据的数据线连接电脑后，Android Studio 可以识别到设备：

配置好之后的真机显示位置

  1. 可使用 Chrome 访问 chrome://inspect 进行真机 WebView 调试。

15. 注意事项

  1. 可以安装 nvm 工具统一管理 node 版本，版本过高会导致报错。
  2. 注意环境变量的配置，确保项目能够正常运行。
  3. 应用图标和启动页配置参考 https://github.com/ionic-team/capacitor-assets：
  4. npm install --save-dev @capacitor/assets；
  5. public/manifest.webmanifest 由 capacitor/assets 命令生成，同时生成 icons 目录；
  6. 该工具要求项目根目录中存在 assets 或 resources 文件夹，文件名不能改。
  7. 日志位置：Android 环境下 文件管理 → documents → app。
  8. 提取 jks 文件中的公钥和 MD5 签名： 
    keytool -exportcert -rfc -keystore release.jks -alias release > cert.pem
certutil -dump cert.pem
  9. 滑动退出在 iOS 环境下不生效，Android 正常。

第三部分 常见坑

  1. 首次执行 .\gradlew 会下载 Gradle 全量包（gradle-8.11.1-all.zip），首次构建耗时会明显更长，需保证网络可达 services.gradle.org，或提前配好镜像。
  2. JAVA_HOME 与 PATH 上的 java 版本不一致时，若报 AGP 不兼容，显式指定 $env:JAVA_HOME 指向 JDK 17+，或在 android/gradle.properties 里加 org.gradle.java.home=。
  3. aapt2 报 Failed to stat file ... android.jar 的 WARN：构建期间会反复出现，但不影响结果（最终仍 BUILD SUCCESSFUL），可忽略。
  4. versionCode 每次上传商店必须递增，否则拒收（提示 build already exists）。
  5. 签名口令当前明文写在 android/app/build.gradle：开源发布前按第 5 节改成从 keystore.properties 等工程外文件读取，release.jks、cert.pem 不要入库。
搜索