はじめに
本ドキュメントの目的
本書は、jQueryの大幅なバージョンアップに伴う互換性問題を解決するための実務的なガイドです。jQuery Migrateプラグインの役割や導入方法、段階的なバージョンアップ手順、テスト環境の作り方、警告への対処法、全体の流れを一冊で分かりやすくまとめます。
対象読者
- 既存のWebサイトを運用している開発者や運用担当者
- jQueryのバージョンアップを検討しているチームリーダー
- 互換性問題に不安があるフロントエンドエンジニア
本書で学べること
- jQuery Migrateプラグインで互換性を保つ方法
- CDNを使った簡単な導入手順
- 安全にバージョンを上げる段階的な進め方
- テスト環境の作り方と検証ポイント
- Migrateが出す警告の読み方と具体的な対処法
読み進め方の提案
まず第2章でMigrateの役割を理解してください。その後、第3章以降で導入とテスト、警告対応の順に読み進めると実務に活かしやすくなります。章ごとに手順と注意点を丁寧に説明しますので、必要に応じて参照してください。
jQuery Migrateプラグインとは何か
概要
jQuery Migrateプラグインは、jQuery本体のバージョン更新で非推奨になったり削除された機能を一時的に復元するツールです。古いコードが理由で動かなくなる箇所をコンソール上に警告として表示し、移行作業を助けます。
主な機能
- 削除・変更されたAPIの互換レイヤーを提供します。
- コンソールに詳細な警告メッセージを出します。どの行で何が問題か分かりやすくなります。
いつ使うか
バージョンアップ直後の確認期間に使います。まずプラグインを入れて警告を確認し、警告に従ってコードを修正します。修正が終わったらプラグインは外します。
注意点
長期間の併用はおすすめしません。互換レイヤーが本来の問題を覆い隠し、将来の不具合や性能低下の原因になります。あくまで移行のための緩衝材と考えてください。
簡単な例
古いメソッドを使った部分でコンソールに「deprecated」と表示されます。表示内容に従って該当箇所を現行APIに置き換えてください。
jQuery Migrateプラグインの導入方法
導入の基本
jQuery Migrateは、古い書き方や削除された機能を一時的に補うためのプラグインです。導入は簡単で、まずjQuery本体を読み込み、その直後にMigrateを読み込みます。順序を逆にすると動作しないので注意してください。
CDNから読み込む（具体例）
最も手軽なのはCDN（外部配信サービス）を使う方法です。以下は代表的な例です。バージョンはjQuery 3.7.1、Migrate 3.5.2を想定しています。
- 公式CDN（code.jquery.com）
- Google CDN
- Microsoft CDN
読み込みは内またはの末尾のどちらでも可能です。一般的には表示を速くするためにの末尾に置きます。
ローカル設置とフォールバック
CDNが使えない環境では、ファイルをダウンロードして自分のサーバーに置きます。CDNと併用する場合はフォールバックを用意すると安全です。例：
window.jQuery || document.write(”)
導入時の注意点（メリット・デメリット）
メリット：設置が非常に簡単で、複数サイトで同じファイルが使われればブラウザがキャッシュを共有しやすくなります。デメリット：CDN側で障害が起きると読み込めなくなります。オフライン環境や厳しいセキュリティポリシーがある場合はローカル設置が向きます。
以上が導入方法の基本です。次章では段階的なバージョンアップ手順を説明します。
段階的なバージョンアップの手順
概要
jQuery 1.8.2 から 3.7.1 へ一気に上げると不具合が出やすいです。まず 1.12.4 に移行して Migrate プラグインで問題点を洗い出し、警告を潰してから 3.7.1 に移す段階的な手順をおすすめします。
ステップ 1: 準備と現状把握
・バックアップを必ず取ります（ファイルとデータベース）。
・index.html の script タグ、package.json、プラグインの利用箇所を一覧にします。
ステップ 2: 1.12.4 と Migrate の導入
例:
導入後、ブラウザの開発者ツールのコンソールで警告を確認します。
ステップ 3: 警告を順に潰す
よくある置換例:
・$(selector).size() → $(selector).length
・$(elem).bind(…) → $(elem).on(…)
・$(elem).live(…) → $(document).on(…, selector)
警告ごとにコードを修正し、都度動作確認します。
ステップ 4: 3.7.1 への移行
プラグインやカスタムコードを最新互換に更新したら、jQuery を 3.7.1 に切り替えます。Migrate の 3.x 系を併用して残る警告を潰します。例:
ステップ 5: Migrate の削除と最終確認
すべての警告が解消されたら Migrate スクリプトを外し、エンドツーエンドのテストを実行します。問題がなければ本番へ反映します。
注意点
・外部プラグインの互換性を確認してください。テスト環境で段階的に確認することが最も安全です。
テスト環境の構築
準備
最初に本番サイトの完全バックアップを取ります。ファイル一式とデータベースを別々に保存してください。作業中に連絡先や重要情報を書いたメモを用意すると安全です。
ファイルのコピー
FTP/SFTPまたはSSHで本番サーバーから全ファイルをダウンロードします。WordPressならwp-contentやテーマ・プラグインフォルダを優先で取得します。テスト先はサブドメインや別サーバーを用意してください。
データベースの移行
phpMyAdminでエクスポート・インポート、またはmysqldumpとmysqlコマンドで移します。新しいデータベース名と接続情報を設定ファイル（例: wp-config.php）に反映させます。
設定の切り替えと保護
サイトURLやメール送信をテスト用に書き換えます。robots.txtやベーシック認証で検索エンジンや第三者からのアクセスを防ぎます。メールは外部送信を無効にしてください。
動作確認チェックリスト
・ブラウザのコンソールでエラーや警告を確認
・主要ページ、ログイン、フォーム、ファイルアップロードを検証
・キャッシュやCDNを無効化して最新状態で確認
・プラグイン・テーマを順に有効化して問題箇所を特定
ロールバック準備
問題が発生した際はすぐ復元できるようバックアップ手順を記録しておきます。テストで得た変更点は一覧にまとめ、本番反映前に再確認してください。
警告への対処方法
1. コンソールの確認と優先度付け
まずブラウザのデベロッパーツールを開き、コンソールに出る警告を確認します。警告にはファイル名と行番号が出ることが多いので、影響範囲の広いもの（ページ全体に影響するAPI呼び出しなど）を優先して対応します。
2. よくある置換例（実際のコードで示す）
- 古い書き方: $(‘selector’).size();
新しい書き方: $(‘selector’).length; - 古い書き方: $(elem).bind(‘click’, fn);
新しい書き方: $(elem).on(‘click’, fn); - 古い書き方: $(document).delegate(‘.a’,’click’,fn);
新しい書き方: $(document).on(‘click’, ‘.a’, fn); - 古い書き方: $(window).load(fn);
新しい書き方: $(window).on(‘load’, fn);
これらは一つずつ置き換えるだけで多くの警告を消せます。
3. 発見場所の特定方法
ソースマップがあると行番号から元のファイルを特定できます。行番号が分からない場合は、プロジェクト全体でgrepやIDEの検索機能で該当APIを検索します。コンソールのスタックトレースも活用してください。
4. サードパーティ製コードへの対応
テーマやプラグインの外部ライブラリが原因なら、まず最新版に更新します。提供元が更新していない場合は、次の選択肢を検討します:
– 自分で一時的に修正パッチを当てる（子テーマやローカルコピーに適用）
– 軽い互換ラッパーを作る（簡単な置換関数など）
– 作者に報告して対応を依頼する
重要なのは警告がゼロになるまで繰り返し確認することです。
5. WordPressでの注意点
WordPressではプラグインやテーマ側が非推奨APIを使っていることが多いです。wp_enqueue_scriptで正しいjQueryを読み込み、まずはプラグインを最新化してください。修正が必要な場合はプラグイン内の該当箇所を上記の例に合わせて書き換えます。
6. 最後に
修正後はページを再読み込みして警告が消えているか確認します。警告が残る限りテストと修正を繰り返してください。
バージョンアップの全体的な流れ
1. 現行バージョンと依存関係の洗い出し
まず作業対象のjQueryとプラグイン、テーマ、カスタムスクリプトのバージョンを一覧にします。例：jQuery 1.11、プラグインA v2.3。依存するライブラリも忘れずに記録します。
2. テスト環境の構築
ローカルまたはステージング環境を用意します。実運用と同じデータや設定を用意すると問題点が見つかりやすくなります。自動化テストやブラウザの互換性チェックも設定してください。
3. Migrateプラグインを用いた段階的アップグレード
jQuery Migrateを導入して警告を確認します。警告を一つずつ潰しながら、jQueryを段階的に上げます。例：1.11→1.12→2.x→3.xの順にテストします。Migrateは互換性の橋渡し役です。
4. テストと修正
コンソールの警告や機能不具合を修正します。表示崩れやイベントの動作不良を確認し、該当コードをモダンな書き方に書き換えます。変更は小分けでコミットしてください。
5. 本番リリースと監視
本番へ適用する際はメンテナンスウィンドウを確保します。ログやユーザー報告を即時に監視し、想定外の障害が出たら速やかにロールバックします。
6. ロールバックと文書化
問題が出た場合に備えてロールバック手順を用意します。アップデートの手順、修正箇所、テスト結果を文書化して次回に備えます。
