如何在 Huawei AppGallery 发布 Capacitor 应用

你可以用发布到 Google Play 的同一个 Android build，把 Capacitor 应用发布到 Huawei AppGallery。注册免费的 HUAWEI Developers 账号，检查哪些插件依赖 Google Play 服务（2019 年底起发布的华为手机不包含该服务），隐藏或替换这些功能，然后在 AppGallery Connect 中上传已签名的 APK、填写上架信息并等待审核。本指南会逐步讲解，包括一小段可直接放进应用的原生检测代码，无需额外依赖即可检测 Google Play 服务。

谁适合在 AppGallery 上架

AppGallery 是华为手机和平板的默认应用商店。如果你的用户中有以下群体，它就很关键：

• 在欧洲、中东、非洲、拉美和东南亚使用 2019 年美国贸易限制后发布的华为设备的用户，这些设备出厂不预装 Google Play 服务和 Play Store。
• 统一采用华为硬件的企业或政府客户。

关于 HarmonyOS 的说明：在中国大陆以外销售的华为手机运行基于 Android 的 EMUI，可以安装 APK。而中国大陆运行 HarmonyOS NEXT（HarmonyOS 5 及更高版本）的设备只能运行原生 HarmonyOS 应用，Android APK 无法触达。本指南针对的是基于 Android 的 AppGallery。

第 1 步：检查 Google Play 服务依赖

Capacitor 本身只依赖 AndroidX 和它自己的 Android 库。风险来自那些引入 Google 库的插件。看看你的依赖项：

cd android
./gradlew :app:dependencies --configuration releaseRuntimeClasspath \
  | grep -E "com.google.android.gms|com.google.firebase|com.google.android.play|billingclient" \
  | sort -u

然后把它们分成“无需 Google Play 服务即可运行”和“需要 Google Play 服务”两类。

“不起作用”通常意味着调用抛异常或一直不 resolve。它很少会让整个 App 崩溃，但审核人员会在华为设备上测试，按钮点了没反应或白屏是很常见的拒审原因。

第 2 步：在运行时检测 Google Play 服务

你无需添加任何 Google 依赖，就能检查 Google Play 服务：只需询问 Android 的包管理器 com.google.android.gms 是否已安装。在你的 Capacitor Android 项目中添加一个小巧的本地插件。

android/app/src/main/java/com/example/app/ServicesCheckPlugin.java:

package com.example.app;

import android.content.pm.PackageManager;
import com.getcapacitor.JSObject;
import com.getcapacitor.Plugin;
import com.getcapacitor.PluginCall;
import com.getcapacitor.PluginMethod;
import com.getcapacitor.annotation.CapacitorPlugin;

@CapacitorPlugin(name = "ServicesCheck")
public class ServicesCheckPlugin extends Plugin {

    private boolean isInstalled(String packageName) {
        try {
            getContext().getPackageManager().getPackageInfo(packageName, 0);
            return true;
        } catch (PackageManager.NameNotFoundException e) {
            return false;
        }
    }

    @PluginMethod
    public void getStatus(PluginCall call) {
        JSObject ret = new JSObject();
        ret.put("gms", isInstalled("com.google.android.gms"));
        ret.put("hms", isInstalled("com.huawei.hwid"));
        call.resolve(ret);
    }
}

在 MainActivity.java 在……之前 super.onCreate:

package com.example.app;

import android.os.Bundle;
import com.getcapacitor.BridgeActivity;

public class MainActivity extends BridgeActivity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        registerPlugin(ServicesCheckPlugin.class);
        super.onCreate(savedInstanceState);
    }
}

从 Android 11 开始，应用只能看到其声明的其他包。请添加一个 <queries> 块到 android/app/src/main/AndroidManifest.xml，位于 <manifest>:

<queries>
    <package android:name="com.google.android.gms" />
    <package android:name="com.huawei.hwid" />
</queries>

在 TypeScript 中调用：

import { Capacitor, registerPlugin } from '@capacitor/core';

