版本控制

Maps JavaScript API 团队会定期更新 API,以加入新功能、修复 bug 并提升性能。本页面介绍了可用于您的应用的 API 版本。

发布渠道和版本号

您可以在应用中指定发布渠道或版本号:

  • 每周渠道v=weekly 指定。
    此渠道每周更新一次,提供的版本是最新的。
  • 季度渠道v=quarterly 指定。
    此渠道每季度更新一次,可预测性最高。
  • Beta 渠道v=beta 指定。
    此渠道基于 weekly 渠道,每周更新一次。其中包含一些额外的变更,方便进行早期测试和收集反馈。
  • Alpha 渠道v=alpha 指定。
    此渠道基于 beta 渠道,每周更新一次。其中包含实验性版本,用于收集客户对原型的反馈。此渠道仅用于开发目的,不应在生产环境中使用。
  • 版本号v=n.nn 指定。
    您可以选择 v=3.58v=3.57v=3.56v=3.55
    版本号每季度更新一次(请参阅季度更新)。

如果您未明确指定渠道或版本,系统将为您默认采用每周渠道。如果您是从专业版方案迁移而来,未明确指定渠道或版本,则默认采用季度渠道。如果您指定的版本无效,则采用默认的渠道。

选择每周渠道

对于大多数应用,建议使用每周渠道。此渠道提供的版本是最新的,包含最新的 bug 修复和性能提升。您可以使用以下脚本标记来加载 Maps JavaScript API,从而指定每周渠道:

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

目前,每周渠道提供的是版本 3.58。 此版本每周更新一次,以加入新功能、修复 bug 并提升性能。

11 月中旬,每周频道将更新为 版本 3.59。届时,新版本可能会移除已弃用的功能,并/或引入向后不兼容性。

选择季度渠道

某些应用可能更适合进行数量较少但规模较大的更新,因为这会提高可预测性。这些应用应使用季度渠道。如果您希望在预期的时间修复 bug 和提升性能,请使用此方法(请参阅季度更新)。您可以使用以下脚本标记来加载 Maps JavaScript API,从而指定季度渠道:

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

目前,季度渠道提供的版本为版本 3.57。 在本季度,此版本将不再接收新功能、bug 修复或性能提升。我们可能会不时地在此版本中引入安全性 bug 修复。

11 月中旬,季度渠道提供的版本将更新至版本 3.58。 届时,新版本将加入新功能、移除已弃用的功能并/或不再向后兼容前三个月的功能。

选择 Beta 渠道

使用 Beta 渠道可以试用新的 Beta 版功能和变更。Beta 版有完整的功能,但可能存在一些未解决的问题(请使用问题跟踪器报告问题并提供反馈)。Beta 渠道不在任何服务等级协议 (SLA) 或弃用政策的涵盖范围内,并且某些变更可能无法向后兼容早期版本。

此渠道基于 weekly 渠道,每周更新一次。

您可以使用以下脚本标记来加载 Maps JavaScript API,从而指定 Beta 渠道:

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

选择 Alpha 渠道

使用 Alpha 渠道可以试用新的实验性功能和变更。请使用问题跟踪器报告问题并提供反馈。Alpha 渠道不在任何服务等级协议 (SLA) 或弃用政策的涵盖范围内,并且某些变更可能无法向后兼容早期版本。此渠道仅用于开发目的,不应在生产环境中使用。

此渠道基于 beta 渠道,每周更新一次。

您可以使用以下脚本标记来加载 Maps JavaScript API,从而指定 Alpha 渠道:

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

选择版本号

请仅在定期测试并更新应用的情况下才通过编号指定版本。这是因为随着新版本在每个季度中一一创建,编号版本最终会被删除。您可以使用以下脚本标记来加载 Maps JavaScript API,从而指定版本号:

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

目前,您可以指定 v=3.58v=3.57v=3.56v=3.55

  • 版本 3.58 将接收每周更新,其中包含新功能、bug 修复和 性能提升
  • 版本 3.57 不会接收每周更新。
  • 版本 3.56 不会接收每周更新。
  • 版本 3.55 不会接收每周更新。
  • 我们可能会不时地在任何版本中引入安全性 bug 修复。
  • 在创建新版本时,我们可能会引入向后不兼容的变更。

11 月中旬之后,您将能够指定 v=3.59v=3.58v=3.57v=3.56

  • 版本 3.59 将接收每周更新,其中包含新功能、问题修复和 性能提升
  • 版本 3.58 将不再接收每周更新。
  • 版本 3.57 将不再接收每周更新。
  • 版本 3.56 将不再接收每周更新。
  • 我们可能会不时地在任何版本中引入安全性 bug 修复。
  • 版本 3.55 将无法再使用。任何尝试加载此版本的操作都将被忽略,系统将改而为您采用默认的渠道。

