如何在 Huawei AppGallery 发布 Capacitor App

你可以使用与 Google Play 相同的 Android build 在 Huawei AppGallery 发布 Capacitor App。首先注册免费的 HUAWEI Developers 账号，检查哪些 plugin 依赖 Google Play 服务（2019 年底以后发布的华为手机均不包含此服务），隐藏或替换这些功能，然后在 AppGallery Connect 中上传签名后的 APK 并填写上架信息，等待审核即可。本指南将涵盖每个步骤，包括一段你可以直接集成到 App 中、无需额外依赖即可检测 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 services 是否已更新或已启用；如果你也需要该功能，请添加 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 你只需初始化当前显示的 provider 即可。
• 支付：Google Play Billing 不可用。AppGallery 有自己的 Huawei IAP。如果数字购买是应用的核心功能，可以集成 Huawei IAP，或发布不带购买功能的 AppGallery 版本，并在商店详情中说明。
• 推送：HMS 设备请使用 Huawei Push Kit。没有官方的 Capacitor 插件；Huawei 在以下位置发布 Cordova 插件： @hmscore/* 这些插件可在 Capacitor 中运行，或者你也可以基于 Push Kit SDK 编写一个小型原生插件。
• 地图：在 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. 完成 身份验证 （个人或企业）。个人通常需要提供身份证件和银行卡信息；企业则需提供营业执照。审核通常需要一到两个工作日。
3. 请仔细选择账号类型和国家/地区。华为不支持将个人账号转换为企业账号，且验证后的国家或地区后续无法更改。

注册是免费的。

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

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

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

AppGallery 支持 APK 和 AAB 格式。APK 流程更简单：你使用自己的密钥进行签名，Huawei 无需持有你的签名密钥。

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 则要求使用其 App Signing 服务，这意味着 Huawei 会生成并持有最终的签名密钥，其模式与 Play App Signing 相同。

上传前请检查以下事项：

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

第 7 步：准备应用详情

AppGallery 的上架规范与 Apple 和 Google 不同：

请勿重复使用带有 Google Play logo、其他厂商品牌的 Android 设备边框或 “Get it on Google Play” 徽章的截图。Huawei 会拒绝包含其他应用商店信息的上架申请。对于其他素材，可以复用为其他商店准备的内容；我们的 App Store 与 Google Play 上架指南 涵盖了这些内容。

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

1. 在 版本信息 > 草稿中，上传 APK 文件 软件版本.
2. 填写上架信息、评分、隐私政策及适用国家。
3. 设置发布时间（审核通过后立即发布或定时发布）。
4. 提交审核。

审核通常需要几个工作日。如果被拒绝，会通过邮件发送包含指南参考的通知。Capacitor 应用常见的拒绝原因包括：

• 缺少 Google Play 服务时无法运行的功能 (登录按钮无效，屏幕空白)。
• 应用重复：AppGallery 上已存在包名相同的其他开发者应用，或者华为之前从 Google Play 复制过您的应用。请联系华为开发者支持并提供所有权证明。
• 其他应用商店引用 于截图或文本中。
• 缺少英文内容 以进行国际化发行。
• 隐私政策 缺失或无法在应用内访问。

AppGallery Connect 还提供 Publishing API，因此在首个版本上线后，您可以实现从 CI 自动上传。

第 9 步：保持快速更新

与其它应用商店一样，每次 Native Build 的变更都需要重新通过华为审核。而对于 JavaScript、HTML 和 CSS 的变更， Capgo Live Updates 只需一次 upload，即可将新 bundle 直接推送至华为、Google 和 Apple 设备上的已安装应用，因为 updater 会从您的 Capgo 端点获取 bundle，而不依赖 Google Play services。如果您的华为版本包含不同的功能，请使用专用 channel：

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

在构建时为华为版本设置默认 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 开发者账号 关于仅适用于这些平台的 12 位测试人员规则。