ものしり

第3部 運用と移行

第11章 WordPress からの移行

WordPress から移すための判断、手順、検証を学ぶ。

読了の目安 約 40 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)

この章で学ぶこと

  • WordPress から EmDash へ移行すべきかどうかを、何を基準に判断するか
  • 移行前に棚卸ししておくべき項目と、その確認方法
  • EmDash 標準のインポート機能 (WXR アップロード / EmDash Exporter) が何を移し、何を移さないか
  • メディア、URL、リダイレクト、プラグイン機能、テーマをどう移すか
  • 本番切り替え前の検証、切り替え手順、ロールバックの考え方

この章の基準は EmDash 1.3.1 (確認日 2026-10-29) です。インポート機能の仕様は公式ドキュメントに基づいて書きます。公式資料に書かれていない一般的な WordPress 移行の注意は、「一般論」と明記して区別します。

1. 移行の全体像と判断

なぜ「移行すべきか」から考えるのか

移行は、記事を移すだけの作業ではありません。WordPress は、投稿、テーマ、プラグイン、wp-admin、PHP の書き換えルール (rewrite rules) までを一体で提供してきました。EmDash は Astro のサイトに CMS が組み込まれた構成で、コードとデータが別々にデプロイされます。そのため、移行では「データ」「見た目」「機能」「URL」の四つを別々に移す必要があります。

公式ドキュメントも、インポートが担当するのはコンテンツ (と一部の設定) であり、テーマは Astro プロジェクトとして作り直す、と明確に分けています。テーマは PHP のテーマとして読み込まれるのではなく、EmDash のクエリとシード (seed) ファイルを含む完全な Astro プロジェクトになります。

図 11-1 に示すように、移行は棚卸しから切り替えまでを順に進め、見た目と機能は別に作り直します。

図 11-1: WordPress 移行の全体フロー

移行すべきか、しないか

以下は一般論であり、公式の判断基準ではありません。公式が示しているのは「何が移るか」「何が移らないか」であり、移行の是非ではありません。

移行に向いているケース:

  • 記事とページが中心で、プラグイン依存が少ない。
  • すでに Astro や Cloudflare で運用しており、フロントエンドを自由に作りたい。
  • テーマの改修や PHP のメンテナンスが負担になっている。

慎重になるべきケース:

  • WooCommerce のような商取引機能が中核にある。公式のテーマ移植の資料も、商取引の挙動 (商品、カート、決済、注文) は別のアプリケーション統合として扱うよう述べています。表示用ファイルを移植しても、これらの意味は置き換わりません。
  • ページビルダーで組んだページが大量にある。ビルダー固有のショートコードや JSON は、Portable Text への意図的な変換か、ページテンプレートの再設計が必要になります。
  • WPML や Polylang の多言語構造を保ちたい。WXR にはその構造が含まれません (後述)。
  • 編集者が wp-admin の操作に強く依存している。EmDash の管理画面は wp-admin の見た目の複製ではなく、Gutenberg のブロックは Portable Text になります。

2. 事前棚卸しチェックリスト

なぜ棚卸しが先か

インポートの結果は、「何が移り、何が移らないか」が事前にわかっていれば手戻りが減ります。公式の手順も、移行前に現在のパーマリンク構造、正規のオリジン (canonical origin)、リダイレクト、メニュー、有効な投稿タイプ、タクソノミー、移行後も保持したいプラグイン所有のフィールドを記録するよう求めています。

準備するもの

公式が挙げている前提は次のとおりです。

  • WordPress の DB と wp-content/uploads のバックアップ
  • メディアをコピーする場合は、ストレージを設定した EmDash サイト
  • EmDash の管理者アカウント (インポートには import:execute 権限が必要)
  • 完全な WXR エクスポート、または WordPress 側に入れた EmDash Exporter プラグイン

棚卸し表

次の表を実際に埋めてから着手することをお勧めします。右端の「EmDash での受け皿」は、この章の各節で詳しく説明します。

項目 確認すること EmDash での受け皿
投稿タイプ 有効な投稿タイプ、各件数、公開状態の内訳 コレクション (post は posts、page は pages、カスタムは正規化したスラッグ)
カスタムフィールド post meta、ACF のフィールドグループ コレクションのフィールド。WXR では自動コピーされない (節3)
プラグイン依存 有効プラグインごとに、データ・出力・管理画面のどれを担っているか 節6
ショートコード 使われているショートコードの種類と件数 Portable Text のカスタムブロック (節7)
メディア 総容量、件数、アップロード外にある参照 メディアライブラリ (節4)
URL 構造 パーマリンク設定、カテゴリ付き URL、ページ階層 ルートファイルとコレクションの urlPattern (節5)
リダイレクト 既存のリダイレクトルール (プラグイン管理を含む) 管理画面の Redirects、シードの redirects
フォーム 問い合わせフォームなどの送信先と通知先 資料に記載なし。自前実装やプラグイン
多言語 多言語プラグインの有無と方式 Astro の i18n と行ごとのロケール (節3)
SEO プラグイン Yoast、Rank Math の利用 Exporter 経由で SEO フィールドに取り込み可。表示はテンプレート側
ユーザー 著者数、権限、公開表示に使う名前 EmDash ユーザーまたはゲスト署名 (byline)

