版本管理

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Maps JavaScript API 團隊會定期更新 API,包括新增功能、修正錯誤和提升效能。本頁面說明可在您應用程式中使用的 API 版本。

發布版本和版本號碼

在應用程式中,您可以指定發布版本或版本號碼:

  • 每週版本是以 v=weekly 指定。
    這個版本包含最新內容,每週更新一次。
  • 每季版本是以 v=quarterly 指定。
    這個版本帶來的影響最容易預測,每季更新一次。
  • Beta 版是以 v=beta 指定。
    這個版本以 weekly 版本為基礎,每週更新一次,內容包含額外變更,以便進行早期測試及收集意見回饋。
  • 版本號碼是以 v=n.nn 指定。
    您可以選用 v=3.51v=3.50v=3.49v=3.48
    版本號碼每季更新一次 (請參閱「每季更新」一節)。

如未明確指定版本,預設會收到每週版本。如果您是從付費方案轉移過來,且未明確指定版本,預設會收到每季版本。要是指定無效版本,您會收到預設版本。

選擇每週版本

針對大多數應用程式,我們建議指定每週版本。這是目前最新版本,內容包括最新錯誤修正和效能提升。如要指定每週版本,您可以使用下列指令碼標記載入 Maps JavaScript API:

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

目前,每週頻道為 3.51 版。這個版本每週更新一次,內容包含最新功能、錯誤修正和效能提升。

每週 2 月中旬,每週頻道將更新至 3.52 版。屆時,新版本可能會移除已淘汰的功能,並/或推出無法回溯相容的內容。

選擇每季版本

對某些應用程式來說,減少更新次數但擴大更新規模的做法較為有利,因為這樣做帶來的影響更容易預測。我們建議這類應用程式使用每季版本。如果您希望能在預定時間修正錯誤及提升效能,不妨使用這種做法 (請參閱「每季更新」一節)。如要指定每季版本,您可以使用下列指令碼標記載入 Maps JavaScript API:

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

目前每季版本為 3.50 版。 在本季中,這個版本不會推出任何最新功能、錯誤修正或效能提升。我們可能會不時在這個版本中推出安全性錯誤修正。

季度頻道在 2 月中旬會更新為 3.51 版。 屆時,新版本會納入最新功能、移除已淘汰的功能,並/或推出無法與過去三個月的版本回溯相容的內容。

選擇 Beta 版

使用 Beta 版即可體驗新的 Beta 版功能和變動內容。Beta 版功能完整,但可能有一些尚待解決的問題 (請使用 Issue Tracker 回報問題並提供意見回饋)。Beta 版不在任何服務水準協議或廢止政策的涵蓋範圍內,且部分變動內容可能無法與舊版回溯相容。

這個版本以 weekly 版本為基礎,每週更新一次,

如要指定 Beta 版,您可以使用下列指令碼標記載入 Maps JavaScript API:

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

選擇版本號碼

只有在您會定期測試及更新應用程式時,才以數字來指明版本。這是因為每季都會推出新版本,有編號的版本最終會刪除。您可以使用下列指令碼標記,載入 Maps JavaScript API 來指定版本號碼:

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

目前您可以指定 v=3.51v=3.50v=3.49v=3.48

  • 3.51 版每週都會收到有關新功能、錯誤修正和效能提升的更新。
  • 3.50 版未收到每週更新。
  • 3.49 版不會每週更新。
  • 3.48 版不會每週更新。
  • 我們可能會不時在任何版本中推出安全性錯誤修正。
  • 我們可能會在建立新版本時,推出無法回溯相容的變動內容。

2 月中旬之後,您就能指定 v=3.52v=3.51v=3.50v=3.49

  • 3.52 版每週都會收到新功能,以及修正錯誤和改善效能。
  • 3.51 版將不再接收每週更新。
  • 3.50 版不再會每週更新。
  • 3.49 版不再會每週更新。
  • 我們可能會不時在任何版本中推出安全性錯誤修正。
  • 3.48 版已無法使用。系統會略過嘗試載入這個版本的任何作業,改為提供預設版本。

下圖顯示未來一年會推出的版本。

17

影響應用程式的更新內容

