將 Google Maps JavaScript API 金鑰整合至 Webflow 專案

Aiko · March 31, 2025, 4:16am

前置作業：準備您的 Google Cloud Platform 環境

在我們深入探討 Webflow 的設定之前，首要任務是確保您已擁有有效的 Google Maps JavaScript API 金鑰。此金鑰是 Google 用來驗證您請求並追蹤 API 使用量的憑證。

建立或登入 Google Cloud Platform 帳戶：前往 Google Cloud Platform。如果您尚未擁有帳戶，需要先行註冊。請注意，啟用 Google Maps Platform 相關 API 可能需要綁定有效的付款方式，雖然 Google 提供了每月免費的使用額度，但設定付款資訊是必要的步驟。
建立新專案或選取現有專案：在 Google Cloud Console 中，建立一個新的專案專門用於管理您的 API 金鑰，或選擇一個您既有的專案。為專案指定一個清晰的名稱（例如：「My Webflow Maps Project」）有助於後續管理。
啟用 Maps JavaScript API：
- 在左側導覽選單中，找到「API 和服務」>「程式庫」。
- 在搜尋框中輸入「Maps JavaScript API」。
- 點擊搜尋結果中的「Maps JavaScript API」。
- 點擊「啟用」按鈕。如果系統提示您啟用相關的帳單帳戶，請依照指示完成。
產生 API 金鑰：
- 啟用 API 後，前往「API 和服務」>「憑證」。
- 點擊頁面上方的「+ 建立憑證」。
- 選擇「API 金鑰」。系統將會自動為您產生一組金鑰。請妥善保管此金鑰，切勿直接在公開的程式碼儲存庫中分享。
設定 API 金鑰限制（極其重要）：為了防止您的金鑰被未經授權的第三方濫用，導致產生非預期的費用，強烈建議您設定金鑰限制。
- 在「憑證」頁面找到您剛剛建立的 API 金鑰，點擊其名稱或右側的編輯圖示。
- 在「應用程式限制」區塊，選擇「HTTP 參照網址 (網站)」。
- 點擊「新增項目」，輸入您 Webflow 網站的網域。您應該包含所有可能的格式：
  - yourdomain.com/* （您的正式網域）
  - *.webflow.io/* （您的 Webflow 暫存網域，如果您需要在此測試）
  - 若有其他子網域也需要使用地圖，請一併加入。
  - 使用 * 作為萬用字元，表示該網域下的所有路徑皆可使用此金鑰。
- 在「API 限制」區塊，選擇「限制金鑰」。
- 在下拉選單中，僅勾選「Maps JavaScript API」。這樣可以確保此金鑰只能用於地圖顯示，無法用於其他 Google Cloud 服務。
- 點擊「儲存」。

完成以上步驟後，您就擁有了一組安全且設定妥當的 Google Maps JavaScript API 金鑰，可以開始進行 Webflow 的整合工作了。

在 Webflow 中準備嵌入位置

接下來，我們需要在您的 Webflow 專案中指定地圖的顯示位置。

開啟 Webflow 設計器：登入您的 Webflow 帳戶並開啟您想要加入地圖的專案。
選擇目標頁面：導航至您希望顯示 Google Maps 的頁面，例如「聯絡我們」或「分店位置」頁面。
新增 Embed 元件：
- 在左側的「Add」面板 (快捷鍵 A) 中，向下滾動找到「Components」區塊。
- 拖曳「Embed」元件到您頁面佈局中理想的位置。這個 Embed 元件將作為容納我們自訂地圖程式碼的容器。

實作 Google Maps JavaScript 程式碼

這是整合過程的核心步驟。我們將在 Webflow 的 Embed 元件中插入必要的 HTML 和 JavaScript 程式碼。

開啟 Embed Code Editor：點擊您剛剛添加到頁面上的 Embed 元件，會開啟一個程式碼編輯器視窗。
貼上 HTML 與 JavaScript 程式碼：將以下程式碼範本複製並貼到編輯器中。

<style>
  /* 設定地圖容器的基本樣式 */
  #map {
    height: 400px; /* 您可以自訂地圖的高度 */
    width: 100%;   /* 通常設定為 100% 寬度以填滿容器 */
  }
</style>

<!-- 用於顯示地圖的 HTML 容器 -->
<div id="map"></div>

<script>
  // 定義初始化地圖的函數
  function initMap() {
    // 設定地圖中心點的經緯度座標
    const mapCenter = { lat: 25.034, lng: 121.564 }; // 範例：台北 101 座標，請替換成您的目標位置

    // 設定地圖的初始縮放等級 (數字越大越放大)
    const mapZoom = 15; // 數值範圍通常在 0 (全球) 到 21 (極詳細) 之間

    // 建立新的地圖實例並將其附加到 ID 為 'map' 的 div 元素上
    const map = new google.maps.Map(document.getElementById("map"), {
      zoom: mapZoom,
      center: mapCenter,
      // 您可以在此處加入更多地圖選項，例如：
      // mapTypeId: 'satellite', // 設定地圖類型 (roadmap, satellite, hybrid, terrain)
      // disableDefaultUI: true, // 隱藏預設的 Google Maps 控制項
      // styles: [ ... ] // 在此加入自訂地圖樣式 JSON 陣列
    });

    // (可選) 在地圖中心點加上標記 (Marker)
    const marker = new google.maps.Marker({
      position: mapCenter,
      map: map,
      title: "我們的地點" // 標記的標題，滑鼠懸停時顯示
      // icon: 'URL_TO_YOUR_CUSTOM_ICON.png' // 您可以指定自訂圖標的路徑
    });

    // (可選) 為標記加上資訊視窗 (InfoWindow)
    /*
    const infowindow = new google.maps.InfoWindow({
      content: '<h3>公司名稱</h3><p>詳細地址<br>聯繫電話</p>' // 資訊視窗的 HTML 內容
    });
    marker.addListener('click', () => {
      infowindow.open(map, marker);
    });
    */
  }