項目ごとの注意

投稿タイプ: 内部用の投稿タイプはインポート対象から除外されます。WXR の再利用ブロック (wp_block) は通常のコンテンツではなく「セクション」として取り込まれます。

カスタムフィールド: 公式は、WXR の分析が非内部の post meta キーを報告しフィールド名と型を提案するものの、WXR のデータベースインポートは標準のインポート用フィールドを書き込むだけで、任意の meta キーを全部コピーはしない、と述べています。つまり、WXR で出る meta 一覧は「別途変換が必要かもしれないもの」のチェックリストとして使います。

ユーザー: 著者は EmDash ユーザーにマッピングできます。マッピングされない著者は、WordPress 側の著者情報に基づいてゲスト署名として作成または再利用されます。署名表示のために EmDash のログイン権限を与える必要はありません。

SEO プラグイン: Exporter 経路では、Yoast や Rank Math の SEO タイトルと説明を、対象コレクションの「SEO Title」「SEO Description」フィールドへ取り込めます。これらは通常のコンテンツフィールドであり、SEO パネルとは別物です。ページテンプレートで出力しない限り表示されません。

3. インポート機能の使い方と対応表

インポート元の種類

EmDash の管理画面の Import (/_emdash/admin/import/wordpress) には、三つのソースがあります。

ソース ID 入力 取り込み 備考
wxr Tools → Export で作った XML あり エクスポートに含まれるデータのみ
wordpress-plugin サイト URL と EmDash Exporter の認証情報 (またはマイグレーションキー) あり 認証が必要な内容も取得できる
wordpress-rest 公開サイト URL なし 検出と公開件数の確認だけ

重要な制限が三つあります。

  1. URL を入れるだけの方法 (Exporter なし) は、公開 REST API を探る「プローブ」にとどまります。WordPress の検出と公開された投稿・ページ・メディアの件数は分かりますが、直接インポートはできません。
  2. wordpress-com という OAuth 型のインポートソースはありません。WordPress.com のサイトも WXR か、互換のある Exporter 接続を使います。
  3. WXR は添付ファイルの URL とメタデータを持つだけで、メディアの実体 (バイト列) は含みません。

WXR と Exporter の使い分け

観点 WXR EmDash Exporter
導入の手間 WordPress 標準機能のみ WordPress にプラグインを入れる
下書き等の認証が必要なデータ エクスポートに含まれる範囲 取得可能
カスタム meta / ACF 自動コピーなし (提案のみ) 対象コレクションに同名フィールドがあればコピー可
Yoast / Rank Math の SEO 値 なし フィールドとして作成・取り込み可 (切替あり)
サイト設定 (タイトル、キャッチフレーズ) なし 取り込み可
コメント、メニュー、ロゴ、ファビコン なし Exporter 1.2.0 以降で可
カスタムタクソノミー 対応する定義がなければ報告されて割り当てはスキップ 定義を作成できる

Exporter が 1.2.0 より古い場合、コメント、メニュー、ロゴ、ファビコンは何も報告されずに取り込まれません。必ず WordPress の Plugins 画面でバージョンを確認してください。1.2.0 以降では Tools → EmDash Migration でマイグレーションキーを発行し、EmDash のインポート画面に貼り付けます。どのバージョンでも、サイト URL を入れて WordPress のアプリケーションパスワード画面で承認する方法があります。ローカルの HTTP 開発サイトでは、コールバックが HTTPS を要求するため、ユーザー名とアプリケーションパスワードを手入力します。

セキュリティ: Exporter は emdash/v1 の API エンドポイント経由でデータを送り、EmDash に DB への直接アクセスを与えません。それでも認証情報 (アプリケーションパスワード、マイグレーションキー) は移行期間だけの用途と考え、終わったら失効させ、Exporter プラグインも無効化または削除してください。これは一般論としての運用上の推奨で、公式資料には失効手順の記載がありません。

管理画面での手順

公式の流れは次のとおりです。

  1. Connect: WXR をアップロードする、マイグレーションキーを貼る、または URL を入力する。
  2. Analyze: 投稿タイプ、必須フィールド、著者、添付、スキーマ互換性を読み取る。
  3. Review: 投稿タイプごとの対象コレクション、著者マッピング、追加項目を選ぶ。
  4. Prepare: 足りないコレクションとフィールドを作る。
  5. Import: 変換してエントリを作る。
  6. Copy media: 添付ファイルをダウンロードし、一致する URL を書き換える。

管理画面の「インポート」を開くと、WordPress からのインポートの画面になります(画面 11-1)。移行キーの貼り付け、サイトの URL の入力、ファイルのアップロードのいずれかで始めます。