interface ServicesCheckPlugin {
  getStatus(): Promise<{ gms: boolean; hms: boolean }>;
}

const ServicesCheck = registerPlugin<ServicesCheckPlugin>('ServicesCheck');

export async function getMobileServices() {
  if (Capacitor.getPlatform() !== 'android') {
    return { gms: true, hms: false };
  }
  return ServicesCheck.getStatus();
}

包的存在是一个合理的替代指标。它无法告诉你 Google Play 服务是否已更新或启用；如果你也需要检查这一点，请添加 com.google.android.gms:play-services-base 并使用 GoogleApiAvailability.isGooglePlayServicesAvailable()，即使在没有 GMS 的设备上也能正常工作。

步骤 3：优雅降级

使用结果来开启或关闭功能：

import { PushNotifications } from '@capacitor/push-notifications';
import { getMobileServices } from './services';

export const features = {
  push: true,
  googleSignIn: true,
  playBilling: true,
  inAppReview: true,
};

export async function initFeatures() {
  const { gms } = await getMobileServices();

  features.push = gms;
  features.googleSignIn = gms;
  features.playBilling = gms;
  features.inAppReview = gms;

  if (features.push) {
    const perm = await PushNotifications.requestPermissions();
    if (perm.receive === 'granted') {
      await PushNotifications.register();
    }
  }
}

实用回退方案：

