maplibre-mapbox-migration

Mapbox から MapLibre への移行

このスキルでは、アプリケーションを Mapbox GL JS から MapLibre GL JS に移行する方法を説明します。2つのライブラリには共通の系譜があり（MapLibre は 2020 年 12 月に Mapbox GL JS v1.13 からフォークされました）、API の大部分は共通です。主な変更点は、パッケージの切り替え、名前空間の置き換え、Mapbox アクセストークンの削除、そして新しいタイルソースの選択です（MapLibre は mapbox:// スタイルを使用しません）。

主な参考資料： MapLibre 公式の Mapbox 移行ガイド。

このスキルを使う場面

• 既存の Mapbox GL JS アプリを MapLibre に移行する
• Mapbox のオープンソース代替として MapLibre を評価する
• API の互換性と変更による影響を把握する
• Mapbox から移行した後のタイルソースとサービスを選択する

MapLibre に移行する理由

チームが Mapbox から切り替える一般的な理由は次のとおりです。

• オープンソースライセンス — MapLibre は BSD-3-Clause です。ベンダーロックインや独自の利用条件はありません
• アクセストークン不要 — ライブラリに Mapbox トークンは必要ありません。タイルソースには独自のキーが必要な場合と不要な場合があります（例：OpenFreeMap）
• コスト — Mapbox のマップ読み込み料金や API 料金を回避し、無料または固定料金のタイルおよびジオコーディングプロバイダーを利用できます
• セルフホスト — 独自のタイル（PMTiles、tileserver-gl、Martin）や、任意のサードパーティソースを利用できます
• コミュニティ — MapLibre は MapLibre 組織とコミュニティによって保守されています。スタイル仕様と API はオープンに進化しています
• コミュニティが支援する資金調達 — MapLibre は多くの企業や個人からの寄付によって資金を得ています。特定の単一企業が商業的な後ろ盾となっていないため、プロジェクトはコミュニティの意向に沿って進められます
• オープンなベクタータイル形式（MLT） — MapLibre は、Mapbox Vector Tiles（MVT）の現代的な代替形式である MapLibre Tile（MLT） を提供しています。より高い圧縮率を実現し、3D 座標と標高をサポートします。GL JS と Native でサポートされており、Planetiler で生成できます

利用できなくなるもの： Mapbox Studio との連携、Mapbox がホストするタイルとスタイル、Mapbox Search／Directions／Geocoding API、Mapbox の公式サポート。

フォークについて

• 2020年12月： Mapbox GL JS v2.0が独自ライセンスに切り替わりました。コミュニティはv1.13をフォークし、MapLibre GL JSを作成しました。MapLibre organizationとGL JS repoが公式の拠点です。
• API： MapLibre GL JS v1.xは、Mapbox GL JS v1.xとの後方互換性をおおむね維持しています。地図のコード（メソッド、イベント、レイヤー、ソース）の多くは、最小限の変更で動作します。
• フォーク後のリリース： MapLibreは独自のバージョン系列で開発を進めています。v2.2では3D地形が追加され、v3ではWebGL2に移行しました。v4では公開APIにPromiseが導入され（多くのコールバックを置き換え）、v5では地球投影法が追加されました。v6（2026-07-22）はESモジュールのみで提供され、UMDバンドルとデフォルトエクスポートが廃止されました（以下のインポートとCSSを更新するを参照）。また、いくつかのデフォルト値が変更されています（v5からv6への移行ガイドを参照）。リリースとCHANGELOGを参照してください。
• スタイル仕様： MapLibreは独自のMapLibre Style Specification（Mapbox仕様からフォークしたもの）を管理しています。ほとんどのスタイルとの互換性がありますが、一部の機能が追加・変更されています。新しい機能やMapLibre固有の機能を使用する場合は、スタイル仕様のサイトを確認してください。
• エコシステム： GL JSに加え、MapLibre組織はMapLibre Native（iOS、Android、デスクトップ）、Martin（PostGIS／PMTiles／MBTiles対応のベクタータイルサーバー）、MapLibre Tile（MLT）形式を提供しています。ロードマップとニュース：maplibre.org/roadmap、maplibre.org/news。

