從零開始導入 Google Maps API

發表於 分類於

從零開始導入 Google Maps API

簡介

什麼是 Google Maps API？

Google Maps API 是 Google 提供的網頁地圖服務，讓開發者能在自己的網站或 Web App 中嵌入互動式地圖。除了基本的地圖顯示外，還支援標記（Marker）、路線規劃、街景、自訂樣式等豐富功能,是製作 LBS（Location-Based Service）應用、店家定位、地圖小遊戲等常見專案時的首選方案。

本文以最精簡的範例,示範如何取得 API Key、建立第一張可運作的地圖,並透過 importLibrary() 動態載入新版地圖函式庫。

適合使用情境

  • 需要在網站中嵌入互動式地圖的應用
  • 開發以地理位置為基礎的小型專案或 Game Jam 作品
  • 想體驗 Google Maps 新版動態載入 API（importLibrary）的開發者
  • 需要使用 Cloud-based Map Styling（雲端地圖樣式）的專案

系統要求

項目 需求
瀏覽器 任何支援 ES2017（async/await）的現代瀏覽器
Google 帳號 已啟用結帳功能的 Google Cloud 帳號
開發環境 任意靜態網頁伺服器(VS Code Live Server、Vite、http-server 等)
網路連線 可連線至 maps.googleapis.com

重要提醒：Google Maps Platform 雖然提供每月免費額度,但仍須在 Google Cloud Console 中啟用結帳帳戶才能取得可用的 API Key。請務必於 Cloud Console 中設定配額（Quota）或用量上限警示,避免因額度爆量而產生非預期費用。

步驟 1：建立 Google Cloud 專案

要使用 Google Maps API,必須先在 Google Cloud Platform 上建立一個專案來承載相關設定。

  1. 前往 Google Cloud Console 並登入 Google 帳號。
  2. 點擊頂部的專案下拉選單,選擇 New Project（新增專案）。
  3. 輸入專案名稱(例如 my-map-demo),選擇所屬組織後按下 Create。
  4. 等待專案建立完成,並從上方的下拉選單切換到該專案。

步驟 2：啟用 Maps JavaScript API

新版的 Google Maps Platform 採取「按服務啟用」的模式,需要先開啟對應的 API 才能使用。

  1. 在 Cloud Console 左側導覽列中,選擇 APIs & Services > Library。
  2. 在搜尋框輸入 Maps JavaScript API,點擊搜尋結果。
  3. 進入服務頁面後,按下 Enable 按鈕啟用此 API。

小提醒:如果未來要使用 Places、Directions、Geocoding 等其他服務,也需要在 Library 中分別啟用,各自會獨立計算用量。

步驟 3：建立並限制 API Key

API Key 是呼叫 Google Maps 服務的憑證,強烈建議在建立後立刻加上使用限制,避免被盜用造成損失。

  1. 進入 APIs & Services > Credentials。
  2. 點擊 Create Credentials > API key,系統會產生一組金鑰。
  3. 複製 Key 並按下 Edit API key(或點擊金鑰名稱)進入詳細設定。
  4. 在 Application restrictions 中選擇 HTTP referrers (web sites),並加入允許的網域,例如:
    • 本地開發:http://localhost:5500/*
    • 正式環境:https://your-domain.com/*
  5. 在 API restrictions 中選擇 Restrict key,勾選剛才啟用的 Maps JavaScript API。
  6. 按下 Save 儲存設定。

安全提醒:絕對不要將 API Key 直接 commit 到公開的 Git Repository。建議透過環境變數、後端代理或建置流程注入。

步驟 4：建立第一張地圖

設定完成後,只需要一個 HTML 檔案就能渲染出第一張地圖。以下是一份完整可運作的最小範例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
<!DOCTYPE html>
<html>
  <head>
    <title>Google Map Test</title>
    <style>
      /* 讓地圖填滿整個畫面 */
      html, body {
        height: 100%;
        margin: 0;
        padding: 0;
      }
      /* 這是用來裝載地圖的容器 */
      #map {
        height: 100%;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>

    <script>
      // 初始化地圖的函數
      let map;
      async function initMap() {
        // 載入核心地圖函式庫
        const { Map } = await google.maps.importLibrary("maps");

        // 建立地圖實體,並設定中心點與縮放級別
        map = new Map(document.getElementById("map"), {
          center: { lat: 25.033968, lng: 121.564468 }, // 預設中心點設定在台北101
          zoom: 14, // 數值越大,視角越近
          mapId: "DEMO_MAP_ID", // 未來如果要套用 Cloud 樣式,會需要這個設定
          disableDefaultUI: true // 隱藏預設的縮放與街景控制項
        });
      }
    </script>

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

