E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

WordPress から移行する

このページ

EmDash の管理画面を使って、WordPress サイトの分析、互換性のあるコレクションの準備、コンテンツのインポート、メディアのコピー、URL の書き換えを行います。インポートしたサイトが検証に合格するまでは、WordPress サイトを利用可能な状態に保ってください。

始める前に

次の項目を準備してください。

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

現在のパーマリンク構造、正規のオリジン、リダイレクト、メニュー、有効な投稿タイプ、タクソノミー、そして新しいサイトで保持する必要があるプラグイン所有のフィールドを記録しておきます。

インポート方法を選ぶ

方法使用する場面含まれるデータ
WXR アップロードTools → Export からエクスポートできる場合エクスポートに含まれるデータ。投稿、固定ページ、カスタム投稿タイプ、タクソノミーのターム、再利用ブロック、著者、添付ファイルの URL を含みます
EmDash ExporterWordPress サイトを管理しており、Exporter をインストールできる場合認証が必要なコンテンツに加えて、対応しているサイト設定、SEO フィールド、タクソノミー、メディアのメタデータ。Exporter 1.2.0 以降ではコメント、メニュー、ロゴ、ファビコンも対象

Exporter なしでサイトの URL を入力した場合は、公開されている WordPress REST API を確認するだけです。この確認では WordPress の検出と、公開されている投稿・固定ページ・メディアの件数取得はできますが、REST による直接インポートは実行できません。

WXR ファイルをエクスポートする

WordPress で Tools → Export を開き、All content を選択して、XML のエクスポートファイルをダウンロードします。WXR ファイルは WordPress オリジン上のメディアを指しており、添付ファイルのバイトデータは含まれません。

EmDash Exporter に接続する

WordPress の Plugins 画面で Exporter のバージョンを確認します。コメント、メニュー、ロゴ、ファビコンには Exporter 1.2.0 以降が必要です。それより前のバージョンでは、これらを含めずにインポートが完了し、欠落として報告されません。

Exporter 1.2.0 以降では、WordPress で Tools → EmDash Migration を開き、マイグレーションキーを生成します。そのキーを EmDash のインポートページに貼り付けます。

どのバージョンの Exporter でも、WordPress サイトの URL を入力できます。Exporter が検出されたら、WordPress のアプリケーションパスワード画面から EmDash を認可します。ローカルの HTTP 開発サイトでは、認可コールバックに HTTPS が必要なため、WordPress のユーザー名とアプリケーションパスワードを手動で入力してください。

管理画面からインポートする

  1. 管理画面のサイドバーで Import を選択して Import from WordPress ページを開くか、/_emdash/admin/import/wordpress に直接アクセスします。

  2. WXR ファイルをアップロードするか、Exporter のマイグレーションキーを貼り付けるか、WordPress の URL を入力します。

  3. 分析結果を確認します。WordPress の各投稿タイプについて、対象のコレクション、必須フィールド、既存フィールドとの互換性を確認します。

  4. WordPress の著者を EmDash のユーザーに対応付けます。対応付けされていないソースの著者はゲストの byline として表現できるため、表示上のクレジットは EmDash のログイン権限を付与するかどうかに左右されません。

  5. Exporter を使ったインポートでは、メニュー、サイトタイトルとキャッチフレーズ、ロゴと favicon、対応している SEO の値をインポートするかどうかを選択します。これらのスイッチは WXR の経路には含まれません。

  6. インポートを開始します。EmDash は、エントリーを作成する前に、不足している互換性のあるコレクションとフィールドを作成します。

  7. 添付ファイルが見つかった場合は、メディアのステップを実行します。EmDash はソースのバイトデータをダウンロードし、設定されたストレージアダプター経由で保存し、一致するコンテンツ内の URL を書き換えます。

変換の動作

ステータス

インポーターは WordPress のステータスを次のように対応付けます。

WordPressEmDash
publishpublished
draftdraft
pendingdraft
privatedraft
future、trash、または不明なステータスdraft

予約された日時や WordPress の公開範囲のルールは、これらのステータスから再構築されません。公開する前に、インポートしたすべての下書きを確認してください。

リッチテキストと再利用ブロック