画面 11-1: WordPress からのインポート画面(接続・確認・インポートの3段階)

図 11-2 に示すように、取り込めるインポート元は WXR と EmDash Exporter で、URL だけの方法は検出と件数確認にとどまります。

図 11-2: インポート元の三種類と管理画面の六つの手順

Exporter 経路だけ、メニュー、サイトタイトルとキャッチフレーズ、ロゴとファビコン、対応する SEO 値を取り込むかどうかの切替があります。WXR 経路には、この切替はありません。

レビュー画面では、投稿タイプごとにスキーマの状態が表示されます。

状態 意味
Ready コレクションと必須フィールドがすでに互換
New collection Prepare でコレクションと必須フィールドを作る
Add fields コレクションは存在し、足りないフィールドを足す
Incompatible 同名で型が違うフィールドがある。マッピングかスキーマを直す

Prepare は追加のみで、既存フィールドの型を変えて合わせることはしません。Incompatible のときは、対象コレクションを変えるか、Content Types でフィールドを整理してから再試行します。

変換の対応表: 何がそのまま移り、何が手作業か

対象 結果 手作業の要否
投稿・ページ・カスタム投稿タイプの本文 Gutenberg マークアップも古典的 HTML も同じ変換器で Portable Text になる 複雑なブロック、埋め込み、ショートコード、ビルダー出力は表示を目視確認
publish published 不要
draft / pending / private / future / trash / 不明 すべて draft 予約日時や非公開などの意味は再現されない。全件確認が必要
サーバー側描画ブロック (Latest Posts、プラグイン由来) 元のブロックコメントを含む HTML ブロックとして取り込まれる 画面には何も出ない。再構築するか削除する
再利用ブロック (wp_block) セクション 使用箇所の確認
スラッグ WordPress のスラッグがそのまま EmDash のスラッグになる 不要
ID EmDash が独自に採番 WordPress の ID に依存した処理は作り直し
カテゴリ・タグ 一致するタクソノミー定義へ取り込み 定義の確認
カスタムタクソノミー WXR は定義がなければ報告されてスキップ。Exporter は定義を作れる WXR の場合は先に定義を作る
著者 マッピングすればエントリの所有者。なければゲスト署名 マッピング設定
任意の meta (WXR) 標準フィールド以外は自動コピーされない 別途変換
任意の meta・ACF (Exporter) 対象コレクションに同名フィールドがあればコピー フィールドを事前に用意し、内容を確認
注目画像・SEO (Exporter) 切替を有効にすれば作成・取り込み SEO 値はテンプレートで出力
メディア本体 メディア手順でダウンロードして保存 WordPress を稼働させたままコピーを実施
多言語 (WPML / Polylang) ロケールと翻訳グループは引き継がれず、既定ロケールに入る 翻訳エントリを後から作成して結び付ける

図 11-3 に、上の対応表を「そのまま移るもの」と「手作業・確認が必要なもの」に分けて示します。

図 11-3: インポートで、そのまま移るものと手作業が必要なもの

ACF の取り扱いには細かい癖があります。公式によれば、「投稿タイプが等しい」という位置ルールを持つ ACF フィールドグループでは、グループ内の全フィールドについてフィールドが提案されます。テキスト、数値、真偽値は対応する型になり、選択、チェックボックス、リピーター、グループ、リレーションなど、リストやオブジェクトを持ちうるものは JSON フィールドになります。JSON の中身は WordPress の形のままで、リレーション、投稿オブジェクト、ユーザー、タクソノミーのフィールドは EmDash のエントリではなく WordPress の ID を指します。画像、ファイル、ギャラリーも、取り込み済みの EmDash メディアではなく WordPress のメディアファイルを指します。テンプレートで使う前に、必ず値を確認し、必要なら ID の対応づけを自前で行ってください。

多言語の扱い

EmDash は「ロケールごとに1行」のモデルです。翻訳ごとに独立した ID、スラッグ、状態、リビジョンを持ち、translation_group で結び付きます。WXR には WPML や Polylang が付けるロケールと翻訳グループの構造が含まれないため、インポートされた内容は既定ロケールに入ります。翻訳を作るには、翻訳エントリを下書きで作り、元エントリのデータベース ID に結び付けます。

emdash content create posts \
  --locale fr \
  --translation-of 01ABC... \
  --slug mon-article \
  --data '{"title":"Mon article"}' \
  --draft

Astro 側の設定にも注意が必要です。i18n ブロックを入れると多言語機能が有効になりますが、既定ロケールに接頭辞を付けるルーティング (prefixDefaultLocale: true や "prefix-always") は、/_emdash/admin が 404 になるため使えません。既定の prefix-other-locales を使います。日本語が既定ロケールで URL に /ja/ を付けたい場合は、サイトの手前でリダイレクトか書き換えを行います。公式は英語の例 (/ から /en/) で案内しており、日本語の /ja/ への当てはめは筆者の読み替えです。