手順に沿った移行

1. パッケージをインストールする

npm install maplibre-gl

2. インポートとCSSを更新する

// Before (Mapbox)
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

// After (MapLibre) — v6 ships ES modules only; the default export is gone
import * as maplibregl from 'maplibre-gl';
// or pull in just what you need: import {Map} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

CDN： Mapboxのスクリプト／リンクをMapLibreに置き換えます。Mapboxの<script src> パターンをそのまま使えるとは限りません。MapLibreの配布バンドル形式はメジャーバージョンごとに変更されており（v6ではUMDビルドが廃止されています）。このスニペットをそのままコピーする前に、 最新のリリースノートを確認してください。

<script src="https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.css" rel="stylesheet" />


<script type="module">
  import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs';
</script>
<link href="https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.css" rel="stylesheet" />

3. 名前空間を置き換える

mapboxglをすべてmaplibreglに置き換えます（パッケージ名やパスではmapbox-glをmaplibre-glに置き換えます）。例：

// Before (Mapbox)
const map = new mapboxgl.Map({ ... });
new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new mapboxgl.NavigationControl());

// After (MapLibre)
const map = new maplibregl.Map({ ... });
new maplibregl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new maplibregl.NavigationControl());

CSSクラス名： クラス名でコントロールやUIのスタイルを設定している場合は、mapboxgl-ctrlをmaplibregl-ctrlに置き換えます（同様のプレフィックスも置き換えます）。

4. アクセストークンを削除する

MapLibreはmapboxgl.accessTokenを使用しません。これを設定する行は削除してください。

タイルやAPIのキー（ホスト型タイルサービスやジオコーディング用など）は、地図インスタンスではなく、サービスごとに設定します。

5. スタイル URL を置き換える（重要）

Mapbox スタイル（mapbox://styles/...）は MapLibre では動作しません。Mapbox 以外のタイルソース、スプライト、グリフを使用するスタイルを地図に指定する必要があります。

最も簡単なのは、OpenFreeMap のように API キーが不要なスタイル URL を使用することです。OpenFreeMap はコミュニティの資金で運営されており、API キーなしで無料で利用できます。本番環境でアプリが OpenFreeMap に依存する場合は、プロジェクトへの寄付をご検討ください。移行が正常に動作することをテストして確認したら、利用可能な多くの選択肢を検討できます（その他の候補については、awesome-maplibre または MapLibre Tile Sources をご覧ください）。

例：

// Before (Mapbox)
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-122.42, 37.78],
  zoom: 12
});

// After (MapLibre)
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/liberty', // or your chosen style
  center: [-122.42, 37.78],
  zoom: 12
});

その後、スタイルを検証してデバッグするために、MapLibre Style Specification & Utilities をインストールできます。

npm install --save-dev @maplibre/maplibre-gl-style-spec

カスタム Mapbox スタイル： Mapbox Studio でスタイルを作成した場合、MapLibre で直接読み込むことはできません。スタイル JSON をエクスポートし、Mapbox のソース URL を選択したタイルソースの URL に置き換えてください。新しいタイルソースのタイルスキーマに合わせて、Mapbox のタイルスキーマへのすべての参照を調整するまで、スタイルはレンダリングされません。 ソース URL の更新に加え、スタイル JSON の id、source、source-layer プロパティを新しいソース名とレイヤー名に合わせる必要があります。

Mapbox スタイルのほとんどのプロパティは MapLibre と互換性があります。サポートされているプロパティと型の詳細については、MapLibre Style Specification をご確認ください。MapLibre のスタイルエディターである Maputnik を使ってスタイル JSON を視覚的にテスト、デバッグできます。また、互換性やその他の検証上の問題は MapLibre Style Spec CLI Tools で確認できます。

npx gl-style-validate style.json

6. プラグインを更新する（使用している場合）