• 登录：隐藏 Google 按钮，改为显示邮箱、Apple 或 Facebook 登录。这样 @capgo/capacitor-social-login 你只需初始化显示的提供商即可。
• 支付：Google Play Billing 不可用。AppGallery 有自己的 Huawei IAP。如果数字商品购买是应用的核心功能，要么集成 Huawei IAP，要么发布不带购买功能的 AppGallery 构建，并在应用详情页说明。
• 推送：针对 HMS 设备，请使用 Huawei Push Kit。目前没有官方的 Capacitor 插件；Huawei 在以下位置发布 Cordova 插件： @hmscore/* 这些插件可在 Capacitor 中运行，或者你可以基于 Push Kit SDK 编写一个小型原生插件。
• Map：在 WebView 中使用 Web 地图（如 Leaflet、MapLibre GL JS），它在所有设备上都能运行，或者使用 Huawei Map Kit。
• 给应用评分：在 Huawei 上，请链接到你的 AppGallery 页面，而不是调用 Play 的评价 API。
• 应用商店链接：“更新应用”按钮应打开 AppGallery (appmarket://details?id=com.example.app)，而不是 Play Store。

请在真实的华为设备或华为云调试服务上测试。带 Google APIs 的模拟器会掩盖所有这些问题。

步骤 4：注册 HUAWEI Developers 账号

1. 前往以下网址创建 HUAWEI ID： developer.huawei.com.
2. 完成 实名认证 可选择个人或企业身份。个人通常需提供身份证件和银行卡信息；企业需提供营业执照。审核通常需要 1 到 2 个工作日。
3. 请仔细选择账号类型和国家/地区。华为不支持将个人账号转为 企业账号，且认证后的国家或地区后续无法更改。

注册免费。

第 5 步：在 AppGallery Connect 中创建应用

1. 打开 AppGallery Connect > 我的应用 > 新建应用.
2. 平台： Android。设备： 手机 （也包含平板电脑）。
3. 应用名称、默认语言和包名。包名必须匹配 appId 中的 capacitor.config.ts 且在首次上传后无法更改。
4. 选择应用分类。

步骤 6：构建并签名发布包

AppGallery 支持 APK 和 AAB。APK 流程更简单：使用自己的密钥签名，华为无需持有您的签名密钥。

bun run build
bunx cap sync android
cd android
./gradlew assembleRelease

在以下位置配置签名： android/app/build.gradle （从环境变量加载密码，或 keystore.properties，切勿提交到版本控制）：

android {
    signingConfigs {
        release {
            storeFile file(System.getenv("ANDROID_KEYSTORE_PATH") ?: "upload-keystore.jks")
            storePassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
            keyAlias System.getenv("ANDROID_KEY_ALIAS")
            keyPassword System.getenv("ANDROID_KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

APK 位于 android/app/build/outputs/apk/release/。如果需要 keystore， Android keystore 生成器 会创建一个。请妥善保管：后续每次向 AppGallery 提交更新，都必须使用同一密钥进行签名。

如果上传 AAB 文件，AppGallery 要求使用其应用签名服务，这意味着华为将生成并保管最终签名密钥，模式与 Play App Signing 相同。

上传前请检查以下几项：

• versionCode 每次上传时都必须递增。
• APK 中的应用名称应与 AppGallery 上的应用名称保持一致。
• 如果在中国大陆以外分发，请在应用详情中提供英语（美国）语言。
• 自 2026 年 9 月 30 日起，Android 的开发者验证适用于在巴西、印度尼西亚、新加坡和泰国的认证设备上安装的应用。不含 Google 服务的华为设备并非 Google 认证设备，但如果同一个包也会在认证设备上通过 Google Play 以外的渠道安装，请在 Android Developer Console 中注册该包名。

第 7 步：准备应用详情

AppGallery 的应用详情规范与 Apple 和 Google 不同：

请勿复用显示 Google Play 标志、其他制造商品牌 Android 设备边框或“Get it on Google Play”徽章的截图。华为会拒绝引用其他商店的列表。对于其他素材，请复用您为其他商店制作的内容；我们的 App Store 和 Google Play 列表指南 涵盖了这些内容。

第 8 步：上传、提交与审核

1. 在 版本信息 > 草稿，在以下位置上传 APK 软件版本.
2. 填写商店信息、内容分级、隐私政策和上架国家/地区。
3. 设置发布时间（审核通过后立即发布或定时发布）。
4. 提交审核。

审核通常需要几个工作日。拒审通知会通过邮件发送，并附上对应的指南条款。Capacitor 应用常见的拒审原因：

• 依赖 Google Play 服务才能运行的功能 （登录按钮点击无反应，地图页面空白）。
• 重复应用：AppGallery 上已有其他开发者提交了相同包名的应用，或华为此前已从 Google Play 复制了您的应用。请携带所有权证明联系华为开发者支持。
• 提及其他应用商店 出现在截图或文本中。
• 缺少英文 用于国际发行。
• 隐私政策 缺失或无法从应用内部访问。

AppGallery Connect 也提供发布 API，因此首个版本上线后，您可以从 CI 自动化上传。

第 9 步：保持更新快速

每次原生更改都需要再次通过华为审核，与其他商店一样。对于 JavaScript、HTML 和 CSS 更改， Capgo 实时更新 只需一次 upload，就能把新 bundle 直接下发到华为、Google 和 Apple 设备上的已安装应用，因为 updater 会从你的 Capgo endpoint 获取 bundle，不使用 Google Play services。如果华为 build 功能不同，请使用专用 channel：

bunx @capgo/cli@latest bundle upload --channel huawei

在构建时为华为 build 设置默认 channel，或在应用里把设备分配到该 channel。有关 Capgo updater 文档 会说明 channel 和配置。

清单

• 依赖审计已完成，已列出仅 GMS 的功能
• 已添加运行时服务检查，并在华为真机上测试通过
• 已隐藏或替换仅限 Google 的功能（推送、登录、计费、地图、评价）
• HUAWEI Developers 账号已验证
• 已创建应用，包名与以下相同： capacitor.config.ts
• Release APK 已用备份的 keystore 签名， versionCode 已更新
• 图标、3 到 8 张截图、简短及完整介绍、隐私政策
• 上架素材中不得出现 Google Play 相关内容
• 如有需要，提供审核员测试账号
• 已提交，正在监控审核邮件

如果你也在准备 Google Play，请阅读 如何创建 Apple 和 Google Play 开发者账号 关于仅适用于 Google Play 的 12 名测试人员规则。