mapbox-maplibre-migration

MapLibre から Mapbox への移行スキル

MapLibre GL JS から Mapbox GL JS への移行に関する専門的なガイダンスです。両者の共通する歴史、API の互換性、移行手順、Mapbox プラットフォームの利点を解説します。

フォークについて

歴史

MapLibre GL JS は、Mapbox が v2.0 からライセンスを変更したことを受けて、2020 年 12 月に作成された Mapbox GL JS v1.13.0 のオープンソースフォークです。

タイムライン：

• 2020 年以前： Mapbox GL JS はオープンソースでした（BSD ライセンス）
• 2020 年 12 月： Mapbox GL JS v2.0 でプロプライエタリライセンスが導入されました
• 2020 年 12 月： コミュニティが v1.13 をフォークし、MapLibre GL JS を作成しました
• 現在： 両方のライブラリで開発が活発に続いています

重要なポイント： MapLibre は Mapbox のフォークとして始まったため、API は約 95% 同一です。ほとんどのコードは最小限の変更で両方で動作するため、移行は簡単です。

Mapbox に移行する理由

Mapbox GL JS を選ぶ主な理由：

• 公式サポートと SLA： 応答時間が保証されたエンタープライズグレードのサポート
• 優れたタイル品質： 世界中をカバーし、頻繁に更新される最高クラスのベクタータイル
• より優れた衛星画像： 高解像度で最新の衛星画像と航空写真
• 豊富なエコシステム： Mapbox Studio、API、サービスとのシームレスな連携
• 高度な機能： 交通状況を考慮したルート検索、ターンバイターン方式の案内、プレミアムデータセット
• ジオコーディングと検索： 世界水準の住所検索と場所検索
• ナビゲーション SDK： リアルタイムの交通情報に対応したモバイルナビゲーション
• タイルインフラが不要： 独自のタイルサーバーをホスト、保守する必要がありません
• 定期的な更新： 継続的な改善と新機能
• プロフェッショナルサービス： 複雑なプロジェクト向けに Mapbox ソリューションチームを利用できます

Mapbox には手厚い無料枠があります： 月間 50,000 回のマップ読み込みが含まれており、多くのアプリケーションを無料で利用できます。

簡単な比較

項目	Mapbox GL JS	MapLibre GL JS
ライセンス	プロプライエタリ（v2 以降）	BSD 3-Clause（オープンソース）
サポート	公式の商用サポート	コミュニティサポート
タイル	Mapbox のプレミアムベクタータイル	OSM またはカスタムタイルソース
衛星画像	高品質な全世界の画像	カスタムソースが必要
トークン	必須（アクセストークン）	任意（タイルソースによる）
API	Mapbox のエコシステム全体	サードパーティサービスが必要
Studio	完全に統合	ネイティブ統合なし
3D 地形	プレミアムデータで標準搭載	利用可能（データソースが必要）
グローブビュー	v2.9 以降	v3.0 以降
API 互換性	MapLibre と約 95% 互換	Mapbox と約 95% 互換
バンドルサイズ	約 500KB	約 450KB
セットアップの複雑さ	簡単（トークンを追加するだけ）	タイルソースの設定が必要

移行手順

1. Mapbox アカウントを作成する

1. mapbox.com で登録します
2. アカウントダッシュボードからアクセストークンを取得します
3. 料金を確認します：無料枠には月間 50,000 回のマップ読み込みが含まれます
4. トークンを控えます（公開トークンは pk. で始まります）

2. パッケージを更新する

# Remove MapLibre
npm uninstall maplibre-gl

# Install Mapbox
npm install mapbox-gl

3. インポートを更新する

// Before (MapLibre)
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

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

または CDN を使用します：

<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/[email protected]/dist/maplibre-gl.css" rel="stylesheet" />


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

4. アクセストークンを追加する

// Add this before map initialization
mapboxgl.accessToken = 'pk.your_mapbox_access_token';

トークンのベストプラクティス：

• 環境変数を使用します：process.env.VITE_MAPBOX_TOKEN または process.env.NEXT_PUBLIC_MAPBOX_TOKEN
• セキュリティのため、Mapbox ダッシュボードで URL 制限を設定します
• クライアントサイドのコードには公開トークン（pk.*）を使用します
• トークンを git にコミットしないでください（.env に追加し、.gitignore に登録します）
• 漏洩した場合はトークンをローテーションします

トークンのセキュリティに関する包括的なガイダンスについては、mapbox-token-security スキルを参照してください。

5. マップの初期化を更新する

// Before (MapLibre)
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json', // or your custom style
  center: [-122.4194, 37.7749],
  zoom: 12
});