Gutenberg のマークアップは Portable Text に変換されます。クラシック HTML も同じコンバーターで処理されます。複雑なブロック、埋め込み、ショートコード、ページビルダーのマークアップ、プラグインが定義したブロックは、レンダリングされた EmDash サイトで確認してください。

WordPress がサーバー側でレンダリングするブロック（Latest Posts やプラグインのブロックなど）には、保存されたマークアップがありません。これらは、元のブロックコメントを含む HTML ブロックとしてインポートされます。例: <!-- wp:latest-posts {"postsToShow":3} /-->。これらのブロックはサイト上では何も表示されません。エディターでそのブロックの HTML タブを開いて元の内容を確認し、作り直すか削除してください。

WXR の wp_block エントリーはセクションとしてインポートされます。通常のコンテンツコレクションにはインポートされません。

コレクションとフィールド

投稿タイプの既定の対応付けには、post から posts、page から pages があります。カスタム投稿タイプには、サニタイズされたコレクションの slug が使われます。準備ステップでは、分析で必要となる標準のタイトル、Portable Text のコンテンツ、抜粋、アイキャッチ画像のフィールドが追加されます。

互換性のある型の既存フィールドは再利用されます。型が一致しない場合、そのコレクションの対応付けはブロックされます。インポーターは、既存のフィールドを別の型に強制変換することはありません。

カスタムフィールドと SEO データ

WXR の分析では、内部用ではない投稿メタのキーが報告され、フィールド名と型が提案されますが、WXR のデータベースインポートでは、任意のメタキーをすべてコピーするのではなく、標準のインポート対象フィールドが書き込まれます。この分析は、個別の変換が必要になる可能性があるフィールドのチェックリストとして扱ってください。

EmDash Exporter の経路では、対象のコレクションに一致するフィールドがあれば、カスタムメタと Advanced Custom Fields (ACF) の値をコピーできます。ACF のフィールドグループに「Post Type is equal to」の位置ルールがある場合、分析はそのグループ内のすべての ACF フィールドに対してフィールドを提案します。テキスト、数値、真偽値のフィールドは対応する型になり、select、checkbox、repeater、group、relationship など、リストやオブジェクトを保持できるフィールドは JSON フィールドになります。他の位置ルールで割り当てられたグループのフィールドは、Exporter が報告するメタキーからのみ提案されます。以前のインポートがメタキーからフィールドを作成したコレクションはそれらを保持するため、リピーターは行とサブフィールドごとに 1 つのフィールドとして取り込まれます。JSON 値は WordPress の形を保ちます。relationship、post object、user、taxonomy の各フィールドは、EmDash のエントリーではなく WordPress の ID で WordPress の投稿、ユーザー、タームを指し、画像、ファイル、ギャラリーの各フィールドは、インポートされた EmDash のメディアではなく WordPress のメディアファイルを指します。複数の投稿に保存された ACF グループのサブフィールドが、グループの JSON フィールドの横に別々のフィールドとして現れることもあります。テンプレートで使うほうを残してください。これらの値は、テンプレートで使う前に確認してください。

Exporter の経路では、対応するインポートスイッチが有効な場合、サポートされているアイキャッチ画像と、Yoast または Rank Math の SEO フィールドを作成して値を入力することもできます。

著者と Byline

対応付けされた WordPress の著者がエントリーの所有者になります。表示上のクレジットには byline が使われます。ユーザーの対応付けがない場合、EmDash は WordPress の著者情報に基づいてゲストの byline を作成するか、既存のものを再利用します。

タクソノミー

カテゴリーとタグは、対応する EmDash のタクソノミー定義にインポートされます。Exporter の経路では、カスタムタクソノミーの定義を作成できます。一致する EmDash の定義がない WXR のカスタムタクソノミーは、不足として報告され、その割り当てはスキップされます。

メディア

メディアの重複排除では、ダウンロードしたバイトデータの SHA-1 ハッシュを比較します。同じハッシュを持つ既存のメディア行が再利用されます。ファイル名や WordPress の ID は重複排除のキーではありません。

EmDash が添付ファイルをダウンロードしている間、ソースサイトに到達できる状態を維持する必要があります。添付ファイルの URL からのリダイレクトは、追跡する前に検証されます。

部分的なインポートを再試行する