多くの Mapbox プラグインは変更なしで MapLibre でも動作し、MapLibre ネイティブ版にフォークまたは置き換えられたものも多数あります。MapLibre ネイティブの代替プラグインがある場合は、長期的な互換性のため、そちらを優先してください。

互換性のあるプラグインや代替プラグインを見つけるには、awesome-maplibre の「User Interface Plugins」、「Geocoding & Search Plugins」、「Map Rendering Plugins」セクションをご確認ください。

7. Mapbox API（検索、ルート案内など）を置き換える

アプリで Mapbox Geocoding、Directions、その他の REST API を呼び出している場合は、オープンなサービスまたはサードパーティーのサービスに置き換えてください。

• ジオコーディング／検索： Nominatim、Photon、Pelias、または MapTiler Geocoding
• ルート案内／ルーティング： OSRM、OpenRouteService、Valhalla

利用ポリシーと持続可能性： これらはオープンなサービス、またはコミュニティの資金で運営されているサービスです。本番環境で利用する際には、利用規約が重要になります。

• Nominatim — OpenStreetMap の帰属表示が必要です。公開インスタンスはテストと低頻度の利用に限られています。Nominatim の利用ポリシーを参照してください。本番環境のワークロードでは、セルフホストするか、マネージドプロバイダー（例：MapTiler Geocoding）を利用してください。
• OSRM デモサーバー（router.project-osrm.org）— 本番環境での利用は明示的に禁止されており、SLA や稼働時間の保証はありません。本番環境のアプリでは、セルフホストするか、マネージドサービス（例：OpenRouteService、MapTiler Directions）を利用してください。
• アプリでコミュニティが維持するサービスを大規模に利用している場合は、コミュニティに還元しましょう。セルフホストして共有インフラへの負荷を減らす、寄付する、または上流プロジェクトにコードやドキュメントを提供してください。

コードを更新し、新しいエンドポイントとレスポンス形式を使用してください。MapLibre では、マップレイヤーとインタラクションのコード（例：ルート線の追加）はそのまま使えます。

8. 変更されない部分

マップコードの大部分は変更不要です。

• マップメソッド：setCenter、setZoom、fitBounds、flyTo、getBounds など
• イベント：map.on('load')、map.on('click', layerId, callback) など
• マーカー、ポップアップ、コントロール（Navigation、Geolocate、Fullscreen、Scale）
• ソースとレイヤー：addSource、addLayer、setPaintProperty、setFilter
• スタイル仕様内の GeoJSON と式

そのため、パッケージ、名前空間、トークン、スタイル（およびプラグイン／API）を置き換えれば、残りのロジックはそのまま使えます。

9. Mapbox v2 専用 API は、探さずに置き換えます

フォーク後に追加された Mapbox GL JS v2 のメソッドは、MapLibre には Mapbox の名称では存在せず、MapLibre のどのリリースでも追加されません。Mapbox の名称で検索し、「バージョンの問題に違いない」と結論づけるのは、移行時によくある行き詰まりです。代わりに、MapLibre での名称を調べてください。

Mapbox GL JS v2	MapLibre GL JS	備考
map.setFog({...})、スタイルのルートレベルにある fog	map.setSky({...}) / map.getSky()、スタイルのルートレベルにある sky	MapLibre には どのバージョンにも setFog メソッドはありません。sky と setSky は GL JS v4.5.0 から存在します。大気は sky に含まれ、そのプロパティには sky-color、horizon-color、fog-color、fog-ground-blend、horizon-fog-blend、sky-horizon-blend、atmosphere-blend があります。スタイル仕様では sky は実験的機能とされています。
map.getFreeCameraOptions() / map.setFreeCameraOptions()、FreeCameraOptions	map.calculateCameraOptionsFromCameraLngLatAltRotation(...) → jumpTo / easeTo / flyTo	MapLibre には FreeCameraOptions クラスも、getFreeCameraOptions / setFreeCameraOptions もありません。カメラは center、zoom、pitch、bearing に加え、CameraOptions の elevation と roll（どちらも v5.0.0）で表します。カメラの経度・緯度・高度を基準に配置するには、calculateCameraOptionsFromCameraLngLatAltRotation(cameraLngLat, cameraAlt, bearing, pitch, roll)（v5.0.0）で変換するか、注視点を指定する場合は calculateCameraOptionsFromTo(from, altitudeFrom, to, altitudeTo)（v2.4.0）を使用し、返された CameraOptions を jumpTo、easeTo、または flyTo に渡します。

