在Android Studio项目中添加MapBox Navigation遇到问题求解决

算力阿峰

2026-9-30

修复下载密钥配置
首先确认你已在MapBox账号后台生成拥有下载权限的专属Token，在项目根目录的gradle.properties文件中添加如下配置：
```
MAPBOX_DOWNLOADS_TOKEN=你生成的带下载权限的Token
```
注意不要将该配置文件上传到公共代码仓库，需提前加入.gitignore规则。
修正仓库配置
AGP 7.0+版本默认将全局仓库配置放在settings.gradle的dependencyResolutionManagement > repositories块中，你需要同时修改项目级build.gradle和settings.gradle的仓库配置：
1. 删除已废弃的jcenter()、https://mapbox.bintray.com/mapbox仓库配置
2. 保留并确保MapBox官方maven仓库配置同时出现在两处仓库块中：
```
maven {
    url 'https://api.mapbox.com/downloads/v2/releases/maven'
    authentication {
        basic(BasicAuthentication)
    }
    credentials {
        username = "mapbox"
        password = project.properties['MAPBOX_DOWNLOADS_TOKEN'] ?: ""
    }
}
google()
mavenCentral()
```
解决依赖版本兼容问题
你当前使用的0.42.6版本MapBox导航SDK已停止维护，和AGP 7.0+版本存在兼容性问题，建议按如下方式调整：
1. 模块级build.gradle中调整minSdkVersion至少为23，compileSdkVersion至少为33
2. 替换为当前稳定维护的v2版导航SDK依赖：
```
implementation 'com.mapbox.navigation:android:2.16.0'
implementation 'com.mapbox.search:mapbox-search-android:1.0.0'
implementation 'com.google.android.material:material:1.9.0'
```
如果你必须使用旧版0.42.6导航SDK，请将AGP版本降级到4.2.x，minSdkVersion调整为21，同时删除新版MapBox maven仓库配置，仅保留旧版bintray仓库。
补充遗漏配置
1. 在模块级AndroidManifest.xml的application块中添加公开访问Token配置：
```
<meta-data
    android:name="com.mapbox.token"
    android:value="你的MapBox公开Token" />
```
1. 如果你开启了代码混淆，在proguard-rules.pro中添加MapBox官方混淆规则。
2. 检查gradle/wrapper/gradle-wrapper.properties中的Gradle版本和AGP版本匹配，AGP 7.0.2对应Gradle版本需为7.0.2及以上兼容版本。