// After (Mapbox)
mapboxgl.accessToken = 'pk.your_mapbox_access_token';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard', // Mapbox style
  center: [-122.4194, 37.7749],
  zoom: 12
});

6. スタイル URL を更新する

Mapbox では、専門家がデザインし、保守しているスタイルを提供しています。

// Mapbox built-in styles
style: 'mapbox://styles/mapbox/standard'; // Mapbox Standard (default)
style: 'mapbox://styles/mapbox/standard-satellite'; // Mapbox Standard Satellite
style: 'mapbox://styles/mapbox/streets-v12'; // Streets v12
style: 'mapbox://styles/mapbox/satellite-v9'; // Satellite imagery
style: 'mapbox://styles/mapbox/satellite-streets-v12'; // Hybrid
style: 'mapbox://styles/mapbox/outdoors-v12'; // Outdoor/recreation
style: 'mapbox://styles/mapbox/light-v11'; // Light theme
style: 'mapbox://styles/mapbox/dark-v11'; // Dark theme
style: 'mapbox://styles/mapbox/navigation-day-v1'; // Navigation (day)
style: 'mapbox://styles/mapbox/navigation-night-v1'; // Navigation (night)

カスタムスタイル： Mapbox Studio でカスタムスタイルを作成して使用することもできます。

style: 'mapbox://styles/your-username/your-style-id';

7. すべての参照を更新する

すべての maplibregl の参照を mapboxgl に置き換えます。

// Markers
const marker = new mapboxgl.Marker() // was: maplibregl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setText('San Francisco'))
  .addTo(map);

// Controls
map.addControl(new mapboxgl.NavigationControl(), 'top-right');
map.addControl(new mapboxgl.GeolocateControl());
map.addControl(new mapboxgl.FullscreenControl());
map.addControl(new mapboxgl.ScaleControl());

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

一部の MapLibre プラグインは、Mapbox 版に置き換える必要があります。

MapLibre プラグイン	Mapbox の代替プラグイン
@maplibre/maplibre-gl-geocoder	@mapbox/mapbox-gl-geocoder
@maplibre/maplibre-gl-draw	@mapbox/mapbox-gl-draw
maplibre-gl-compare	mapbox-gl-compare

例：

// Before (MapLibre)
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

// After (Mapbox)
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

map.addControl(
  new MapboxGeocoder({
    accessToken: mapboxgl.accessToken,
    mapboxgl: mapboxgl,
    countries: 'us', // ISO 3166-1 alpha-2 code(s), comma-separated; hard filter, not a soft bias
    language: 'en' // Also affects which result ranks first, not just the UI/response text
  })
);

注： countries と language は、結果のフィルタリング方法や表示方法だけでなく、返される結果そのものを変えます。language は結果のスコアに影響するため、同じクエリでも言語によって最初に表示される場所が異なる場合があります。また、countries を指定すると、リストされたコード以外のすべての結果が除外されます。元の MapLibre ジオコーダーで設定していたロケールや地域の制限も引き継いでください。

9. それ以外はすべてそのままです

マップのコード、イベント、レイヤー、ソースはすべて同じように動作します。

// This code works EXACTLY THE SAME in both libraries
map.on('load', () => {
  map.addSource('points', {
    type: 'geojson',
    data: geojsonData
  });

  map.addLayer({
    id: 'points-layer',
    type: 'circle',
    source: 'points',
    paint: {
      'circle-radius': 8,
      'circle-color': '#ff0000'
    }
  });
});

// Events work identically
map.on('click', 'points-layer', (e) => {
  console.log(e.features[0].properties);
});

// All map methods work the same
map.setCenter([lng, lat]);
map.setZoom(12);
map.fitBounds(bounds);
map.flyTo({ center: [lng, lat], zoom: 14 });

変更点の概要

変更が必要なもの：

• パッケージ名（maplibre-gl -> mapbox-gl）
• インポート文
• mapboxgl.accessToken の設定を追加
• スタイル URL（mapbox:// スタイルに変更）
• プラグインパッケージ（使用している場合）

そのまま使えるもの：

• すべてのマップメソッド（setCenter、setZoom、fitBounds、flyTo など）
• すべてのイベント処理（map.on('click')、map.on('load') など）
• マーカー／ポップアップ API（100％互換）
• レイヤー／ソース API（100％互換）
• GeoJSON の処理
• カスタムスタイルと式
• コントロール（ナビゲーション、位置情報、スケールなど）

よくある移行時の問題

問題 1：トークンが設定されていない

問題：

// Error: "A valid Mapbox access token is required to use Mapbox GL"
const map = new mapboxgl.Map({...});

解決策：