// Mapbox GL JS v2
map.setFog({ 'horizon-blend': 0.3, color: '#ffffff' });

// MapLibre GL JS — the same idea, different property names
map.setSky({
  'sky-color': '#199EF3',
  'horizon-color': '#ffffff',
  'fog-color': '#0000ff',
  'fog-ground-blend': 0.5,
  'horizon-fog-blend': 0.5,
  'sky-horizon-blend': 0.5,
  'atmosphere-blend': 1.0
});

ほかの v2 メソッドについても、アップグレードすれば復元されると決めつける前に、Map API リファレンスで確認してください。

チェックリスト

• mapbox-gl をアンインストールし、maplibre-gl をインストールします
• インポートと CSS を置き換えます（mapbox-gl → maplibre-gl）
• すべての mapboxgl を maplibregl に置き換えます（CSS クラスも mapboxgl- → maplibregl- に置き換えます）
• mapboxgl.accessToken を削除します
• style に Mapbox 以外の URL（ホストされたスタイルまたは独自のスタイル）を設定します
• 互換性のない Mapbox プラグインを、MapLibre またはオープンな代替手段に置き換えます
• Mapbox Geocoding／Directions を Nominatim、OSRM、またはその他のオープンな代替手段に置き換えます
• Mapbox v2 専用 API を置き換えます（setFog → setSky、フリーカメラ → calculateCameraOptionsFromCameraLngLatAltRotation + jumpTo／easeTo／flyTo）
• マップの読み込み、コントロール、API 駆動の機能をテストします

関連スキル

• maplibre-tile-sources — データに適したソースタイプの選択
• maplibre-pmtiles-patterns — PMTiles を使用したサーバーレスタイル

このスキルで使用したソース

このスキルの作成時に、以下のソースを使用しました。これらを保守している、または貢献したコントリビューターにも協力を依頼するとよいでしょう。

1. MapLibre 公式移行ガイド — maplibre.org/maplibre-gl-js/docs/guides/mapbox-migration-guide/ — 主な手順を説明するリファレンス（パッケージ、名前空間、CSS、CDN）。
2. MapLibre GL JS ドキュメント — maplibre.org/maplibre-gl-js/docs/ — API と概念。
3. MapLibre スタイル仕様 — sky — maplibre.org/maplibre-style-spec/sky/ および Map.setSky — Mapbox の fog に代わる大気のプロパティ。Mapbox のフリーカメラに代わるカメラ位置の設定方法については、Map.calculateCameraOptionsFromCameraLngLatAltRotation および CameraOptions を参照してください。
4. MapLibre GL JS GitHub — github.com/maplibre/maplibre-gl-js — README、リリース、フォークの経緯。
5. mapbox-agent-skills — Mapbox リポジトリの mapbox-maplibre-migration スキルでは、逆方向（MapLibre → Mapbox）の移行を扱っています。この Mapbox → MapLibre スキルでは、トピックの構成と比較要素を参考にしています。参考にした部分の著作権は Mapbox, Inc. に帰属します。
6. このリポジトリのスキル — maplibre-tile-sources、maplibre-pmtiles-patterns。maplibre-open-search-patterns と maplibre-geospatial-operations はまだリポジトリにありません。移行後のタイルソースとサービスの代替手段については、これらを参照してください。

---

このスキルはある時点のスナップショットです。 主な情報源（上記の参考資料、MapLibre の現行ドキュメント、または MapLibre の実行時の動作）とこのスキルの内容が矛盾する場合は、情報源を優先してください。そちらに従ったうえで、情報源と使用中の MapLibre のバージョンを明記して相違点を報告してください。インストール済みのコピーを編集しても他のユーザーの役には立たず、次回の更新時に上書きされます。