注意: 多言語サイトを移行する場合、既定ロケールとフォールバックの設計は、インポート前に決めておく必要があります。EmDash の単一エントリ取得はフォールバックチェーンをたどりますが、一覧取得はロケールごとの結果のみを返します。

部分的に失敗したときの再実行

管理画面のインポートは、既存エントリのスキップを前提にしています。ただし判定の境界を理解しておく必要があります。

  • 既存エントリの一致判定は、コレクション、スラッグ、ロケールの組で行います。WordPress の ID では判定しません。
  • 再実行の間にスラッグを変えると、別のエントリとして作られることがあります。重複は手作業で解消します。
  • メディアの再実行は、バイト列が同じファイルを再利用するので安全です。
  • 管理画面は WXR の再開用ファイルを永続化しません。CLI の emdash import wordpress の --resume は、変換した JSON をディスクに書き出す別のワークフローのためのもので、管理画面の DB インポートを再開するものではありません。

Exporter の流れは Worker の制限に収めるため小さなチャンクで送られます。ブラウザが状態を失った場合は、最初からやり直します。スキップされたエントリから関係マップが再構築されます。

落とし穴

  • Cloudflare のボット対策が Exporter への通信をチャレンジページで遮ることがあります。その場合、EmDash は「ボット保護に遮られた」と報告します。Super Bot Fight Mode などを使っている場合は、移行期間だけ、/wp-json/emdash/v1/ や /wp-content/uploads/ へのリクエストを Skip する WAF カスタムルールを、チャレンジを出すルールより上に置きます。Free プランの Bot Fight Mode はルールでスキップできないため、移行中だけオフにします。

4. メディア移行

なぜ別の手順なのか

WXR にはメディアの実体がないため、メディアは別のステップで移します。公式の手順では、EmDash が添付ファイルの URL をダウンロードし、設定済みのストレージアダプターに保存し、本文中の一致する URL を書き換えます。このため、移行が終わるまで WordPress のオリジンを到達可能にしておく必要があります。

仕組みと制限

  • 重複排除は、ダウンロードしたバイト列の SHA-1 ハッシュで行います (sha1: 接頭辞付きで保存)。ファイル名や WordPress の ID は判定に使いません。同じバイト列なら、URL が違っても既存のメディア行を再利用します。このハッシュはセキュリティ署名ではなく重複排除のキーです。
  • URL の書き換えは、Portable Text、テキスト、文字列、画像、ファイルの各フィールドが対象です。
  • 認証の裏にあるメディア、削除済みファイル、プライベートアドレスへのリダイレクトは、個別に失敗し、メディアのエラー一覧に残ります。リダイレクトは辿る前に検証されます。
  • 最終結果に失敗した URL が列挙されます。アクセス可能にしてから再実行すれば、完了済みのファイルは再利用されます。

保存先の選択

EmDash では、保存先をストレージアダプターで選びます。Cloudflare Workers で動かすなら R2 バインディング、Node.js ならローカルディスクまたは S3 互換です。重要なのは、データベースのバックアップにはメディアのメタデータしか含まれず、実体は含まれないことです。ストレージは別にバックアップしてください。

メディアライブラリの既定の制限も確認します。

  • 既定で受け付けるのは PNG、JPEG、GIF、WebP、AVIF、一般的な動画・音声形式、PDF です。SVG は、動作するコードを含みうるため既定では除外されます。
  • 1ファイルの既定上限は 50 MB です (maxUploadSize で変更可)。
  • 画像・ファイルフィールドに独自の許可 MIME タイプリストを設定でき、保存時にサーバー側で再検査されます。

大きな動画や SVG を多く含むサイトは、この既定値に引っかからないか、事前に確認してください。

5. URL とリダイレクト

なぜ重要か

URL が変わると、検索流入と外部からのリンクが失われます。WordPress は rewrite rules で URL を決めていましたが、Astro ではルートが明示的なファイルになるため、URL 構造は自分で設計します。公式の移植資料も、コンテンツタイプごとに新しい URL を決め、変更した全パーマリンクについて切り替え前にリダイレクトを用意するよう述べています。

URL を決める

公式のブログテンプレートでは、次の対応になっています。

WordPress EmDash テンプレート
single.php src/pages/posts/[slug].astro
archive.php src/pages/posts/index.astro
page.php src/pages/pages/[slug].astro
category.php src/pages/category/[slug].astro

スターターテンプレートはページに src/pages/[slug].astro を使うなど、テンプレートによって異なります。どちらかのルートモデルを選び、シードの urlPattern (たとえば /posts/{slug}) とリダイレクトを、ルートと一致させてください。urlPattern には、1つのパスセグメントにつき最大1つのプレースホルダーを置けます。

旧 URL を完全に維持するか、新 URL に整理してリダイレクトで繋ぐかは、設計上の選択です。維持できるなら、リダイレクトの数と検証の手間が減ります。

リダイレクトの管理