管理画面からのインポートは既存のエントリーをスキップするように設計されていますが、その照合の境界を理解しておくことが重要です。

  • 既存のコンテンツは、WordPress の ID ではなく、コレクション、slug、ロケールで照合されます。
  • 試行の間にソースの slug が変更された場合は、両方のエントリーを確認し、重複を手動で解消してください。
  • メディアのステップを再実行すると、すでに保存されているバイト単位で同一のファイルが、コンテンツのハッシュによって再利用されます。
  • Exporter のフローは、サイズが制限されたチャンクで送信します。ブラウザーのフローを再起動すると、コンテンツのページが再実行され、スキップされたエントリーからリレーションのマップが再構築されます。

管理画面は WXR の再開用ファイルを保持しません。emdash import wordpress の --resume フラグは、変換済みの JSON ファイルをディスクに書き込む別の CLI ワークフローのものであり、管理画面のデータベースインポートを再開するものではありません。

切り替え前に検証する

インポートしたサイトをソースと照合します。

  • 投稿タイプとステータスごとにエントリー数を数えます。
  • Gutenberg、クラシックエディター、ショートコード、ページビルダーの代表的なコンテンツを開きます。
  • アイキャッチ画像とインラインのメディアが EmDash の URL から解決されることを確認します。
  • 著者、byline、カテゴリー、タグ、カスタムタクソノミー、翻訳を確認します。
  • Exporter でインポートした場合は、メニュー、コメント、サイトのアイデンティティ、SEO フィールドをテストします。
  • 以前の公開 URL をクロールし、変更されたすべてのルートにリダイレクトを用意します。
  • ログインしていない訪問者が下書きにアクセスできないことを確認します。

新しいサイトが本番環境で問題なく稼働し、ロールバックが不要になるまで、バックアップと WordPress のデプロイメントを保持してください。

トラブルシューティング

XML ファイルを解析できない

Tools → Export からファイルを再度エクスポートし、ダウンロードが完了したことを確認してください。エンコーディングを変更するツールで XML を編集しないでください。

コレクションが非互換とマークされる

既存のフィールドの slug は同じですが、型が異なります。再試行する前に、投稿タイプのマッピングを変更するか、Content Types でフィールドを調整してください。準備ステップは不足しているフィールドを追加しますが、既存のフィールドの型は変更しません。

ボット対策が Exporter をブロックする

Cloudflare のボット対策が、Exporter API ではなくチャレンジページで EmDash のリクエストに応答することがあります。その場合、EmDash はボット対策が接続をブロックしたと報告します。マイグレーションの間は、Exporter のリクエストを通すようにしてください。

  • Super Bot Fight Mode やその他の Cloudflare WAF 機能を使っている場合は、Skip アクションのカスタムルールを追加し、チャレンジを発行するルールより上に配置します。All Super Bot Fight Mode rules を選択し、ゾーンが I’m Under Attack モードを使っている場合は Security Level も選択します。次の式は、きれいなパーマリンクの有無にかかわらず、サブディレクトリにインストールされた WordPress も含めて Exporter API に一致し、EmDash がダウンロードするメディアファイルにも一致します。

    (http.request.uri.path contains "/wp-json/emdash/v1/")
or (http.request.uri.query contains "rest_route=%2Femdash%2Fv1%2F")
or (http.request.uri.path contains "/wp-content/uploads/")

  • Cloudflare Free プランの Bot Fight Mode は、ルールでスキップできません。マイグレーションの間はオフにし、終わったらオンに戻してください。

メディアの URL をダウンロードできない

ソースの添付ファイルが WordPress のセッションなしで到達できることを確認してください。認証の背後にあるメディア、削除されたファイル、プライベートネットワークアドレスへのリダイレクトは個別に失敗し、メディアのエラー一覧に残ります。

テーマを適応させる

アーカイブのルートには getEmDashCollection() を、slug のルートには getEmDashEntry() を使用します。entry.id はルートの識別子で、通常は slug です。entry.data.id は、リレーションのヘルパーが使用する、保存されているコンテンツ ID です。

次のルートは、インポートした投稿をレンダリングします。

---
import { decodeSlug, getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: post, error } = await getEmDashEntry("posts", slug);
if (error) return new Response("Could not load the post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>

ルートとコンポーネントのマッピングについては WordPress テーマを移植する を、エンドポイントの仕様と正確な再試行の境界については コンテンツインポート を参照してください。