React Native 0.74.0集成HMS Map Kit地图不显示求助

API 探路者

2026-6-23

问题：React Native 0.74.0集成HMS Map 6.11.2-302无法显示地图

我在React Native 0.74.0中集成版本为6.11.2-302的@hmscore/react-native-hms-map，但始终无法成功显示地图。已经多次调整gradle和agconnect版本，问题仍未解决，希望得到帮助，同时想了解开发模式下让地图正常显示的方法。

项目配置代码

Android根目录下的build.gradle

buildscript { 
    ext { 
        buildToolsVersion = "34.0.0" 
        minSdkVersion = 23 
        compileSdkVersion = 34 
        targetSdkVersion = 34 
        ndkVersion = "26.1.10909125" 
        kotlinVersion = "1.9.22" 
    } 
    repositories {
        google() 
        mavenCentral() 
        maven { url 'https://developer.huawei.com/repo/' } 
    }
    dependencies {
        classpath("com.android.tools.build:gradle:8.3.2") 
        classpath("com.facebook.react:react-native-gradle-plugin") 
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") 
        classpath 'com.huawei.agconnect:agcp:1.9.1.301' 
    } 
} 
allprojects { 
    repositories { 
        google() 
        mavenCentral() 
        maven { url 'https://developer.huawei.com/repo/' } 
    } 
} 
apply plugin: "com.facebook.react.rootproject"

Android/app目录下的build.gradle

apply plugin: "com.android.application" 
apply plugin: "com.huawei.agconnect" 
apply plugin: "org.jetbrains.kotlin.android" 
apply plugin: "com.facebook.react"

/**
This is the configuration block to customize your React Native Android app.
By default you don't need to apply any configuration, just uncomment the lines you need. 
*/ 
react { 
    /* Folders */ 
    //   The root of your project, i.e. where "package.json" lives. Default is '..' 
    // root = file("../") 
    //   The folder where the react-native NPM package is. Default is ../node_modules/react-native 
    // reactNativeDir = file("../node_modules/react-native") 
    //   The folder where the react-native Codegen package is. Default is ../node_modules/@react-native/codegen 
    // codegenDir = file("../node_modules/@react-native/codegen") 
    //   The cli.js file which is the React Native CLI entrypoint. Default is ../node_modules/react-native/cli.js 
    // cliFile = file("../node_modules/react-native/cli.js")

    /* Variants */ 
    //   The list of variants to that are debuggable. For those we're going to 
    //   skip the bundling of the JS bundle and the assets. By default is just 'debug'. 
    //   If you add flavors like lite, prod, etc. you'll have to list your debuggableVariants. 
    // debuggableVariants = ["liteDebug", "prodDebug"]

    /* Bundling */ 
    //   A list containing the node command and its flags. Default is just 'node'. 
    // nodeExecutableAndArgs = ["node"] 
    // 
    //   The command to run when bundling. By default is 'bundle' 
    // bundleCommand = "ram-bundle" 
    // 
    //   The path to the CLI configuration file. Default is empty. 
    // bundleConfig = file(../rn-cli.config.js) 
    // 
    //   The name of the generated asset file containing your JS bundle 
    // bundleAssetName = "MyApplication.android.bundle" 
    // 
    //   The entry file for bundle generation. Default is 'index.android.js' or 'index.js' 
    // entryFile = file("../js/MyApplication.android.js") 
    // 
    //   A list of extra flags to pass to the 'bundle' commands. 
    //   See https://github.com/react-native-community/cli/blob/main/docs/commands.md#bundle 
    // extraPackagerArgs = []

    /* Hermes Commands */ 
    //   The hermes compiler command to run. By default it is 'hermesc' 
    // hermesCommand = "$rootDir/my-custom-hermesc/bin/hermesc" 
    // 
    //   The list of flags to pass to the Hermes compiler. By default is "-O", "-output-source-map" 
    // hermesFlags = ["-O", "-output-source-map"] 
}

/**
Set this to true to Run Proguard on Release builds to minify the Java bytecode. 
*/ 
def enableProguardInReleaseBuilds = false

/**
The preferred build flavor of JavaScriptCore (JSC)

For example, to use the international variant, you can use:
def jscFlavor = 'org.webkit:android-jsc-intl:+'

The international variant includes ICU i18n library and necessary data
allowing to use e.g. Date.toLocaleString and String.localeCompare that
give correct results when using with locales other than en-US. Note that
this variant is about 6MiB larger per architecture than default. 
*/ 
def jscFlavor = 'org.webkit:android-jsc:+'

android { 
    ndkVersion rootProject.ext.ndkVersion 
    buildToolsVersion rootProject.ext.buildToolsVersion 
    compileSdk rootProject.ext.compileSdkVersion

    namespace "com.koipo.admin"
    defaultConfig {
        applicationId "com.koipo.admin"
        minSdkVersion rootProject.ext.minSdkVersion
        targetSdkVersion rootProject.ext.targetSdkVersion
        versionCode 1
        versionName "1.0"
    }
    signingConfigs {
        debug {
            storeFile file('mykeystore.jks')
            storePassword '123456'
            keyAlias 'grekosys'
            keyPassword '123456'
        }
    }
    buildTypes {
        debug {
            signingConfig signingConfigs.debug
        }
        release {
            // Caution! In production, you need to generate your own keystore file.
            // see https://reactnative.dev/docs/signed-apk-android.
            signingConfig signingConfigs.debug
            minifyEnabled enableProguardInReleaseBuilds
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
        }
    }

}