EmDash の管理画面 Redirects では、次のルールを扱えます。

  • 送り先へのリダイレクト: ステータス 301、302、307、308
  • 応答のみ: 410 Gone、451 Unavailable For Legal Reasons
  • 送り元に名前付きセグメント (/old/[slug]) とキャッチオール (/old-blog/[...path]) を使え、送り先で再利用できます。

加えて、公開済みエントリのスラッグを変えると、コレクションの URL パターンにもとづいて 301 が自動作成されます (翻訳などが同じスラッグを使っている間は作られません)。404 になったリクエストは記録され、404 Errors タブで頻度順に確認し、リダイレクトの追加や 410 の指定ができます。ログは最大 10,000 パスで、最も長く見られていないものから消えます。

シードの redirects でも定義できます。送り元と送り先は / で始まるローカルパスのみで、プロトコル相対 URL、パスのトラバーサル、改行は拒否されます。許可されるのは 301、302、307、308 です。

json title="seed/seed.json" { "version": "1", "redirects": [ { "source": "/old-path", "destination": "/new-path", "type": 301, "enabled": true, "groupName": "WordPress migration" } ] }

落とし穴

  • 外部ドメインへのリダイレクトは、シードでは定義できません (ローカルパスのみ)。
  • ドメイン自体を変える場合のリダイレクトは、EmDash ではなく、ホストまたは DNS で行います。公式の「ドメイン変更」の案内は、旧アドレスは、ホストから外すまで引き続きサイトを配信するため、新しいアドレスへ送るリダイレクトをホストか DNS プロバイダーに追加する、としています。
  • リダイレクト管理プラグインのルールを自動で取り込む機能は、公式のインポートには書かれていません。ルールを書き出し、管理画面かシードの redirects に変換して登録する必要があります (一般論)。

6. プラグイン機能の置き換え

まず「移植しない」判断をする

公式は、Astro や EmDash がすでに置き換えている WordPress の関心事のためのプラグインは、移植しないよう述べています。たとえば PHP のページキャッシュ、WordPress の書き換えルール、テーマのテンプレート選択、WordPress コアのグローバル変数の変更です。また、カスタム投稿タイプやフィールドを定義するだけで実行時の振る舞いがほとんどないプラグインは、プラグインではなく EmDash のコレクションとシードで置き換えます。

プラグイン移植の対象にふさわしいのは、コンテンツの検証、外部 API 呼び出し、バックグラウンド処理、独自の保存レコード、設定、管理ツールなど、WordPress コアから独立した振る舞いです。

棚卸しからの分類

分類 例 置き換え方
Astro / EmDash が代替 キャッシュ、書き換えルール、テンプレート選択 移植しない
データ定義のみ CPT / ACF の定義 コレクションとシード
SEO Yoast、Rank Math EmDash の SEO 機能、Exporter 経由の値、<EmDashHead>
リダイレクト リダイレクト管理 管理画面の Redirects、シード
独自ロジック 外部連携、検証、バックグラウンド処理 EmDash プラグイン (サンドボックス型またはネイティブ型)
フォーム フォームプラグイン 標準の置き換えは資料に記載なし。自前実装
商取引 WooCommerce 別のアプリケーション統合

サンドボックス型かネイティブ型か

要件 サンドボックス型 ネイティブ型
レジストリからのインストール 可 不可
分離された実行環境 可 (ランナーの設定が必要) 不可
フック、ルート、KV、構造化ストレージ 可 可
Block Kit の管理ページ 可 可
カスタム React 管理コンポーネント 不可 可
公開側の Astro コンポーネント 不可 可
生のページ断片 不可 可

ネイティブ型は、ネイティブ専用のビルド時またはユーザーインターフェースの機能が必要なときだけ選びます。ネイティブ型の移植は、ホストサイトのプロセス権限で動きます。機能宣言 (capabilities) は与えられる PluginContext を制限しますが、環境変数、直接のネットワーク呼び出し、イベントループからは分離されません。

セキュリティ: サンドボックス型でもネイティブ型でも、必要な機能 (capabilities) と許可するホスト (allowedHosts) は最小限に宣言してください。ネイティブ型を選ぶ前に、本当にネイティブ専用の機能が必要か確認してください。

WordPress の概念との対応

WordPress EmDash
register_activation_hook() plugin:install (初回導入) または plugin:activate (有効化)
register_uninstall_hook() plugin:uninstall
wp_insert_post_data content:beforeSave
save_post content:afterSave
before_delete_post content:beforeDelete
deleted_post content:afterDelete
wp_handle_upload_prefilter media:beforeUpload
add_attachment media:afterUpload
get_option / update_option ctx.settings (設定)、ctx.kv (小さな内部値)
カスタムテーブル ctx.storage.<collection> (インデックス宣言が必要)
REST ルート /_emdash/api/plugins/<plugin-id>/<route-name>

