錯誤訊息

本頁面說明 Maps JavaScript API 可能傳回的錯誤訊息。Maps JavaScript API 會將錯誤和警告訊息寫入 JavaScript 控制台。此外,也可能發生某些錯誤狀況,導致出現加上浮水印的深色地圖。

API 金鑰和帳單錯誤

疑難排解

在某些情況下,地圖顏色可能會變得比較深 (有點像「負片」效果的街景服務圖片),而且會有「僅供開發使用」浮水印。這通常代表有 API 金鑰或帳單方面的問題。如要使用 Google 地圖平台的各項產品,帳戶必須啟用計費功能,且所有要求都必須包含有效的 API 金鑰。請參閱「在瀏覽器中檢查錯誤」一節,瞭解如何找出錯誤訊息。

下列流程有助於您排解問題。

開發人員和網站擁有者適用的 Maps JavaScript API 錯誤代碼

下表列出 Maps JavaScript API 可能傳回的錯誤代碼,並說明原因和問題解決方法。請參閱「在瀏覽器中檢查錯誤」一節,瞭解如何找出錯誤訊息。

地圖載入錯誤

如果您在載入 Maps JavaScript API 時發生錯誤,請參閱下表來查看錯誤代碼的說明。

錯誤代碼 訊息 說明
NotLoadingAPIFromGoogleMapsError Maps JavaScript API 必須直接透過 Google 的伺服器下載。

網頁中未正確納入用於載入 Maps JavaScript API 的指令碼元素。如要讓 API 正常運作,必須直接從 https://maps.googleapis.com 下載。

請參閱「載入 Maps JavaScript API」一文。

TOSViolationMapError 這個網站疑似違反《Google Maps API 服務條款》。這個網站的 Google Maps API 已停用。

您的應用程式在數次收到電子郵件通知後,仍然違反《Google 地圖平台服務條款》,因此遭到封鎖。如要提出封鎖申訴並讓我們審查您的導入方式,請填寫這份表單。您會在幾個工作天內收到電子郵件回覆。

如果您有 Google 地圖平台付費方案授權,請使用 Google 地圖平台付費方案憑證來解決這個錯誤。請參閱付費方案驗證指南。

UnauthorizedURLForClientIdMapError 這個網站並未獲得授權,無法使用所提供的 Google 地圖用戶端 ID。

載入指令碼時附上的付費方案或 Maps API for Work 用戶端 ID 無效/已過期,或是用於載入 Maps JavaScript API 的目前位址尚未加進授權網址清單。

請參閱「註冊授權的網址」一文。

Maps JavaScript API 錯誤代碼