// Set token BEFORE creating map
mapboxgl.accessToken = 'pk.your_token';
const map = new mapboxgl.Map({...});

問題 2：トークンが Git に含まれている

問題：

// Token hardcoded in source
mapboxgl.accessToken = 'pk.eyJ1Ijoi...';

解決策：

// Use environment variables
mapboxgl.accessToken = process.env.VITE_MAPBOX_TOKEN;

// Add to .env file (not committed to git)
VITE_MAPBOX_TOKEN=pk.your_token

// Add .env to .gitignore
echo ".env" >> .gitignore

問題 3：スタイル URL の形式が正しくない

問題：

// MapLibre-style URL won't work optimally
style: 'https://demotiles.maplibre.org/style.json';

解決策：

// Use Mapbox style URL for better performance and features
style: 'mapbox://styles/mapbox/streets-v12';

問題 4：プラグインの互換性

問題：

// MapLibre plugin won't work
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

解決策：

// Use Mapbox plugin
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

重要： これはジオコーダーだけでなく、すべての MapLibre プラグインに当てはまります。@maplibre/* または maplibre-gl-* のプラグインは、すべて Mapbox 対応版に置き換える必要があります。使用する各プラグインについて、Mapbox エコシステムに Mapbox 専用版があるか確認してください（対応表全体は上記のステップ 8 を参照）。

問題 5：CDN URL

問題：

// Wrong CDN
<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>

解決策：

// Use Mapbox CDN
<script src='https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css' rel='stylesheet' />

移行チェックリスト

• Mapbox アカウントを作成し、アクセストークンを取得する
• パッケージを更新する：npm install mapbox-gl（maplibre-gl を削除）
• インポートを更新する：maplibre-gl -> mapbox-gl
• CSS のインポートを更新する：maplibre-gl.css -> mapbox-gl.css
• トークンを追加する：mapboxgl.accessToken = 'pk.xxx' を設定する
• 環境変数を使用する：トークンを .env に保存する
• スタイル URL を更新する：mapbox://styles/mapbox/streets-v12 に変更する
• すべての参照を更新する：maplibregl. を mapboxgl. に置き換える
• プラグインを更新する：プラグインの Mapbox 版をインストールする（使用している場合）
• トークンのセキュリティを設定する：ダッシュボードで URL 制限を追加する
• すべての機能をテストする：マップが読み込まれ、操作が機能することを確認する
• 請求アラートを設定する：Mapbox ダッシュボードで使用量を監視する
• ドキュメントを更新する：チーム向けにトークンの設定方法を記載する
• .env を .gitignore に追加する：トークンがコミットされないようにする

クイックリファレンス

主な違いの概要

項目	MapLibre	Mapbox
パッケージ	maplibre-gl	mapbox-gl
インポート	import maplibregl from 'maplibre-gl'	import mapboxgl from 'mapbox-gl'
トークン	任意（タイルによって異なります）	必須：mapboxgl.accessToken = 'pk.xxx'
スタイル	カスタム URL または OSM タイル	mapbox://styles/mapbox/streets-v12
ライセンス	BSD（オープンソース）	プロプライエタリ（v2 以降）
サポート	コミュニティ	公式の商用サポート
タイル	タイルソースが必要	Mapbox のプレミアムタイルを利用可能
API 群	サードパーティ製	Mapbox API エコシステム全体
API	約 95% 互換	約 95% 互換

結論： API がほぼ同一のため、移行は簡単です。主な変更点はパッケージング、トークンの設定、スタイル URL です。移行後は、Mapbox のプレミアムタイル、エコシステム、サポートを利用できます。

他のスキルとの連携

関連スキル：

• mapbox-web-integration-patterns：フレームワーク別のパターン（React、Vue、Svelte、Angular）
• mapbox-web-performance-patterns：パフォーマンス最適化の手法
• mapbox-token-security：トークンセキュリティの包括的なベストプラクティス
• mapbox-google-maps-migration：Google Maps から Mapbox への移行

リソース

Mapbox GL JS：

• 公式ドキュメント
• サンプルギャラリー
• API リファレンス
• GitHub リポジトリ
• Mapbox Studio
• 料金情報

移行サポート：

• スタートガイド
• スタイル仕様
• Mapbox コミュニティサポート

参照ファイル

特定のトピックの詳細については、次の参照ファイルを読み込んでください。

• references/api-compatibility.md -- 100% 互換の API の全一覧と、並べて比較できる移行例
• references/exclusive-features.md -- Mapbox 独自の機能（API、Studio、Advanced）と React／Vue のフレームワーク例
• references/why-mapbox.md -- Mapbox を選ぶ理由（本番環境、開発チーム、ビジネス）とパフォーマンス比較