错误消息

本页面介绍了 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 进行加载。

请参阅加载 Maps JavaScript API

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 密钥,请点击下面的按钮。
开始使用

InvalidClientIdMapError 错误

用于加载 API 的脚本元素中包含的客户端 ID 无效或已过期。请确保正确使用客户端 ID。客户端 ID 应以“gme-”前缀开头。如果您在正确使用客户端 ID 的情况下仍看到此错误,则表示客户端 ID 可能已过期。请联系您的 Google 客户经理。

如果您没有专业版方案许可或 Maps API for Work 许可,则需要使用 key 参数传递 API 密钥,而不是 client 参数。

请参阅有关专业版方案身份验证的指南。

InvalidKeyMapError 错误

未找到用于加载 API 的脚本元素中所包含的 API 密钥。请确保您使用的是正确的 API 密钥。您可以在 Cloud 控制台中生成新的 API 密钥。

要获取 API 密钥,请点击下面的按钮。
开始使用

MalformedCredentialsMapError 错误

您的应用使用的 URI 架构不受支持。请确认应用使用的是 RFC 3986 中规定的有效 URI 格式。

MissingKeyMapError 错误

加载 API 的脚本元素缺少必需的身份验证参数。

如果您使用的是标准 Maps JavaScript API,则必须使用 key 参数传递有效的 API 密钥。如需了解详情,请参阅 Google Maps Platform 使用入门

如果您是专业版方案客户,则必须使用 client 参数传递客户端 ID,或使用 key 参数传递有效的 API 密钥。如需了解详情,请参阅有关 API 密钥和客户端 ID 的指南。

如果您不是网站所有者,则无法采取任何措施来修复此错误。不过,如果可能的话,建议您通知网站所有者。

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 警告

您在 client 参数中提供的可能是加密密钥。如果您有专业版方案许可或 Maps API for Work 许可,请以 client 参数的形式指定您的客户端 ID。您无需为 Maps JavaScript API 使用加密密钥。

请参阅适用于专业版方案和 Maps API for Work 客户的客户端 ID 指南。

ClientIdLooksLikeKey 警告

您可能在 client 参数中提供了 API 密钥。如果您有专业版方案许可或 Maps API for Work 许可,请以 client 参数的形式指定您的客户端 ID。如果您有 Google Maps Platform 专业版方案,则既可以使用 client 参数,也可以使用 key 参数。如果您没有任何许可,则必须使用 key 参数,而不是 client 参数。

请参阅有关专业版方案身份验证的指南。

InvalidChannel 警告

您提供的 channel 参数可能无效。该参数必须是一个 ASCII 字母数字字符串,可包含英文句点 (.)、下划线 (_) 和连字符 (-)。请确保您指定的 channel 参数有效。

请参阅报告 | Google Maps Platform 专业版方案

InvalidClientId 警告

client 参数包含的客户端 ID 似乎不正确。客户端 ID 应以“gme-”开头。

请参阅有关专业版方案身份验证的指南。

InvalidKey 警告

用于加载 API 的脚本元素中包含的 API 密钥似乎不正确。请确保您使用的是正确的 API 密钥。您可以在 Cloud 控制台中生成新的 API 密钥。

要获取 API 密钥,请点击下面的按钮。
开始使用

InvalidVersion 警告

您在脚本元素中提供的版本号可能不正确。请确保您使用的版本号正确无误。

请参阅版本控制 | Google Maps JavaScript API

KeyLooksLikeClientId 警告 您可能以 key 参数的形式提供了客户端 ID。如果您有专业版方案许可或 Maps API for Work 许可,请以 client 参数(而不是 key 参数)的形式指定您的客户端 ID。如果您有 Google Maps Platform 专业版方案,则既可以使用 client 参数,也可以使用 key 参数。如果您没有任何许可,则必须使用 key 参数,而不是 client 参数。

请参阅有关专业版方案身份验证的指南。

KeyLooksLikeCryptoKey 警告

您可能以 key 参数的形式提供了加密密钥或签名密钥。如果您有专业版方案许可或 Maps API for Work 许可,请以 client 参数的形式指定您的客户端 ID,并从脚本元素中移除 key 参数。Maps JavaScript API 不需要加密密钥。如果您有 Google Maps Platform 专业版方案,则既可以使用 client 参数,也可以使用 key 参数。如果您没有任何许可,则可以在 Cloud 控制台中获取 API 密钥。

请参阅有关在加载 API 时指定客户端 ID 的指南。

KeyLooksLikeProjectNumber 警告

您可能以 key 参数的形式提供了项目编号。请确保您使用的是正确的 API 密钥。您可以在 Cloud 控制台中生成新的 API 密钥。

了解如何获取 API 密钥。

NoApiKeys 警告

用于加载 API 的脚本元素中没有 API 密钥。请务必以 key 参数的形式添加有效的 API 密钥。您可以在 Cloud 控制台中生成新的 API 密钥。

要获取 API 密钥,点击下方的按钮即可开始。
开始使用

如果您是从已弃用的 v2 路径加载 Maps JavaScript API,则会收到 NoApiKeys 警告,即使您指定了 key 参数也是如此。请查阅 v2 到 v3 升级指南,将您的应用迁移到 Maps JavaScript API v3。

RetiredVersion 警告

您在脚本元素中提供的版本可能已弃用。请更新您的应用以使用一个可用版本。

请参阅版本控制 | Google Maps JavaScript API

SensorNotRequired 警告

Maps JavaScript API 不再需要 sensor 参数。使用 sensor 参数不会阻止 Maps JavaScript API 正常工作,但我们建议您将其从脚本元素中移除。

SignatureNotRequired 警告

Maps JavaScript API 不需要 signature 参数。使用此参数不会阻止 Maps JavaScript API 正常工作,但可能会带来安全风险。请将其从您的脚本元素中移除。

SignedInNotSupported 警告

signed_in 参数已弃用,您使用的 Maps JavaScript API 版本不支持该参数。使用此参数不会阻止 Maps JavaScript API 正常工作,但如果您依赖登录功能,应用的行为可能会发生变化。

UrlAuthenticationCommonError 错误

发生了不归属此页面上其他类别的错误。这可能是由临时问题所致。请稍等片刻后重试请求。如果这不能解决问题,请参阅开发者指南,确保请求的格式正确无误。

在浏览器中查看错误

Maps JavaScript API 会将错误消息写入 window.console。本部分说明了如何在 Google Chrome 中查看 window.console 输出。如果您使用的是任何其他浏览器,请查阅您的浏览器的开发者文档。以下列出了一些其他浏览器中用于查看 window.console 输出的工具,供您参考。

在 Chrome 中,您可以使用 JavaScript 控制台查看 window.console 输出,如下所示。

  1. 依次选择菜单图标 >“更多工具”>“开发者工具”,打开开发者工具。
  2. 按键盘上的 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 语言区分大小写。
  • 检查基础环节 - 一些最常见的问题发生在地图创建的初始阶段。例如:
    • 确认您已在地图选项中指定 zoomcenter 属性。
    • 确保您已声明用于容纳出现在屏幕上的地图的 div 元素。
    • 确保地图的 div 元素已设置高度。默认情况下,div 元素创建时的高度为 0,因此不可见。
    如需了解参考实现,请参阅我们的示例。
  • 使用 JavaScript 调试程序(例如 Chrome 开发者工具中的调试程序)发现问题。首先查看 JavaScript 控制台中是否存在错误。
  • 将问题发布到 Stack Overflow 中。如需了解有关如何发布优质问题的指南,请访问支持页面。