一切就绪!

着手开发前,请先阅读我们的开发者文档

激活 Google Maps JavaScript API

为帮助您起步,我们将引导您在 Google Developers Console 中先完成几项任务:

  1. 创建或选择项目
  2. 激活 Google Maps JavaScript API 及相关服务
  3. 创建相应密钥
继续

版本控制

Google Maps JavaScript API 团队会定期更新 API,以加入新的功能、修复 bug 并提升其性能。本页面介绍可供您的应用使用的 API 版本(无论是测试环境还是生产环境)。API 版本具有下列名称:

  • 试验性
  • 发行
  • 冻结

我们还提供基于应用类型或用途的版本控制程序管理最佳做法。

版本轮转和版本类型

每个季度我们都会砍掉一个新的编号版本,将其作为试验性版本公开发行。同时,上一试验性版本变成发行版本,上一发行版本变成冻结版本。此过程称为版本轮转

在整个季度,我们会继续向试验性版本和发行版本添加错误修复。Google Maps JavaScript API 发行说明中对这些更新做了说明。

您可以指明在您的应用中加载哪个版本的 API,为此,您只需指定 Google Maps JavaScript API 引导程序请求的 v 参数。支持的选项如下:

  • 试验性版本,指定方式:v=3.exp
  • 发行版本,指定方式:v=3
  • 具体版本号。例如:v=3.25v=3.26

如果您未明确指定版本并且使用标准计划(包括未提供密钥的客户),默认情况下,您将收到实验性版本。如果您使用高级计划并且未指定版本,那么在默认情况下,您将收到发布版本。

试验性版本

试验性版本–当前版本为 3.27–包含公开提供的最新功能和错误修复。对试验性版本所做的更改不能保证功能稳定性。我们鼓励您定期使用实验性版本测试您的应用,加载 API 时添加 v=3.27 可以执行测试。如果您喜欢尝鲜,则可以添加 v=3.exp,始终接收带有全部最新功能的当前实验性版本。

您可以通过以下引导程序指定试验性版本:

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.exp
        &key=YOUR_API_KEY&callback=initMap">

发行版本

我们会继续对发行版本应用错误修复,同时确保功能集保持稳定。发行说明中列出了这些修复。

当前发行版本是 3.26。您可以通过以下任一引导程序请求该版本:

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3
        &key=YOUR_API_KEY&callback=initMap">

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.26
        &key=YOUR_API_KEY&callback=initMap">

冻结版本

当我们发行一个新的编号版本时,将会冻结上一发行版本,这意味着我们不再通过定期错误修复对其进行更新。不过,我们可能偶尔对其做出更改,例如出于法律原因需要做出更改时。

我们每次推出新的冻结版本时,都会退役上一冻结版本。指定 v=3.0 等已退役版本将一律返回当前冻结版本。

当前冻结版本是 3.25。您可以通过以下引导程序请求该版本:

<script async defer
    src="https://maps.googleapis.com/maps/api/js?v=3.25
        &key=YOUR_API_KEY&callback=initMap">

最佳做法

Google Maps JavaScript API 团队将不遗余力地保持不同 API 版本的兼容性。不过,为了能继续提供现代化的服务,以及出于运营上的原因,我们偶尔会做出可能影响现有功能的更改。在此类情况下,可能有必要利用 Google Maps JavaScript API 对代码进行调整,以便让代码继续发挥应有的作用,这种调整对更高级的应用而言尤为必要。以下是我们针对若干常见情形提供的有关版本使用的最佳做法建议。

对于高可用性/高流量应用

愿意付出额外的努力来确保稳定性和可用性

为确保不因版本轮转而引发问题,我们建议您在引导程序中显式地指定 API 的当前发行版本号。例如,v=3.26。为避免随时间推移降至 API 的冻结版本,必须在 Google Maps JS API v3 通知和公告组中订阅 Google 提供的版本轮转通知。

在版本轮转(每个季度)之后,您的生产系统将请求冻结版本的 API。目前,我们建议您设置一个暂存/开发环境,以便使用新发布版本的 API 测试您的应用。如果出现任何问题,您可以对代码进行必要调整。当您确信应用可以在 API 的新发行版本上平稳运行时,可以推出必要的修复(如有),同时更新您的应用,以请求与新发行版本对应的版本号。

对于普通应用

我们建议在您的引导程序请求中指定 v=3。这意味着您将始终获得 Google Maps JavaScript API 的当前发行版本,该版本经受过高流量考验并且应用了必要的错误修复。大多数情况下,在版本轮转时通常不需要采取任何措施。不过,为确保您的应用继续平稳地工作,我们建议在 Google Maps JS API v3 通知和公告组中订阅 Google 提供的版本轮转通知。

轮转完成后,您的应用将使用 Google Maps JavaScript API 的新版本。您可能还想查看发行说明,以获悉任何可能影响您的变动。如果您注意到应用的任何方面工作不正常,可通过在您的引导程序请求中显式指定当前冻结版本号暂时切换回旧版本,同时在您的代码中做出必要的调整。

对于前沿应用

愿意提前获得最新功能

对于持续可用性不太重要的应用,我们建议您通过请求 Google Maps JavaScript API 的试验性版本 (v=3.exp) 来获得所有最新功能。每周发布前 Google 都会对试验性版本做全面测试,因此该版本通常相当稳定。不过,发行周期只有短短一周意味着必须保持额外的警惕性,以确保您的应用继续如常工作。

检查版本

要进行调试,请使用 google.maps.version 属性为您的应用获取当前版本的 Google Maps JavaScript API。下面的代码示例会将 API 版本写入浏览器控制台。(如需了解有关浏览器控制台的详细信息,请参阅在浏览器中检查错误指南。)

<!DOCTYPE html>
<html>
  <head>
    <title>Display Google Maps API Version</title>
  </head>
  <body>
    <script>
      function initMap() {
        // Add your map here.
        console.log('Google Maps API version: ' + google.maps.version);
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

各 API 版本的文档

开发者指南介绍的内容一律是试验性版本。

此外,各版本还有单独维护的参考资料:

发送以下问题的反馈:

此网页
Google Maps JavaScript API
Google Maps JavaScript API
需要帮助?请访问我们的支持页面