</script>

<!-- 載入 Google Maps JavaScript API 並觸發 initMap 函數 -->
<!-- **極重要**: 將 YOUR_API_KEY 替換成您真實的 API 金鑰 -->
<script async defer
  src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

替換關鍵參數：
- YOUR_API_KEY：找到程式碼底部載入 API 的 <script> 標籤，將 YOUR_API_KEY 精確地替換成您在 Google Cloud Platform 產生的 API 金鑰。這是最關鍵的一步，若未替換或替換錯誤，地圖將無法載入。
- mapCenter：修改 lat (緯度) 和 lng (經度) 的數值，設定為您希望地圖預設顯示的中心點。您可以使用 Google Maps 找到特定地點的經緯度 (在目標地點點擊右鍵即可看到)。
- mapZoom：調整 mapZoom 的數值來設定地圖的初始縮放程度。數值越大，地圖顯示越詳細。您可以嘗試不同的數值，找到最適合您需求的縮放等級。
- 標記 (Marker) 與資訊視窗 (InfoWindow)：程式碼範例中包含了添加標記和資訊視窗的基礎結構（部分被註解掉）。您可以取消註解並修改 position、title 和 content 等參數，以在地圖上標示您的具體位置並提供額外資訊。
儲存並關閉：完成程式碼修改後，點擊 Embed Code Editor 右上角的「Save & Close」按鈕。

樣式調整與進階自訂

雖然我們在程式碼中加入了基本的 #map CSS 樣式來設定高度和寬度，但您可能需要更進一步的自訂。

Webflow 樣式面板：您可以選取包含 Embed 元件的父層 Div Block，並使用 Webflow 的樣式面板來調整邊距 (Margins)、內距 (Padding) 或添加邊框等視覺效果。
內部 CSS 樣式：直接在 Embed 元件的 <style> 標籤內添加更多 CSS 規則來自訂地圖容器的外觀。
Google Maps JSON 樣式：若想徹底改變地圖本身的視覺風格（例如顏色、道路顯示方式、標籤可見性等），可以使用 Google Maps Platform Styling Wizard (連結) 或手動編寫 JSON 樣式陣列，並將其添加到 new google.maps.Map 的 styles 選項中。這能讓您的地圖完美融入網站的整體設計風格。

測試、發佈與問題排查

在完成所有設定後，進行徹底的測試至關重要。

Webflow 預覽：在 Webflow Designer 中，地圖可能無法完全正常顯示，因為 API 的執行環境與實際網站不同。
發佈至暫存環境：點擊 Webflow 右上角的「Publish」，並選擇發佈到您的 .webflow.io 暫存網域。
實際測試：在瀏覽器中開啟您的暫存網域連結，檢查地圖是否已正確載入、顯示在預期位置、中心點和縮放是否正確，以及標記（如果有的話）是否可見。
開發者工具檢查：如果在載入地圖時遇到問題（例如地圖區塊顯示錯誤訊息或空白），請打開瀏覽器的開發者工具（通常按 F12），檢查「Console」(主控台) 分頁。常見的錯誤訊息包括：
- ApiNotActivatedMapError：表示 Maps JavaScript API 未在 Google Cloud Platform 中啟用。
- InvalidKeyMapError 或 MissingKeyMapError：表示您的 API 金鑰無效、錯誤或遺漏。請仔細檢查您在程式碼中貼上的金鑰是否正確。
- RefererNotAllowedMapError：表示您目前的網站網域未在 API 金鑰的 HTTP 參照網址限制清單中。請回到 Google Cloud Console 檢查並更新您的網域限制設定。
- BillingNotEnabledMapError：表示您尚未為專案啟用帳單功能。
- JavaScript 語法錯誤：檢查您複製貼上的程式碼是否有任何語法錯誤或遺漏。
正式發佈：確認在暫存環境中一切正常後，即可將網站發佈到您的正式網域。再次檢查正式網域上的地圖功能。

安全性最佳實踐回顧

再次強調，限制您的 API 金鑰是保護您帳戶安全和避免非預期費用的關鍵步驟。始終設定 HTTP 參照網址限制，並透過 API 限制僅允許金鑰用於 Maps JavaScript API。切勿將未經限制的金鑰直接嵌入到公開的程式碼中。

透過遵循本指南的詳細步驟，我們相信您能夠成功地將功能豐富且互動性強的 Google Maps 無縫整合至您的 Webflow 網站。這不僅能提升訪客的使用體驗，更有助於清晰傳達重要的地理位置資訊，進而強化您的線上業務形象。

提升您的 Webflow 網站體驗

將 Google Maps 整合至您的 Webflow 網站只是眾多提升數位體驗的策略之一。若您希望進一步優化網站效能、SEO 排名、使用者介面設計或探索更多 Webflow 的進階功能，Tenten.co 的專家團隊隨時準備為您提供協助。我們專注於打造高效能、高轉換率的 Webflow 網站，並提供全方位的數位解決方案。立即預約免費諮詢會議，讓我們一同探討如何將您的網站提升至新的高度。

立即預約免費諮詢會議