consbio/mbgl-renderer

Mapbox GL静态地图渲染器

概述

Mapbox GL静态地图渲染器是一个基于Mapbox GL技术的工具，用于生成静态地图图像。它提供命令行界面、HTTP接口和NodeJS API三种使用方式，支持栅格和矢量瓦片，兼容Mapbox及其他瓦片提供商的服务，还可使用本地mbtiles文件进行渲染。

警告：本项目依赖Mapbox GL的NodeJS绑定（mapbox-gl-native），该绑定已不再由Mapbox维护，且仅支持NodeJS 10（已超出生命周期）。目前项目处于维护模式，主要功能不会有重大更新。

核心功能与特性

• 使用mapbox-gl-native通过NodeJS渲染静态地图
• 支持栅格和矢量瓦片
• 兼容Mapbox瓦片（需注意归因）及其他托管瓦片提供商
• 支持本地mbtiles文件渲染（相比网络瓦片可显著提升渲染速度）
• 可添加GeoJSON叠加层
• 支持高DPI渲染
• 提供Docker镜像便于部署

使用场景与适用范围

• 生成供下载或报告使用的静态地图
• 结合自定义样式或叠加层创建个性化地图
• 注意：若仅使用Mapbox托管样式和矢量瓦片，建议优先使用Mapbox Static API，其功能更完善。

归因要求

使用地图时，需根据数据和样式提供商的要求进行适当归因：

• 使用Mapbox样式或托管瓦片时，必须包含Mapbox归因
• 其他数据源的归因需遵循其指定方式

使用方法

Style JSON配置

所有渲染方法的核心输入是Mapbox GL Style JSON文件，详细格式参考Mapbox文档。

标签配置

如需使用文本标签，需在Style JSON中添加glyphs字段（与sources同级）：

• 使用Mapbox托管字体（需Mapbox token）：

  json
  "glyphs": "mapbox://fonts/mapbox/{fontstack}/{range}.pbf"
  

• 使用OpenMapTiles托管字体：

  json
  "glyphs": "http://fonts.openmaptiles.org/{fontstack}/{range}.pbf"
  

NodeJS API

需使用Babel提供ES6特性支持。

基础示例（中心坐标+缩放级别）

javascript
import render from 'mbgl-renderer';
import style from 'tests/fixtures/example-style.json';
import fs from 'fs';

const width = 512;
const height = 256;
const center = [-79.86, 32.68];
const zoom = 10;

render(style, width, height, { zoom, center })
  .then((data) => {
    fs.writeFileSync('test.png', data);
  });

边界范围渲染

javascript
const width = 512;
const height = 256;
const bounds = [-80.23, 32.678, -79.73, 32.891];

render(style, width, height, { bounds })
  .then((data) => {
    fs.writeFileSync('test.png', data);
  });

带内边距的边界渲染

javascript
const width = 512;
const height = 256;
const bounds = [-80.23, 32.678, -79.73, 32.891];
const padding = 25; // 像素值，需小于宽/高的1/2

render(style, width, height, { bounds, padding })
  .then((data) => {
    fs.writeFileSync('test.png', data);
  });

高DPI渲染

javascript
const width = 512;
const height = 256;
const center = [-79.86, 32.68];
const zoom = 10;
const ratio = 2; // 像素比率，通常>1（已测试最大31）

render(style, width, height, { zoom, center, ratio })
  .then((data) => {
    fs.writeFileSync('test.png', data);
  });

方位角和俯仰角设置

javascript
const width = 512;
const height = 256;
const center = [-79.86, 32.68];
const zoom = 10;
const bearing = 90; // 方位角（0-360度）
const pitch = 30; // 俯仰角（0-60度）

render(style, width, height, { zoom, center, bearing, pitch })
  .then((data) => {
    fs.writeFileSync('test.png', data);
  });

使用Mapbox托管资源（需token）

