MapLibre to Mapbox Migration Skill

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. パッケージを更新

# MapLibre を削除
npm uninstall maplibre-gl

# Mapbox をインストール
npm install mapbox-gl

3. インポートを更新

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

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

または CDN を使用:

<!-- 以前 (MapLibre) -->
<script src="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.css" rel="stylesheet" />

<!-- 以後 (Mapbox) -->
<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. アクセストークンを追加

// マップ初期化前にこれを追加
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. マップ初期化を更新

// 以前 (MapLibre)
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json', // またはカスタムスタイル
  center: [-122.4194, 37.7749],
  zoom: 12
});

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

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

6. スタイル URL を更新

Mapbox はプロフェッショナルに設計・保守されたスタイルを提供しています:

// Mapbox 組み込みスタイル
style: 'mapbox://styles/mapbox/standard'; // Mapbox Standard (デフォルト)
style: 'mapbox://styles/mapbox/standard-satellite'; // Mapbox Standard Satellite
style: 'mapbox://styles/mapbox/streets-v12'; // Streets v12
style: 'mapbox://styles/mapbox/satellite-v9'; // 衛星画像
style: 'mapbox://styles/mapbox/satellite-streets-v12'; // ハイブリッド
style: 'mapbox://styles/mapbox/outdoors-v12'; // アウトドア/レクリエーション
style: 'mapbox://styles/mapbox/light-v11'; // ライトテーマ
style: 'mapbox://styles/mapbox/dark-v11'; // ダークテーマ
style: 'mapbox://styles/mapbox/navigation-day-v1'; // ナビゲーション (昼間)
style: 'mapbox://styles/mapbox/navigation-night-v1'; // ナビゲーション (夜間)

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

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

7. すべての参照を更新

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

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

// コントロール
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

例:

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

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

map.addControl(
  new MapboxGeocoder({
    accessToken: mapboxgl.accessToken,
    mapboxgl: mapboxgl
  })
);

9. その他すべてはそのまま

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

// このコードは両方のライブラリで EXACTLY THE SAME で動作します
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'
    }
  });
});

// イベントも同じように動作します
map.on('click', 'points-layer', (e) => {
  console.log(e.features[0].properties);
});

// すべてのマップメソッドは同じです
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: トークンが設定されていない

問題:

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

解決策:

// マップ作成 BEFORE にトークンを設定
mapboxgl.accessToken = 'pk.your_token';
const map = new mapboxgl.Map({...});

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

問題:

// トークンがソースにハードコーディングされている
mapboxgl.accessToken = 'pk.eyJ1Ijoi...';

解決策:

// 環境変数を使用
mapboxgl.accessToken = process.env.VITE_MAPBOX_TOKEN;

// .env ファイルに追加 (git にコミットされていません)
VITE_MAPBOX_TOKEN=pk.your_token

// .env を .gitignore に追加
echo ".env" >> .gitignore

問題 3: 間違ったスタイル URL フォーマット

問題:

// MapLibre スタイル URL は最適に機能しません
style: 'https://demotiles.maplibre.org/style.json';

解決策:

// より良いパフォーマンスと機能のために Mapbox スタイル URL を使用
style: 'mapbox://styles/mapbox/streets-v12';

問題 4: プラグイン互換性

問題:

// MapLibre プラグインは機能しません
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

解決策:

// Mapbox プラグインを使用
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

重要: これはジオコーダーだけでなく、すべての MapLibre プラグインに適用されます。あらゆる @maplibre/* または maplibre-gl-* プラグインは Mapbox の同等物に置き換える必要があります。使用するすべてのプラグインの Mapbox 固有バージョンについて Mapbox エコシステムをチェックしてください (完全なマッピングテーブルについては上記ステップ 8 を参照)。

問題 5: CDN URL

問題:

// 間違った CDN
<script src="https://unpkg.com/maplibre-gl@3.0.0/dist/maplibre-gl.js"></script>

解決策:

// 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 を選択する理由 (本番環境、開発チーム、ビジネス) + パフォーマンス比較