如果發布版本有所更新,可能會影響您的應用程式。這可能是因為應用程式使用未支援或已淘汰的功能,也可能是我們導入的錯誤/錯誤修正所導致。

您可以將應用程式設為改用舊版,做為暫時解決方法。

  1. 在瀏覽器開發人員工具中開啟控制台,並查看 google.maps.version 的值。
  2. 更新會載入 API 的指令碼標記,然後要求舊版號碼
    例如,如果 google.maps.version 是「3.51.2」,請在指令碼標記中使用 v=3.50
    這個暫時解決方法具有時效性。

這個暫時解決方法設定完畢後,您就有時間 (通常為 3 至 6 個月) 更新應用程式,改為停用未支援或已淘汰的功能,並將錯誤或錯誤修正納入考量。

然後,您必須還原為原始指令碼標記,才能載入 API。

如有需要,您也可以建立客服案件回報問題

每季更新

Maps JavaScript API 團隊每季推出一個新版本,時間是在 2 月中旬、5 月中旬、8 月中旬和 11 月中旬。下一次更新將於 2 月中旬生效。 新的每週管道會提供 3.52 版,屆時其他管道將會更新。

每週版本更新

每週頻道指向 3.51 版。

2 月中旬,每週頻道將從 3.51 版更新至 3.52 版。 屆時,新版本將納入最新功能、移除已淘汰的功能,並/或推出無法回溯相容的內容。建議您在版本更新時,針對這些變動內容進行測試。

在整季中,新版本每週更新一次,內容包含最新功能、錯誤修正和效能提升。這個版本不會移除已淘汰的功能,也不會推出無法回溯相容的內容。

每季版本更新

每季頻道指向 3.50 版。

季度管道在 2 月中會從 3.50 版更新至 3.51 版。 更新後,這個版本將納入最新功能、移除已淘汰的功能,並/或推出無法與過去三個月的版本回溯相容的內容。建議您在版本更新時,針對這些變動內容進行測試。

在整季中,這個版本不會推出任何最新功能、錯誤修正和效能提升。這個版本不會移除已淘汰的功能,也不會推出無法回溯相容的內容。

版本更新

為因應新版本的推出情況,系統會在 2 月中旬推出版本號碼。

3.52 版本

新版本 3.52 將於 2 月中旬推出。 這個版本在發布後將包括 3.51 的新功能,包括移除新功能、移除已淘汰的功能,和/或介紹回溯不相容的項目。建議您在版本號碼變更後測試應用程式。

在本季中,新版本每週更新一次,內容包含最新功能、錯誤修正和效能提升。這個版本不會移除已淘汰的功能,也不會推出無法回溯相容的內容。

3.51 版

相較於 3.50 版,這個版本提供新功能、移除已淘汰的功能和/或推出回溯不相容的問題。建議您在版本號碼變更後測試應用程式。

自 2 月中旬起,這個版本就不會再提供新功能、修正錯誤或提升效能。這個版本不會移除已淘汰的功能,也不會推出無法回溯相容的內容。

3.50 版

這個版本加入最新功能、移除已淘汰的功能,並/或推出無法與 3.49 版回溯相容的內容。建議您在版本號碼變更後測試應用程式。

這個版本不會再推出包含最新功能、錯誤修正或效能提升的更新內容。這個版本不會移除之後淘汰的功能,也不會推出無法回溯相容的新功能。

3.49 版

這個版本加入最新功能、移除已淘汰的功能,並/或推出無法與 3.48 版回溯相容的內容。建議您在版本號碼變更後測試應用程式。

這個版本不會再推出包含最新功能、錯誤修正或效能提升的更新內容。這個版本不會移除之後淘汰的功能,也不會推出無法回溯相容的新功能。

3.48 版

2 月中旬之後,這個版本就會遭到刪除,無法再使用。 系統會略過嘗試載入這個版本的任何作業,改為提供預設版本。

版本支援

每季都有四個版本可供選擇,且全都受到支援。

版本檢查

如要進行偵錯,請在應用程式中使用 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 版本的說明文件

開發人員指南會隨時提供每週版本的說明。

此外,每個版本都有單獨維護的參考資料: