MapLibre GL JS第12课：检查WebGL支持

📌 学习目标

掌握检查WebGL支持的实现方法
理解相关API的使用
能够独立完成类似功能开发

🎯 核心概念

检查浏览器是否支持WebGL。

💻 完整代码

代码示例

js 复制代码

function isWebglSupported() {
    if (window.WebGLRenderingContext) {
        const canvas = document.createElement('canvas');
        try {
            // 注意，可以将 { failIfMajorPerformanceCaveat: true } 作为第二个参数
            // 传递给 canvas.getContext()，如果硬件渲染不可用，检查将失败。有关更多
            // 详细信息，请参见 https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext。
            const context = canvas.getContext('webgl2') || canvas.getContext('webgl');
            if (context && typeof context.getParameter == 'function') {
                return true;
            }
        } catch (e) {
            // WebGL 已支持但被禁用
        }
        return false;
    }
    // WebGL 不支持
    return false;
}
if (!isWebglSupported()) {
    alert('Your browser does not support WebGL');
} else {
    const map = new maplibregl.Map({
        container: 'map',
        style: 'https://demotiles.maplibre.org/style.json',
        center: [-74.5, 40],
        zoom: 2
    });
}

代码示例

html 复制代码

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Check if WebGL is supported</title>
    <meta property="og:description" content="检查浏览器是否支持 WebGL。" />
    <meta property="og:created" content="2025-06-25" />
    <meta charset='utf-8'>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel='stylesheet' href='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.css' />
    <script src='https://unpkg.com/maplibre-gl@5.24.0/dist/maplibre-gl.js'></script>
    <style>
        body { margin: 0; padding: 0; }
        html, body, #map { height: 100%; }
    </style>
</head>
<body>
<div id="map"></div>

<script>
    function isWebglSupported() {
        if (window.WebGLRenderingContext) {
            const canvas = document.createElement('canvas');
            try {
                // 注意：{ failIfMajorPerformanceCaveat: true } 可以作为第二个参数传递给
                // canvas.getContext()，如果硬件渲染不可用，检查将失败。详情请参见
                // https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLCanvasElement/getContext
                const context = canvas.getContext('webgl2') || canvas.getContext('webgl');
                if (context && typeof context.getParameter == 'function') {
                    return true;
                }
            } catch (e) {
                // WebGL 已支持但被禁用
            }
            return false;
        }
        // WebGL 不支持
        return false;
    }
    if (!isWebglSupported()) {
        alert('Your browser does not support WebGL');
    } else {
        const map = new maplibregl.Map({
            container: 'map',
            style: 'https://demotiles.maplibre.org/style.json',
            center: [-74.5, 40],
            zoom: 2
        });
    }
</script>
</body>
</html>

🔍 代码解析

1. WebGL支持检测函数

isWebglSupported() 函数检测浏览器是否支持WebGL：

首先检查 window.WebGLRenderingContext 是否存在
创建一个canvas元素尝试获取WebGL上下文
优先尝试获取 webgl2 上下文，如果失败则尝试 webgl
检查上下文是否有效并包含 getParameter 方法

2. 检测选项

可以通过传入 { failIfMajorPerformanceCaveat: true } 参数来检测硬件加速是否可用。如果硬件渲染不可用，检查会失败。这对于需要高性能WebGL的应用很重要。

3. 条件初始化地图

只有在WebGL支持检测通过后，才创建MapLibre地图实例。如果不支持，可以显示友好的错误提示或提供降级方案。

4. 错误处理

使用try-catch捕获WebGL上下文创建过程中的异常，确保即使WebGL被浏览器禁用也能优雅处理。

⚙️ 参数说明

canvas.getContext 参数

参数	类型	说明
contextType	string	上下文类型：'webgl' 或 'webgl2'
options.failIfMajorPerformanceCaveat	boolean	硬件加速不可用时是否失败

isWebglSupported 函数返回值

返回值	类型	说明
true	boolean	浏览器支持WebGL
false	boolean	浏览器不支持WebGL或WebGL被禁用

🎨 效果说明

运行代码后：

首先检测浏览器是否支持WebGL
如果支持WebGL，地图正常初始化并显示（默认显示美国东部区域）
如果不支持，弹出警告框提示"Your browser does not support WebGL"

这种优雅降级处理确保了在不支持WebGL的环境中不会出现空白页面或崩溃。

💡 常见问题

Q1: 浏览器支持WebGL但地图仍然不显示怎么办？

A: 可能是WebGL被浏览器扩展、安全设置或企业策略禁用。检查浏览器控制台是否有WebGL相关错误，尝试在隐私模式下打开页面测试。

Q2: 如何检测WebGL2而不只是WebGL1？

A: 修改代码只检测webgl2上下文：

javascript 复制代码

function isWebgl2Supported() {
    const canvas = document.createElement('canvas');
    return !!(canvas.getContext('webgl2'));
}

Q3: 在不支持WebGL的环境中如何提供降级方案？

A: 可以：

显示静态地图图片（如通过Google Static Maps API）
使用基于CSS的简单地图渲染
提示用户升级浏览器

📝 练习任务

基础练习：修改警告提示为更友好的自定义模态框
进阶挑战：添加WebGL性能检测，提示用户设备性能等级
拓展思考：实现检测失败后的自动降级，显示静态地图图片

🌟 最佳实践

提前检测: 在加载地图库之前进行WebGL检测，节省不必要的资源加载
友好提示: 为不支持WebGL的用户提供清晰的提示和替代方案
性能考虑 : 使用 failIfMajorPerformanceCaveat: true 确保良好的用户体验
错误处理: 使用try-catch捕获可能的异常，确保检测过程不会中断页面加载

🔗 延伸阅读

Map API文档
Layer API文档
Expression文档
MapLibre GL JS 官方文档
$下一课预告$ ：将继续学习地图图层的基础知识

本文是MapLibre GL JS实践课程系列的一部分，欢迎关注收藏