dependencies { 
    // The version of react-native is set by the React Native Gradle Plugin 
    implementation("com.facebook.react:react-android") 
    implementation 'com.huawei.hms:maps:6.11.2.301'

    if (hermesEnabled.toBoolean()) {
        implementation("com.facebook.react:hermes-android")
    } else {
        implementation jscFlavor
    }

}

apply from: file("../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); 
applyNativeModulesAppBuildGradle(project)

index.js

/**
@format 
*/

import {AppRegistry} from 'react-native'; 
import App from './App'; 
import {Mapa} from './Koipo/Mapa'; 
import {name as appName} from './app.json';

AppRegistry.registerComponent(appName, () => Mapa);

Mapa.js

import React from 'react'; 
import {StyleSheet, Text, View} from 'react-native'; 
import HMSMap, {MapTypes} from '@hmscore/react-native-hms-map';

export function Mapa() { 
    return ( 
        <View style={styles.vista}> 
            <HMSMap 
                mapType={MapTypes.NORMAL} 
                style={{height: 400}} 
                camera={{target: {latitude: 41, longitude: 29}, zoom: 11}} 
            /> 
            <Text>Mapas</Text> 
        </View> 
    ); 
}

const styles = StyleSheet.create({ 
    vista: { 
        flex: 1, 
    }, 
});

AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="com.huawei.appmarket.service.commondata.permission.GET_COMMON_DATA"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

<application
    android:name=".MainApplication"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:allowBackup="false"
    android:theme="@style/AppTheme"
    android:requestLegacyExternalStorage="true"
    android:usesCleartextTraffic="true">
    <meta-data
        android:name="com.huawei.hms.api.API_KEY"
        android:value="xxxxxx" />
    <meta-data
        android:name="com.huawei.hms.client.appid"
        android:value="1111222"/>
    
    <activity
        android:name=".MainActivity"
        android:label="@string/app_name"
        android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"
        android:launchMode="singleTask"
        android:windowSoftInputMode="adjustResize"
        android:exported="true">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>

核心排查点与修复方案

API Key与AppID格式校验
- AndroidManifest.xml中com.huawei.hms.client.appid格式错误，必须添加appid=前缀，正确格式为android:value="appid=1111222"；同时确认API_KEY是对应当前debug签名SHA-256生成的有效密钥。
依赖版本严格匹配
- 当前@hmscore/react-native-hms-map 6.11.2-302要求HMS Maps SDK版本为6.11.2.302，但你配置的是6.11.2.301，修改app/build.gradle中的依赖：
```
implementation 'com.huawei.hms:maps:6.11.2.302'
```
开发签名与后台配置一致
- 用以下命令获取debug签名的SHA-256值：
```
keytool -list -v -keystore mykeystore.jks -storepass 123456
```
- 将该值更新到华为开发者联盟对应应用的配置页面，确保签名信息匹配。

地图组件布局完善

给HMSMap添加宽度属性，确保组件能正常渲染：

<HMSMap 
    mapType={MapTypes.NORMAL} 
    style={{height: 400, width: '100%'}} 
    camera={{target: {latitude: 41, longitude: 29}, zoom: 11}} 
/>

动态申请位置权限

Android 6.0+需要动态申请位置权限，在Mapa组件中添加权限申请逻辑：

import {PermissionsAndroid, useEffect} from 'react-native';

export function Mapa() { 
    useEffect(() => {
        const requestLocationPermission = async () => {
            const granted = await PermissionsAndroid.request(
                PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
                {
                    title: "地图位置权限",
                    message: "应用需要位置权限以加载地图瓦片",
                    buttonPositive: "允许"
                }
            );
            if (granted === PermissionsAndroid.RESULTS.GRANTED) {
                console.log("位置权限已获取");
            }
        };
        requestLocationPermission();
    }, []);

    return ( 
        <View style={styles.vista}> 
            <HMSMap 
                mapType={MapTypes.NORMAL} 
                style={{height: 400, width: '100%'}} 
                camera={{target: {latitude: 41, longitude: 29}, zoom: 11}} 
            /> 
            <Text>Mapas</Text> 
        </View> 
    ); 
}

开发模式调试技巧

打开Android Studio的Logcat，过滤HMSMap或HuaweiMap关键词，查看是否有授权失败、密钥错误、网络请求失败等具体报错。
确保测试设备网络能正常访问华为地图服务（国内设备无需额外配置，海外设备需确认网络连通性）。
清理项目缓存：执行./gradlew clean（Android端），删除node_modules并重新执行npm install，重启Metro服务后重新构建。

内容的提问来源于stack exchange，提问作者Greñas Carreño

React Native 0.74.0集成HMS Map Kit地图不显示求助

项目配置代码 #

Android根目录下的build.gradle #

Android/app目录下的build.gradle #

index.js #

Mapa.js #

AndroidManifest.xml #

核心排查点与修复方案 #

开发模式调试技巧 #