フックの名前だけでなく意図で対応づけてください。イベントの形は EmDash 側の型で決まっており、WordPress のコールバック引数とは異なります。エントリのデータを受け取るコンテンツフックには content:read が必要です。コンテンツの作成・更新・削除には content:write (読み取りも含む)、メディアには media:read / media:write、外部通信には network:request を宣言します。

保存に関する重要な点が三つあります。

  • 資格情報は、admin.settingsSchema で secret フィールドとして宣言すると暗号化されます。
  • 絞り込みや並べ替えに使うフィールドは、ストレージ宣言でインデックスにしておく必要があります (宣言のない項目での where や orderBy は使えません)。
  • プラグインのコードから EmDash の DB を直接開いたり、SQL を組み立てたりしないでください。

移植の進め方

公式の手順を要約します。

  1. フック、オプション、カスタムテーブル、cron、REST ルート、管理ページ、ブロック、ショートコード、外部ホストを棚卸しする。
  2. Astro やコンテンツモデル、デプロイ先が担う部分を取り除く。
  3. 形式を選び、必要な capabilities と allowed hosts を記録する。
  4. KV のキーと構造化ストレージを定義し、インデックスを追加する。
  5. 観察可能な振る舞いを一つずつ移植し、代表的なコンテンツと失敗ケースでテストする。
  6. 管理 UI は、基盤が動いてから足す。
  7. インストール、アップグレード、有効化、無効化、データ削除あり/なしのアンインストール、capability の変更をテストする。

7. テーマ移植

方針

公式は、テーマを「デザイン」「ルートのテンプレート」「データベースが管理する機能」に分けて移植するよう述べています。先に代表的なコンテンツをインポートしてから、テンプレートを変換します。

デザインの抽出対象は、style.css と読み込まれるスタイルシート、ブロックテーマなら theme.json、テンプレートのマークアップとパーツ、フォント・アイコン・画像 (ライセンス込み)、ブレークポイントと対話的な振る舞いです。デザイントークンは Astro の CSS に移し、共通の文書の骨格を src/layouts/Base.astro に作ります。WordPress が生成したクラス名や JavaScript は、新しいコンポーネントで必要がなければコピーしません。見た目と挙動を保ち、実装の残りかすは持ち込まない、という考え方です。

クエリの変換

WordPress EmDash
WP_Query getEmDashCollection()
get_post() getEmDashEntry()
the_content() <PortableText />
wp_nav_menu() getMenu()
サイドバー ウィジェットエリアと <WidgetArea />
オプション API サイト設定 (getSiteSettings())

並べ替えには orderBy を使います (sort や sortBy ではありません)。キーは保存されたフィールド名で、published_at、created_at、またはインデックスされたフィールドです。フィルタと並べ替えはクエリ側で行い、データベースに処理させます。

---
import { getEmDashCollection } from "emdash";

const { entries: posts, error } = await getEmDashCollection("posts", {
  orderBy: { published_at: "desc" },
  limit: 12,
});
if (error) return new Response("Could not load posts", { status: 500 });
---

識別子にも注意してください。post.id は Astro のルート識別子で、通常はスラッグです。post.data.id が保存されたコンテンツ ID で、コメント、タクソノミーのヘルパー、ビジュアル編集のコンテキストにはこちらを使います。

動的機能とショートコード

  • メニュー: シードで定義し、getMenu("primary") で取得します。編集後も並べ替えられるので、同じナビゲーションをハードコードしないでください。
  • ウィジェット: シードでエリアを定義し、<WidgetArea name="sidebar" /> で描画します。
  • サイト情報: タイトル、キャッチフレーズ、ロゴ、ファビコン、1ページあたりの投稿数は、title、tagline、logo、favicon、postsPerPage の各設定に対応します。
  • ページテンプレート: 複数のレイアウトを編集者に選ばせるなら、固定コンポーネントへ対応づけた select フィールドを pages コレクションに足します。保存された文字列を任意のインポートパスにはしないでください。
  • ショートコードとブロック: 内容を持つものは Portable Text の形に対応づけます。たとえばギャラリーは publication.gallery のような名前空間付きの _type にし、Gallery.astro を PortableText のコンポーネントマップで渡します。シードはカスタムブロックのデータを提供できますが、カスタムエディタは登録しません。パッケージ化された Astro レンダラーやカスタム React 編集 UI が必要なら、ネイティブプラグインを使います。

難しいテーマ