如果 Chrome JavaScript 控制台Firefox 網頁控制台或瀏覽器上的任何其他同類工具發生錯誤,請參閱下表來查看錯誤代碼的說明。

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 控制台中刪除。請檢查要使用 API 金鑰 (包含在 JavaScript 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 授權,就必須搭配 API 金鑰使用 key 參數,而不是 client 參數。

請參閱付費方案驗證指南。

InvalidKeyMapError 錯誤

找不到載入 API 的指令碼元素中包含的 API 金鑰。請務必使用正確的 API 金鑰。您可以在 Cloud 控制台中產生新的 API 金鑰。

如要取得 API 金鑰,請點選下方按鈕。
開始使用

MalformedCredentialsMapError 錯誤

您的應用程式使用不支援的 URI 配置。請確認應用程式是否使用 RFC 3986 中定義的有效 URI 格式。

MissingKeyMapError 錯誤

載入 API 的指令碼元素缺少必要的驗證參數。

如果您使用標準 Maps JavaScript API,就必須搭配有效的 API 金鑰使用 key 參數。詳情請參閱「開始使用 Google 地圖平台」一文。

如果您是付費方案客戶,就必須搭配用戶端 ID 使用 client 參數,或是搭配有效的 API 金鑰使用 key 參數。詳情請參閱 API 金鑰和用戶端 ID 指南。

如果您「不是」網站擁有者,就無法修正這個錯誤。不過,如果情況允許,建議您通知網站擁有者。

ProjectDeniedMapError 錯誤

無法完成您的要求。如要進一步瞭解這個錯誤,請前往 Cloud 控制台。

請查看 Cloud 控制台

RefererDeniedMapError 錯誤

您的應用程式在數次收到電子郵件通知後,仍然違反《Google 地圖平台服務條款》,因此遭到封鎖。如要提出封鎖申訴並讓我們審查您的導入方式,請填寫這份表單。您會在幾個工作天內收到電子郵件回覆。

RefererNotAllowedMapError 錯誤

用以載入 Maps JavaScript API 的目前網址尚未加進允許的參照網址清單。請在 Cloud 控制台中查看 API 金鑰的參照網址設定。

請查看 Maps JavaScript API 並取得 API 金鑰

OverQuotaMapError 錯誤

要求數量已超出 Maps JavaScript API 的用量限制。下次每日配額重設時,應用程式的要求就能恢復運作。

如果您「不是」網站擁有者,就無法修正這個錯誤。不過,如果情況允許,建議您通知網站擁有者。

詳情請參閱用量限制指南。此外,該頁面也會說明如何提高用量限制。

ApiProjectMapError 錯誤

無法解析提供的 API 金鑰或與金鑰相關聯的 API 專案。這可能是暫時性錯誤。如果這則錯誤訊息持續存在,您可能需要取得新的 API 金鑰或建立新的 API 專案。

詳情請參閱「開始使用 Google 地圖平台」一文。

ClientIdLooksLikeCryptoKey 警告

您可能已在 client 參數中提供加密編譯金鑰。如果您有付費方案或 Maps API for Work 授權,請將用戶端 ID 指定為 client 參數。您在 Maps JavaScript API 中不需要使用加密編譯金鑰。

請參閱付費方案與 Maps API for Work 客戶適用的用戶端 ID 指南。

ClientIdLooksLikeKey 警告

您可能已在 client 參數中提供 API 金鑰。如果您有付費方案或 Maps API for Work 授權,請將用戶端 ID 指定為 client 參數。如果您有 Google 地圖平台付費方案,就可以使用 client 參數或 key 參數。如果您沒有任何授權,就必須使用 key 參數,而不是 client 參數。

請參閱付費方案驗證指南。

InvalidChannel 警告

您可能提供無效的 channel 參數。管道必須是 ASCII 英數字元字串,其中可能包含半形句號 (.)、底線 (_) 和連字號 (-)。請務必指定有效的 channel 參數。

請參閱「報表 | Google 地圖平台付費方案」。

InvalidClientId 警告

client 參數似乎未包含正確的用戶端 ID。用戶端 ID 的開頭應為「gme-」。

請參閱付費方案驗證指南。

InvalidKey 警告

載入 API 的指令碼元素中包含的 API 金鑰似乎不正確。請務必使用正確的 API 金鑰。您可以在 Cloud 控制台中產生新的 API 金鑰。

如要取得 API 金鑰,請點選下方按鈕。
開始使用

InvalidVersion 警告

您可能在指令碼元素中提供不正確的版本號碼。請務必使用正確的版本號碼。

請參閱「版本管理 | Google Maps JavaScript API」。

KeyLooksLikeClientId 警告 您可能提供用戶端 ID 做為 key 參數。如果您有付費方案或 Maps API for Work 授權,請將用戶端 ID 指定為 client 參數,而不是 key 參數。如果您有 Google 地圖平台付費方案,就可以使用 client 參數或 key 參數。如果您沒有任何授權,就必須使用 key 參數,而不是 client 參數。

請參閱付費方案驗證指南。

KeyLooksLikeCryptoKey 警告

您可能提供加密編譯金鑰或簽署密鑰做為 key 參數。如果您有付費方案或 Maps API for Work 授權,請將用戶端 ID 指定為 client 參數,然後從指令碼元素中移除 key 參數。Maps JavaScript API 不需要使用加密編譯金鑰。如果您有 Google 地圖平台付費方案,就可以使用 client 參數或 key 參數。如果您沒有任何授權,可以在 Cloud 控制台中取得 API 金鑰。

請參閱「在載入 API 時指定用戶端 ID」的指南。

KeyLooksLikeProjectNumber 警告

您可能提供專案編號做為 key 參數。請務必使用正確的 API 金鑰。您可以在 Cloud 控制台中產生新的 API 金鑰。

瞭解如何取得 API 金鑰。

NoApiKeys 警告

載入 API 的指令碼元素沒有 API 金鑰。請務必將以 key 參數的形式加入有效的 API 金鑰。您可以在 Cloud 控制台中產生新的 API 金鑰。

如要取得 API 金鑰,請先點選下方按鈕。
開始使用

如果您是從已淘汰的第 2 版路徑載入 Maps JavaScript API,那麼即使指定 key 參數,也還是會收到 NoApiKeys 警告。請參閱從第 2 版升級至第 3 版的指南,並將應用程式遷移至 Maps JavaScript API 第 3 版。

RetiredVersion 警告

您可能在指令碼元素中提供已淘汰的版本。請更新應用程式,改為使用其中一個可用的版本。

請參閱「版本管理 | Google Maps JavaScript API」。

SensorNotRequired 警告

Maps JavaScript API 不再需要使用 sensor 參數。這不會阻礙 Maps JavaScript API 正常運作,但建議您從指令碼元素中移除 sensor 參數。

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. 如要開啟 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 網站。如要瞭解發布問題的技巧,請參閱「支援」頁面。