javascript
render(style, width, height, { bounds, token: '<your access token>' })
  .then((data) => {
    fs.writeFileSync('test.png', data);
  });

命令行接口

基本用法

bash
mbgl-render <style.json> <img_filename> <width> <height> [options]

选项说明

• -c, --center <longitude,latitude>: 地图中心（无空格）
• -z, --zoom <n>: 缩放级别
• -r, --ratio <n>: 像素比率
• -b, --bounds <west,south,east,north>: 边界范围（无空格）
• --padding <padding>: 内边距像素（仅与bounds配合使用）
• --bearing <degrees>: 方位角（0-360度）
• --pitch <degrees>: 俯仰角（0-60度）
• -t, --tiles <mbtiles_path>: 本地mbtiles文件目录
• --token <mapbox access token>: Mapbox访问令牌

使用示例

• 中心坐标+缩放级别渲染：

  bash
  mbgl-render tests/fixtures/example-style.json test.png 512 256 -c -79.86,32.68 -z 10
  

• 边界范围渲染：

  bash
  mbgl-render tests/fixtures/example-style.json test.png 512 256 -b -80.23,32.678,-79.73,32.891
  

• 带内边距的边界渲染：

  bash
  mbgl-render tests/fixtures/example-style.json test.png 512 256 -b -80.23,32.678,-79.73,32.891 --padding 25
  

• 使用本地mbtiles：

  bash
  mbgl-render tests/fixtures/example-style-mbtiles-source-vector.json test.png 1024 1024 -z 0 -c 0,0 -t tests/fixtures
  

• 使用Mapbox托管样式：

  bash
  mbgl-render mapbox://styles/mapbox/outdoors-v10 test.png 1024 1024 -c 0,0 -z 0 --token <your mapbox token>
  

静态图像服务器

启动服务器

bash
mbgl-static-server [options]

选项说明

• -p, --port <n>: 服务器端口
• -t, --tiles <mbtiles_path>: 本地mbtiles文件目录
• -v, --verbose: 启用请求日志

启动示例

bash
# 启动在8080端口，使用本地tiles目录
mbgl-static-server -p 8080 -t tests/fixtures

# 通过npm启动（需使用--传递参数）
npm start -- --port 8080 --tiles tests/fixtures

请求方法

GET请求

参数说明：

• height/width: 图像尺寸（整数）
• zoom: 缩放级别（浮点数）
• ratio: 像素比率（整数）
• center: 中心坐标（格式：longitude,latitude，无空格）
• bounds: 边界范围（格式：west,south,east,north，无空格）
• padding: 内边距（整数，仅与bounds配合使用）
• bearing: 方位角（0-360度，浮点数）
• pitch: 俯仰角（0-60度，浮点数）
• token: Mapbox访问令牌
• style: URL编码的Style JSON

示例：

bash
# 使用httpie工具测试
http :8080/render width=400 height=400 zoom=0 center=0,0 style:=@tests/fixtures/example-style.json > /tmp/test.png

POST请求

支持所有GET参数，Style JSON可直接作为JSON传递（无需URL编码），适用于Style JSON过长的场景。

Docker部署

拉取镜像

bash
docker pull docker.xuanyuan.run/consbio/mbgl-renderer:latest

运行服务器

bash
# 基本运行（端口8080）
docker run --rm -p 8080:80 docker.xuanyuan.run/consbio/mbgl-renderer

# 挂载本地tiles目录
docker run --rm -p 8080:80 -v $(pwd)/tests/fixtures:/app/tiles docker.xuanyuan.run/consbio/mbgl-renderer

构建自定义镜像

bash
docker build -t <image_name> -f docker/Dockerfile .

注意事项

• NodeJS版本：仅支持NodeJS 10，其他版本需自行从源码构建mapbox-gl-native
• 无头服务器：需使用xvfb提供GL环境，参考Dockerfile配置
• 测试：运行测试需设置MAPBOX_API_TOKEN环境变量（创建.env.test文件）