子テーマは親子を解決した出力を、ブロックテーマは theme.json と templates/*.html を元に移植します。ページビルダーのショートコードや独自 JSON は、Portable Text への意図的な変換かテンプレートの再設計が必要です。

8. 検証

なぜ検証を型にするのか

インポートの成否と、公開サイトの正しさは別の問題です。公式も、切り替え前に元サイトと突き合わせる項目を挙げています。

検証項目

公式のチェックに、一般論の補足を加えて整理します。

検証 方法
件数 投稿タイプ別・状態別に、WordPress と EmDash の件数を比較する
代表コンテンツ Gutenberg、クラシックエディタ、ショートコード、ページビルダーの記事を開いて見る
メディア 注目画像と本文中の画像が EmDash の URL で解決することを確認する
著者・分類 著者、署名、カテゴリ、タグ、カスタムタクソノミー、翻訳を確認する
付随機能 メニュー、コメント、サイト情報、SEO フィールド (Exporter 経由の場合) をテストする
旧 URL 旧サイトの公開 URL をクロールし、変更された全ルートにリダイレクトを用意する
下書きの非公開 ログアウト状態で下書きにアクセスできないことを確認する

下書き扱いに変換された非公開・予約・ゴミ箱の記事は、公開前に1件ずつ確認します。

リンク切れ巡回と差分比較 (一般論)

以下は公式資料にない、一般的な方法です。

  1. 旧サイトの sitemap や DB から、公開 URL の全リストを作る。
  2. 新サイトに対して全 URL にアクセスし、ステータスコード、最終的な遷移先、タイトルを記録する。
  3. 旧サイトでも同じ URL を取得し、ステータスとタイトルを比較する。
  4. 新サイトで 404 になるもの、旧サイトでも 404 だったものを分けて集計する。
  5. 本文中の画像・内部リンクを抽出して、同様に巡回する。
  6. 代表的な URL は、モバイル幅とデスクトップ幅の両方でスクリーンショットを撮って見比べる (公式のテーマ移植手順も、代表的な公開 URL をモバイルとデスクトップの幅で比較し、空のフィールド、長いタイトル、画像なし、下書き、404 をテストするよう述べています)。

9. 本番切り替えとロールバック

切り替え前の条件

次の条件を満たしてから進めてください。

  • 節8の検証が完了している。
  • リダイレクトが、変更された全ルートについて用意されている。
  • メディアのコピーが完了し、失敗リストが解消している (または許容できる)。
  • Exporter の認証情報を無効にする準備ができている。
  • WordPress の DB と wp-content/uploads のバックアップがある。

公式は、新サイトが本番で問題なく稼働し、ロールバックが不要になるまで、バックアップと WordPress のデプロイを保持するよう述べています。

手順の例

以下は一般論としての手順例で、公式資料が規定しているものではありません。

1. 凍結     WordPress の編集を止める (コンテンツの凍結日時を決める)
2. 差分     凍結後に更新された記事を再エクスポートし、差分だけ反映する
3. 検証     ステージングで節8の検証をやり直す
4. TTL      DNS の TTL を事前に短くしておく
5. 切替     DNS またはルーティングを EmDash 側へ向ける
6. 監視     404 ログ、リダイレクト、フォーム、検索流入を数日間見る
7. 後始末   Exporter の認証情報を失効し、WordPress の公開を段階的に閉じる

差分反映では、再実行時の判定に注意が必要です。インポートは (コレクション、スラッグ、ロケール) の組でスキップするため、既存エントリの更新内容は自動では反映されません。内容が更新された記事は、手作業での修正が必要になります (資料にスキップ以外の更新方法は書かれていません)。

ロールバック

切り替えを「いつでも戻せる」ものにするのが基本です。

  • 切り替えは DNS またはルーティングの向き先の変更に限り、WordPress 側を変更しないままにしておきます。戻すときは、向き先を戻すだけで済みます。
  • 切り替え後に EmDash 側で新しく作られたコンテンツ (コメント、フォーム送信、新規記事) は、WordPress に戻りません。ロールバックの判断をする時間枠を決め、その間に生じたデータの扱いを事前に決めておいてください。
  • EmDash のバックアップは別に取っておきます。データベースのバックアップにはメディアの実体が含まれないので、ストレージも別に保全します。
  • 移行期間中は、WordPress のオリジンを残します。メディアの URL が WordPress を指したままの記事があると、オリジンを止めたときに画像が壊れます。書き換え後に検証してから止めてください。

WordPress との違い

観点 WordPress EmDash
URL の決定 rewrite rules とテンプレート階層 src/pages/ のルートファイルと urlPattern
投稿タイプ / メタ 投稿タイプと post meta コレクションとフィールド
本文 Gutenberg / クラシック HTML Portable Text
多言語 WPML / Polylang 等 Astro の i18n と行ごとのロケール
機能拡張 PHP プラグイン サンドボックス型 / ネイティブ型プラグイン、または Astro 側の機能
デプロイ コードとデータが同居 コードとデータベースが別
リダイレクト プラグイン 管理画面の Redirects、シード

セキュリティ上の注意

  • 移行用の認証情報 (アプリケーションパスワード、マイグレーションキー) は、移行後に失効させる。
  • WAF のスキップルールは移行期間だけにする。
  • インポートのエンドポイントはスキーマ、コンテンツ、メディア、設定を作成するため、管理画面のワークフローを使うのが基本。統合する場合は、インストール済みの EmDash のバージョンでテストする。
  • ネイティブプラグインはホストのプロセス権限で動く。
  • メディアの削除は元に戻せないので、使用箇所の確認だけに頼って消さない。

まとめ

  • 移行は、データ、見た目、機能、URL を分けて考える。インポートは、そのうちのコンテンツの下ごしらえである。
  • インポート元は WXR と EmDash Exporter。URL だけの REST プローブは取り込みを行わない。WordPress.com 用の OAuth 取り込みもない。
  • 公開状態以外のステータスは、すべて下書きになる。サーバー側描画ブロックは中身が出ない。任意の meta (WXR)、多言語の構造、リレーションの ID は手作業になる。
  • メディアは別ステップで、WordPress が稼働している間にバイト列の SHA-1 で重複排除しながらコピーする。
  • URL は設計事項で、変更した全ルートにリダイレクトを用意する。管理画面、シード、自動の 301 を使える。
  • プラグインは、まず移植が不要なものを除き、残りをサンドボックス型かネイティブ型で作り直す。
  • テーマは Astro プロジェクトとして作り直す。ショートコードやブロックは Portable Text のカスタム _type に対応づける。
  • 切り替えは戻せる形で行い、検証が済むまで WordPress とバックアップを残す。

理解度チェック

  1. URL だけを入力して WordPress サイトを検出した場合、EmDash は何をしますか。直接インポートは可能ですか。
  2. WordPress の private と future の投稿は、インポート後にどの状態になりますか。公開前に何をすべきですか。
  3. WXR インポートと EmDash Exporter では、カスタム meta・ACF の扱いはどう違いますか。ACF のリレーションフィールドを JSON で取り込んだ場合、その値は何を指していますか。
  4. インポートを途中で中断して再実行したとき、既存エントリはどのように判定されますか。再実行の間にスラッグを変えるとどうなりますか。
  5. WPML でインポート元に翻訳があった場合、WXR で取り込むと翻訳はどうなりますか。取り込み後に翻訳を結び付けるには何を使いますか。
  6. 本番切り替え後にロールバックを可能にしておくために、何を残し、どのような点を事前に決めますか。

答え

  1. WordPress の検出と、公開された投稿・ページ・メディアの件数の確認だけを行います。直接インポートはできません。WXR をアップロードするか、EmDash Exporter を入れて再度プローブします。
  2. どちらも draft になります。非公開や予約の意味は再現されないので、公開前に全件を確認します。
  3. WXR は meta キーを報告して提案するだけで、標準フィールド以外の meta を自動コピーしません。Exporter は、対象コレクションに同名のフィールドがあればカスタム meta と ACF の値をコピーできます。ACF のリレーションなどを JSON で取り込むと、EmDash のエントリではなく、WordPress の投稿・ユーザー・用語の ID を指します。
  4. コレクション、スラッグ、ロケールの組で判定します。WordPress の ID では判定しません。再実行の間にスラッグが変わると別のエントリとして作られることがあるため、重複を手作業で確認して解消します。
  5. WXR にはロケールと翻訳グループの構造が含まれないため、既定ロケールに入ります。取り込み後に、emdash content create の --locale と --translation-of (または API の locale と translationOf) で翻訳を作り、元のデータベース ID に結び付けます。
  6. WordPress のデプロイ、DB と uploads のバックアップ、メディアのオリジンを残します。EmDash 側のデータベースとストレージも別にバックアップします。また、切り替え後に EmDash 側で生じた新規データ (コメント、フォーム送信、新規記事) の扱いと、判断の期間を事前に決めます。

出典

公式ドキュメントのパスは sources/emdash-docs/ 以下のものです。公開 URL は公式ドキュメントサイトの対応するページです。

  • 節1〜3、9: Migrate from WordPress (migration/from-wordpress.mdx) https://docs.emdashcms.com/migration/from-wordpress/
  • 節3: Content import (migration/content-import.mdx) https://docs.emdashcms.com/migration/content-import/
  • 節1、7: EmDash for WordPress Developers (coming-from/wordpress.mdx) https://docs.emdashcms.com/coming-from/wordpress/
  • 節3 (多言語): Internationalization (guides/internationalization.mdx) https://docs.emdashcms.com/guides/internationalization/
  • 節4: Media Library (guides/media-library.mdx) https://docs.emdashcms.com/guides/media-library/
  • 節4: Choose media storage (deployment/storage.mdx) https://docs.emdashcms.com/deployment/storage/
  • 節5: SEO の Redirects and the 404 log (guides/seo.mdx) https://docs.emdashcms.com/guides/seo/
  • 節5: Seed files の Redirects (themes/seed-files.mdx) https://docs.emdashcms.com/themes/seed-files/
  • 節5: Change domain (guides/change-domain.mdx) https://docs.emdashcms.com/guides/change-domain/
  • 節6: Port WordPress Plugins (migration/porting-plugins.mdx) https://docs.emdashcms.com/migration/porting-plugins/
  • 節7: Port a WordPress Theme (themes/porting-wp-themes.mdx) https://docs.emdashcms.com/themes/porting-wp-themes/