將上述程式碼中的 YOUR_API_KEY 替換成步驟 3 取得的金鑰,接著用任何靜態伺服器開啟此頁面即可看到地圖。

程式碼解析

載入腳本的兩個關鍵參數

1
2
3
<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
參數 說明
async 讓瀏覽器以非同步方式載入腳本,不會阻塞頁面渲染
key 上一步取得的 API Key,Google 透過此值辨識用量歸屬
callback 腳本載入完成後要呼叫的全域函式名稱(此處為 initMap)

由於使用了 callback,initMap 必須是全域函式才能被 Google Maps 腳本呼叫到。

動態載入函式庫:importLibrary()

1
const { Map } = await google.maps.importLibrary("maps");

過去要使用 Marker、places 或 drawing 等功能,需要在 <script> 的 URL 中以 &libraries=places,drawing 的方式預先載入,造成初始載入體積過大。

新版 API 改用 importLibrary() 動態載入所需模組,常見的函式庫名稱包括:

  • "maps":核心地圖類別(Map、InfoWindow)
  • "marker":AdvancedMarkerElement 等新版標記
  • "places":Places API(自動完成、附近搜尋)
  • "geocoding":地址與座標互轉
  • "routes":路線規劃

採用此方式後,只會載入實際使用到的功能,有助於提升頁面效能。

Map 建構子的常用選項

1
2
3
4
5
6
map = new Map(document.getElementById("map"), {
  center: { lat: 25.033968, lng: 121.564468 },
  zoom: 14,
  mapId: "DEMO_MAP_ID",
  disableDefaultUI: true
});
選項 用途
center 地圖初始中心點,以 { lat, lng } 物件指定
zoom 縮放級別,數值越大越接近地面(常用 0~22)
mapId 對應 Cloud Console 中設定的地圖樣式 ID
disableDefaultUI 隱藏所有預設控制項,適合需要自訂 UI 的情境

關於 mapId:若要使用 AdvancedMarkerElement 或 Cloud-based Map Styling,必須指定一組有效的 mapId。範例中的 "DEMO_MAP_ID" 為 Google 提供的測試用 ID,正式專案應於 Cloud Console 中自行建立。

常見問題排除

地圖區域顯示灰底並出現警告

最常見的原因有三種:

  1. API Key 未啟用對應服務:確認 Maps JavaScript API 已在 Library 中 Enable。
  2. Referrer 限制不符:檢查目前網址是否符合 Credentials 中設定的 HTTP referrers。
  3. 未啟用結帳帳戶:即使在免費額度內,Google Cloud 仍要求綁定有效的付款方式。

開啟瀏覽器 DevTools 的 Console 面板,Google Maps 通常會輸出明確的錯誤訊息(例如 RefererNotAllowedMapError、ApiNotActivatedMapError),依訊息修正即可。

地圖容器沒有高度

如果 #map 的父層元素未設定高度,地圖將會以 0px 呈現而看不到任何內容。請確認 html、body 與 #map 都明確設定了 height,如同範例中的 CSS 寫法。

initMap is not a function 錯誤

callback 指定的函式必須掛在全域 window 物件下。若使用模組打包工具(如 Vite、Webpack),預設不會將函式暴露為全域,需要手動執行 window.initMap = initMap; 才能被 Google Maps 腳本呼叫。

結語

到這裡,已經完成了 Google Maps JavaScript API 的最小可運作範例。後續可以延伸的方向相當多元,例如加入 AdvancedMarkerElement 顯示自訂圖示、整合 Places API 製作搜尋框、或是透過 Cloud-based Map Styling 打造專屬風格的地圖外觀。

最近我正嘗試用 AI 來製作一款基於 Google Maps API 的遊戲,也因為這樣,才促成了這篇文章的整理與撰寫。對於 Game Dev 等短期專案而言,Google Maps 的優勢在於資料完整、文件豐富、上手快速;只要妥善設定 API Key 限制與用量警示,就能在免費額度內完成大多數原型驗證。

如果後續實作與踩坑經驗累積得夠完整,也有機會再把相關內容整理成系列文章,包含地圖互動設計、位置資料應用,以及 AI 輔助開發流程等主題。有興趣的話,可以期待一下後面的延伸分享。