Svelte应用集成Google Maps仅显示灰色区域问题排查求助

我正尝试在Svelte应用中集成Google Maps，编写了如下组件JS代码：

import {Loader} from '@googlemaps/js-api-loader';

let mapElement;

onMount(async () => {
    let loader = new Loader({
        apiKey: getConfig().GOOGLE_MAPS_KEY,
        version: 'weekly'
    });

    await loader.load();

    let {Map} = await google.maps.importLibrary('maps');

    let map = new Map(mapElement, {
        center: {lat: -34.397, lng: 150.644},
        zoom: 8
    });
})

页面能加载出灰色区域，但无法显示地图。我已检查以下内容：

• API密钥正常
• HTML元素已正确绑定到mapElement
• HTML元素设置了固定高度
  Vite及控制台均无报错信息，请问可能的原因是什么？该如何调试？

可能原因及调试方案 #

1. 地图库加载逻辑问题 #

虽然执行了loader.load()，但importLibrary的异步加载可能存在隐性异常。可以尝试跳过importLibrary，直接从全局google对象调用Map构造函数：

// 替换原importLibrary相关代码
const map = new google.maps.Map(mapElement, {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8
});

调试：在await loader.load()后打印console.log(google.maps)，确认Map构造函数是否存在。

2. 元素尺寸的隐性限制 #

仅设置高度可能不够，地图容器需要明确的宽高和正确的定位上下文：

• 给mapElement同时设置固定宽高（比如width: 100%; height: 400px;）
• 确保容器父元素设置position: relative（Google Maps需要相对定位来渲染子元素）
  调试：打开浏览器DevTools，查看mapElement的实际计算尺寸，确认宽高均不为0，且没有被其他样式遮挡。

3. API服务未启用或密钥限制不匹配 #

即使API密钥有效，可能未启用Maps JavaScript API服务，或者密钥的访问限制与当前环境不匹配：

• 登录Google Cloud控制台，确认对应项目已启用Maps JavaScript API
• 检查密钥的HTTP/HTTPS限制，确保本地开发域名（如http://localhost:5173）在允许列表内
  调试：查看浏览器网络面板中Google Maps相关请求的响应，检查是否有隐藏的权限错误提示。

4. DOM元素就绪状态问题 #

onMount执行时，mapElement可能因条件渲染（如{#if}语句）未完全挂载到DOM：

• 确保绑定mapElement的元素没有被条件语句包裹，或在条件满足后再初始化地图
  调试：在onMount开头打印console.log(mapElement)，确认元素不为null或undefined。

5. API版本兼容性问题 #

使用weekly版本的API可能存在不稳定的兼容性问题，尝试切换到稳定版本：

let loader = new Loader({
    apiKey: getConfig().GOOGLE_MAPS_KEY,
    version: '3.54' // 替换为稳定版本号
});

内容的提问来源于stack exchange，提问作者scriptic