下图显示了在未来一年内每个渠道将会提供的版本。

<ph type="x-smartling-placeholder"></ph> 敬上 v=weekly v=季度 v=3.nn v=3.nn-12024 年 8 月 2024 年 11 月 2025 年 2 月 2025 年 5 月 v3.55 v3.56 v3.56 v3.57 v3.57 v3.57 v3.58 v3.58 v3.58 v3.58 v3.59 v3.59 v3.59 v3.60 v3.60 v3.61

一项更新影响了我的应用

我们更新发布渠道时,您的应用可能会受到影响。这可能是因为您的应用依赖于未载明或已弃用的功能,也可能是我们引入的 bug 或 bug 修复造成的。

您可以通过将应用重新配置为使用旧版本来暂时性地解决此问题。

  1. 在浏览器开发者工具中打开控制台,然后查看 google.maps.version 的值。
  2. 更新用于加载 API 的脚本标记,请求旧版本号
    例如,如果 google.maps.version 为“3.58.2”,请使用 v=3.57
    这种临时解决方案仅在有限的时间内有效。

采用临时解决方案后,您将有时间(通常为 3 到 6 个月)来更新应用,让其不再使用未载明或已弃用的功能,并解决好 bug 或 bug 修复可能带来的问题。

然后,您应该还原为使用原始脚本标记来加载 API。

我们也欢迎您创建支持请求报告问题

季度更新

Maps JavaScript API 团队会每季度发布一个新版本,时间分别在 2 月中旬、5 月中旬、8 月中旬和 11 月中旬。下一次更新时间为 11 月中旬。新的每周渠道将提供版本 3.59, 届时其他渠道将会更新

每周渠道更新

每周渠道目前指向版本 3.58。

11 月中旬,每周渠道提供的版本将从版本 3.58 更新至 3.59 版。 届时,新版本将加入新功能、移除已弃用的功能并/或引入向后不兼容性。在渠道更新后,您可能需要针对这些变更进行测试。

在整个季度内,新版本将每周更新一次,以加入新功能、修复 bug 并提升性能。该版本不会移除已弃用的功能,也不会引入向后不兼容性。

季度渠道更新

季度渠道目前指向版本 3.57。

11 月中旬,季度渠道提供的版本将从版本 3.57 开始更新 3.58 版本。 更新后,此版本将加入新功能、移除已弃用的功能并/或不再向后兼容前三个月的功能。在渠道更新后,您可能需要针对这些变更进行测试。

在整个季度内,此版本不会加入新功能、修复 bug 或提升性能。该版本不会移除已弃用的功能,也不会引入向后不兼容性。

版本更新

11 月中旬,版本号将滚动更新以适应新版本的发布。

版本 3.59

新版本 3.59 将于 11 月中旬发布。 发布后,此版本将加入新功能、移除已弃用的功能 和/或引入向后不兼容性(与版本 3.58 相比)。 在更改版本号时,您应对应用进行测试。

在整个季度内,新版本将每周更新一次,以加入新功能、修复 bug 并提升性能。该版本不会移除已弃用的功能,也不会引入向后不兼容性。

版本 3.58

此版本加入了新功能,移除了已弃用的功能,并/或引入了 向后不兼容性(与版本 3.57 相比)。 在更改版本号时,您应对应用进行测试。

11 月中旬之后,此版本将不再更新以加入新功能、修复 bug 或提升性能。该版本不会移除已弃用的功能,也不会引入向后不兼容性。

版本 3.57

此版本加入了新功能,移除了已弃用的功能,并/或引入了 向后不兼容性(与版本 3.56 相比)。 在更改版本号时,您应对应用进行测试。

此版本将不再更新以加入新功能、修复 bug 或提升性能。该版本不会移除在其之后弃用的功能,也不会引入新的向后不兼容性。

版本 3.56

此版本加入了新功能,移除了已弃用的功能,并/或引入了 向后不兼容性(与版本 3.55 相比)。 在更改版本号时,您应对应用进行测试。

此版本将不再更新以加入新功能、修复 bug 或提升性能。该版本不会移除在其之后弃用的功能,也不会引入新的向后不兼容性。

版本 3.55

11 月中旬之后,此版本将被删除,不能再使用。任何尝试加载此版本的操作都将被忽略,系统将改而为您采用默认的渠道。

版本支持

在任何一个季度,都有四个版本可供选择。这四个版本均受支持。

版本检查

如需进行调试,可使用 google.maps.version 属性来获取应用中 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?key=YOUR_API_KEY&callback=initMap"
    defer></script>
  </body>
</html>

各 API 版本的文档

开发者指南始终会对每周版本进行说明。

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