本页面介绍了 Maps JavaScript API 可能会返回的错误消息。Maps JavaScript API 会将错误消息和警告消息写入 JavaScript 控制台。还可能会出现某些错误情况，导致显示暗色水印地图。
API 密钥和结算错误
问题排查
在某些情况下，可能会显示暗色地图或“负”街景图像，并带有“仅用于开发目的”的文字水印。如果出现此行为，通常说明存在 API 密钥或结算方面的问题。为了使用 Google Maps Platform 产品，必须为账号启用结算功能，并且所有请求都必须包含有效的 API 密钥。如需有关如何查找错误消息的帮助，请参阅在浏览器中查看错误部分。
以下流程有助于排查问题。
面向开发者和网站所有者的 Maps JavaScript API 错误代码
下表列出了 Maps JavaScript API 可能返回的错误代码，并说明了引起问题的原因以及解决方法。如需有关如何查找错误消息的帮助，请参阅在浏览器中查看错误部分。
地图加载错误
如果您在加载 Maps JavaScript API 时遇到了错误，请参阅下表查找关于相应错误代码的说明。
| 错误代码 | 提示 | 说明 |
|---|---|---|
NotLoadingAPIFromGoogleMapsError
|
必须直接从 Google 的服务器下载 Maps JavaScript API。 |
您的页面中未正确包含用于加载 Maps JavaScript API 的脚本元素。为确保 API 正常工作，必须直接从 https://maps.googleapis.com 进行加载。 |
TOSViolationMapError
|
此网站似乎违反了 Google Maps API 服务条款，因此无法使用 Google Maps API。 |
经过数次电子邮件通知后，您的应用仍不符合 Google Maps Platform 服务条款，因而被屏蔽。要对该屏蔽决定进行申诉并让我们审核您的实现情况，请填写此表单。您将在几个工作日内收到电子邮件回复。 如果您有 Google Maps Platform 专业版方案许可，请使用 Google Maps Platform 专业版方案凭据解决此错误。请参阅有关专业版方案身份验证的指南。 |
UnauthorizedURLForClientIdMapError
|
此网址未获得相关授权，无法使用提供的 Google 地图客户端 ID。 |
脚本加载中包含的专业版方案或 Maps API for Work 客户端 ID 无效、已过期，或者用于加载 Maps JavaScript API 的当前地址尚未添加到已授权的网址列表。 请查看注册已授权网址。 |
Maps JavaScript API 错误代码
如果您在 Chrome JavaScript 控制台、Firefox Web 控制台或您浏览器上的任何其他同类工具中发现错误，请参阅下表，查找对相应错误代码的说明。
Maps JavaScript API 会返回错误和警告。错误表示加载 Maps JavaScript API 时发生了严重问题。您的页面无法正确加载该 API，因此该 API 不能在该页面上工作。警告是有关 Maps JavaScript API 加载情况的补充消息。警告会描述错误的可能原因，或指出用于加载 Maps JavaScript API 的代码存在的潜在问题。如果您只收到警告而没有收到任何错误，则 API 将在该页面上正常工作。不过，我们还是建议您解决这些潜在问题。
| 开发者错误代码 | 类型 | 说明 |
|---|---|---|
ApiNotActivatedMapError
|
错误 |
您的 API 项目中未激活 Maps JavaScript API。您可能需要在 Google Cloud 控制台中的“API”下启用 Maps JavaScript API。 要为您的项目激活 Maps JavaScript API，请点击下面的按钮。
|
ApiTargetBlockedMapError
|
错误 |
此 API 密钥未获得相关授权，无法使用此服务或 API。请在 Google Cloud 控制台中检查您的 API 密钥的 API 限制设置，确保已启用的 API 列表中正确指定了您需要使用的所有 API 和服务。 请前往 Cloud 控制台查看 API 密钥。如需了解详情，请参阅 API 安全性最佳实践。 |
DeletedApiProjectMapError
|
错误 |
您的 API 项目可能已从 Cloud 控制台中删除。请检查 JavaScript API 加载器包含的 API 密钥是为哪个项目生成的。您可以在 Cloud 控制台中创建新的 API 项目并获取新密钥。 要创建新项目并为该项目获取 API 密钥，请点击下面的按钮。
|
ClientBillingNotEnabledMapError
|
错误 |
您尚未为项目启用结算功能。您必须在此处为与此客户端 ID 关联的 Google Cloud 项目启用结算功能。 |
BillingNotEnabledMapError
|
错误 |
您尚未为项目启用结算功能，这导致出现了此错误。您必须在此处为 Google Cloud 项目启用结算功能。 |
ExpiredKeyMapError
|
错误 |
用于加载 API 的脚本元素中包含的 API 密钥已过期或系统无法识别。在创建新的 API 密钥后，如果您在系统识别该密钥之前就尝试使用它，就可能会收到此错误。请过几分钟后重试，不然您可能需要在 Cloud 控制台中生成新的 API 密钥。 要获取 API 密钥，请点击下面的按钮。
|
InvalidAppCheckTokenMapError
|
错误 |
提供的 App Check 令牌无效或已过期。只有在使用 App Check 验证时才会发生此错误。 请参阅 App Check 验证指南。 |
InvalidClientIdMapError
|
错误 |
用于加载 API 的脚本元素中包含的客户端 ID 无效或已过期。请确保正确使用客户端 ID。客户端 ID 应以“gme-”前缀开头。如果您在正确使用客户端 ID 的情况下仍看到此错误，则表示客户端 ID 可能已过期。请联系您的 Google 客户经理。
如果您没有专业版方案许可或 Maps API for Work 许可，则需要使用 请参阅有关专业版方案身份验证的指南。 |
InvalidKeyMapError
|
错误 |
未找到用于加载 API 的脚本元素中所包含的 API 密钥。请确保您使用的是正确的 API 密钥。您可以在 Cloud 控制台中生成新的 API 密钥。 要获取 API 密钥，请点击下面的按钮。
|
MalformedCredentialsMapError
|
错误 |
您的应用使用的 URI 架构不受支持。请确认应用使用的是 RFC 3986 中规定的有效 URI 格式。 |
MissingKeyMapError
|
错误 |
加载 API 的脚本元素缺少必需的身份验证参数。 如果您使用的是标准 Maps JavaScript API，则必须使用 如果您是专业版方案客户，则必须使用 如果您不是网站所有者，则无法采取任何措施来修复此错误。不过，如果可能的话，建议您通知网站所有者。 |
ProjectDeniedMapError
|
错误 |
您的请求尚未完成。您或许可以在 Cloud 控制台中找到有关该错误的更多详细信息。 请查看 Cloud 控制台。 |
RefererDeniedMapError
|
错误 |
经过数次电子邮件通知后，您的应用仍不符合 Google Maps Platform 服务条款，因而被屏蔽。要对该屏蔽决定进行申诉并让我们审核您的实现情况，请填写此表单。您将在几个工作日内收到电子邮件回复。 |
RefererNotAllowedMapError
|
错误 |
加载 Maps JavaScript API 的当前网址尚未添加到允许的引荐来源网址列表中。请在 Cloud 控制台中检查您的 API 密钥的引荐来源网址设置。 请查看 Maps JavaScript API 并获取 API 密钥。 |
OverQuotaMapError
|
错误 |
请求次数已超过 Maps JavaScript API 的用量限额。应用的请求将在下一次每日配额重置时恢复正常。 如果您不是网站所有者，则无法采取任何措施来修复此错误。不过，如果可能的话，建议您通知网站所有者。 如需了解详情，请参阅有关用量限额的指南。该页面还说明了如何才能获得更高的用量限额。 |
ApiProjectMapError
|
错误 |
提供的 API 密钥或与其关联的 API 项目无法进行解析。此错误可能是暂时性的。如果此错误消息持续出现，您可能需要获取新的 API 密钥或创建新的 API 项目。 如需了解详情，请参阅 Google Maps Platform 使用入门。 |
ClientIdLooksLikeCryptoKey
|
警告 |
您在 请参阅适用于专业版方案和 Maps API for Work 客户的客户端 ID 指南。 |
ClientIdLooksLikeKey
|
警告 |
您可能在 请参阅有关专业版方案身份验证的指南。 |
InvalidChannel
|
警告 |
您提供的 |
InvalidClientId
|
警告 |
请参阅有关专业版方案身份验证的指南。 |
InvalidKey
|
警告 |
用于加载 API 的脚本元素中包含的 API 密钥似乎不正确。请确保您使用的是正确的 API 密钥。您可以在 Cloud 控制台中生成新的 API 密钥。 要获取 API 密钥，请点击下面的按钮。
|
InvalidVersion
|
警告 |
您在脚本元素中提供的版本号可能不正确。请确保您使用的版本号正确无误。 |
KeyLooksLikeClientId
|
警告 |
您可能以 key 参数的形式提供了客户端 ID。如果您有专业版方案许可或 Maps API for Work 许可，请以 client 参数（而不是 key 参数）的形式指定您的客户端 ID。如果您有 Google Maps Platform 专业版方案，则既可以使用 client 参数，也可以使用 key 参数。如果您没有任何许可，则必须使用 key 参数，而不是 client
参数。
请参阅有关专业版方案身份验证的指南。 |
KeyLooksLikeCryptoKey
|
警告 |
您可能以 请参阅有关在加载 API 时指定客户端 ID 的指南。 |
KeyLooksLikeProjectNumber
|
警告 |
您可能以 了解如何获取 API 密钥。 |
NoApiKeys
|
警告 |
用于加载 API 的脚本元素中没有 API 密钥。请务必以
要获取 API 密钥，点击下方的按钮即可开始。
如果您是从已弃用的 v2 路径加载 Maps JavaScript API 的，则会收到 |
RetiredVersion
|
警告 |
您在脚本元素中提供的版本可能已弃用。请更新您的应用以使用一个可用版本。 |
SensorNotRequired
|
警告 |
Maps JavaScript API 不再需要 |
SignatureNotRequired
|
警告 |
Maps JavaScript API 不需要 |
SignedInNotSupported
|
警告 |
|
UrlAuthenticationCommonError
|
错误 |
发生了不归属此页面上其他类别的错误。这可能是由临时问题所致。请稍等片刻后重试请求。如果仍无法解决问题，请参阅开发者指南，确保请求的格式正确无误。 |
在浏览器中查看错误
Maps JavaScript API 会将错误消息写入 window.console。本部分说明了如何在 Google Chrome 中查看 window.console 输出。如果您使用的是任何其他浏览器，请查阅您的浏览器的开发者文档。以下列出了一些其他浏览器中用于查看 window.console 输出的工具，供您参考。
- Web 控制台，适用于 Firefox。
- 远程调试，适用于 Android。
- Web Inspector，适用于 iOS。
在 Chrome 中，您可以使用 JavaScript 控制台查看 window.console 输出，如下所示。
- 依次选择菜单图标 >“更多工具”>“开发者工具”，打开“开发者工具”。
- 按键盘上的 ESC 键，打开 JavaScript 控制台。 ESC 键用于开关 JavaScript 控制台。如果关闭了控制台，再次按 ESC 键可将其打开。
加载 Maps JavaScript API 时出现的任何错误或警告会在控制台中显示为一行或多行。错误或警告消息的格式如下：
Google Maps API error: [ERROR CODE] [Link to API document]
或
Google Maps API warning: [ERROR CODE] [Link to API document]
您可以查看上文中的错误代码表格，找到错误消息中的错误代码。您还可以在错误消息链接的 API 文档中找到有关该消息的详细信息。
注意：您可以通过程序化方式监听身份验证错误。
处理不受支持的浏览器
确保您使用的浏览器版本目前受 Maps JavaScript API 支持。
如果您要开发在 WebView 中运行的原生 Windows 应用，请确保您使用的是基于 Edge 的 WebView2。我们已不再支持基于 Internet Explorer 的旧版 WebView。
如果您的代码仍不能正常运行
为帮助您确保地图代码正常运行，Brendan Kenny 和 Mano Marks 在此视频中介绍了一些常见错误及相应解决方法。
- 查找拼写错误。请注意，JavaScript 语言区分大小写。
- 检查基础环节，因为一些最常见的问题往往发生在地图创建的初始阶段。例如：
- 确认您已在地图选项中指定
zoom和center属性。 - 确保您已声明用于容纳出现在屏幕上的地图的 div 元素。
- 确保地图的 div 元素已设置高度。默认情况下，div 元素创建时的高度为 0，因此不可见。
- 确认您已在地图选项中指定
- 使用 JavaScript 调试程序（例如 Chrome 开发者工具中的调试程序）发现问题。首先查看 JavaScript 控制台中是否存在错误。
- 将问题发布到 Stack Overflow 中。如需了解有关如何发布优质问题的指南，请访问支持页面。