Google地图是否可用

2025年11月14日 · 阅读需 5 分钟

Quany

软件工程师

要通过API请求检测Google地图是否可用，核心思路是尝试加载Maps JavaScript API，然后根据加载成功与否或具体的错误信息来判断。下面这个流程图梳理了主要的检测逻辑和关键环节：

下面我们具体看一下每个关键环节的操作和注意事项。

💡 检测逻辑与常见错误

检测Google Maps API是否可用的方法，主要是监听其加载成功或失败的事件，并检查常见的错误信息。

基本可用性检测：最直接的方法是检查加载Maps JavaScript API的脚本后，是否存在全局的 google.maps 对象。这表示核心库已加载。

if (typeof google !== 'undefined' && google.maps) {
    console.log('Google Maps API 可用。');
} else {
    console.log('Google Maps API 未成功加载。');
}

监听加载事件：更可靠的做法是使用API加载时指定的回调函数。如果地图成功加载并初始化，这个回调函数会被调用。

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

function initMap() {
    // 此函数被调用，通常意味着API加载成功，可以在此进行地图初始化
    console.log('Google Maps API 已加载并准备就绪。');
    // 你可以进一步创建地图实例来确认完全可用
    // var map = new google.maps.Map(document.getElementById('map'), {...});
}

同时，建议监听窗口的错误事件，以防API脚本加载失败。

window.addEventListener('error', function(e) {
    if (e.target.tagName === 'SCRIPT' && e.target.src.includes('maps.googleapis.com')) {
        console.error('Google Maps API 脚本加载失败。');
    }
}, true);

识别常见错误：如果地图显示为暗色并有“仅用于开发目的”的水印，或控制台有特定错误，通常意味着API密钥、账单或权限问题。下表列出了常见错误及含义：

错误代码	含义与解决方案
`MissingKeyMapError`	请求中缺少必需的API密钥。检查脚本的`src`是否包含正确的`key`参数。
`InvalidKeyMapError`	API密钥无效。请确保密钥正确无误且在Google Cloud控制台中处于启用状态。
`ApiNotActivatedMapError`	项目中未启用Maps JavaScript API。需在Google Cloud控制台中为该API启用。
`BillingNotEnabledMapError`	项目未启用结算功能。使用Google Maps Platform必须关联有效的结算账号。
`RefererNotAllowedMapError`	当前网页的网址未添加到API密钥的“应用程序限制”中授权的网址列表里。

🛠️ 示例代码与注意事项

以下是一个综合性的检测函数示例，它结合了多种检查方式：

/**
 * 检测Google Maps API是否可用
 * @param {string} apiKey - 你的API密钥
 * @param {function} onSuccess - 成功回调函数
 * @param {function} onFailure - 失败回调函数
 */
function checkGoogleMapsAvailability(apiKey, onSuccess, onFailure) {
    // 检查是否已存在google.maps对象（可能已被加载）
    if (window.google && window.google.maps) {
        console.log('Google Maps API 已加载。');
        onSuccess();
        return;
    }

    // 定义全局回调函数，在API加载完成后执行
    window.onGoogleMapsLoaded = onSuccess;

    // 创建脚本标签动态加载API
    const script = document.createElement('script');
    script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&callback=onGoogleMapsLoaded`;
    script.async = true;
    script.defer = true;

    // 处理加载错误
    script.onerror = function() {
        console.error('无法加载 Google Maps API 脚本。');
        onFailure('NETWORK_ERROR');
    };

    // 设置超时处理
    const timeoutId = setTimeout(function() {
        console.error('加载 Google Maps API 超时。');
        onFailure('TIMEOUT');
    }, 10000); // 10秒超时

    // 重写全局回调以确保超时后也能清理
    window.onGoogleMapsLoaded = function() {
        clearTimeout(timeoutId);
        onSuccess();
    };

    // 将脚本添加到文档中开始加载
    document.head.appendChild(script);
}

// 使用示例
checkGoogleMapsAvailability(
    'YOUR_API_KEY_HERE',
    function() {
        console.log('成功：Google Maps 可用。');
        // 这里可以开始初始化地图
    },
    function(errorReason) {
        console.error('失败：Google Maps 不可用。原因：', errorReason);
        // 这里可以根据不同的错误原因向用户显示提示信息
    }
);

重要注意事项：

API密钥配置：确保你的API密钥在Google Cloud控制台中已启用Maps JavaScript API，并且其“应用程序限制”设置（如HTTP引荐来源网址）包含了你的网站域名，否则会导致 RefererNotAllowedMapError 错误。
启用结算功能：使用Google Maps Platform必须为项目启用结算功能，否则即使有有效的API密钥，地图也不会正常显示。

💎 总结

总而言之，通过动态加载脚本并结合成功回调和错误处理，是检测Google Maps是否可用的可靠方法。一旦加载失败，浏览器控制台的错误信息是首要的排查依据。

希望这些信息能帮助你有效地集成检测功能。如果你在实践过程中遇到更具体的问题，比如某个特定的错误代码，欢迎随时提出。

💡 检测逻辑与常见错误​

🛠️ 示例代码与注意事项​

💎 总结​

微信公众号​

💡 检测逻辑与常见错误

🛠️ 示例代码与注意事项

💎 总结

微信公众号