EmDash情報局

検索

相談する

WordPressからの移行

このページで分かること

  • 移行前に用意するもの（WordPressのバックアップ、ストレージ、import:execute 権限、WXRファイルまたはEmDash Exporter）と、2つのインポート方法の違い
  • 管理画面でのインポートの手順と、公開状態・本文・コレクション・カスタムフィールド・投稿者・タクソノミー・メディアの変換のされ方
  • 途中で止まったときのやり直し方、切り替える前の確認項目、テーマの対応
難易度
実践
読む時間
7分
前提知識
CMSとは／WordPress開発者のためのEmDash
このページの目次

EmDashの管理画面を使って、WordPressのサイトを分析し、互換性のあるコレクションを準備し、コンテンツをインポートし、メディアをコピーし、URLを書き換えます。インポートしたサイトが確認に通るまで、WordPressのサイトは使える状態のままにしておきます。

始める前に

次のものを用意します。

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

現在のパーマリンクの構造、正規のオリジン、リダイレクト、メニュー、使用中の投稿タイプ、タクソノミー、新しいサイトで引き継ぐ必要のあるプラグイン独自のフィールドを記録しておきます。

インポート方法の選択

方法 使う場面 含まれるデータ
WXRのアップロード 「ツール」→「エクスポート」からエクスポートできる場合 エクスポートに含まれるデータ。投稿、固定ページ、カスタム投稿タイプ、タクソノミーのターム、再利用ブロック、投稿者、添付ファイルのURLを含みます
EmDash Exporter WordPressのサイトを管理していて、エクスポーターをインストールできる場合 認証付きで取得したコンテンツに加え、対応しているコメント、メニュー、サイト設定、SEOのフィールド、タクソノミー、メディアのメタデータ

エクスポーターなしでサイトのURLを入力した場合は、公開されているWordPressのREST APIを調べるだけです。この調査では、WordPressであることを検出し、公開されている投稿、固定ページ、メディアの数を数えられますが、RESTから直接インポートすることはできません。

本サイトの補足 やさしい解説

WordPressからの移行方法は2つあります。1つは、WordPressの「ツール」→「エクスポート」で作るXMLファイル（WXR）をアップロードする方法です。もう1つは、WordPressに「EmDash Exporter」プラグインを入れて、EmDashから直接つなぐ方法です。後者は、WXRには含まれないコメント、メニュー、サイト設定、SEOのフィールドなども対象になります。WordPressのサイトにプラグインを入れられるかどうかで選びます。

WXRファイルのエクスポート

WordPressで「ツール」→「エクスポート」を開き、「すべてのコンテンツ」を選択して、XMLのエクスポートファイルをダウンロードします。WXRファイルはWordPressのオリジンにあるメディアを指しているだけで、添付ファイルのデータそのものは含みません。

EmDash Exporterの接続

WordPressで「ツール」→「EmDash Migration」を開き、移行用のキーを生成します。そのキーを、EmDashのインポートのページに貼り付けます。

WordPressのサイトのURLを入力することもできます。エクスポーターが検出されたら、WordPressのアプリケーションパスワードの画面でEmDashを承認します。ローカルのHTTPの開発用サイトでは、承認のコールバックにHTTPSが必要なため、WordPressのユーザー名とアプリケーションパスワードを手動で入力します。

管理画面からのインポート

  1. EmDashのサイドバーで「Import WordPress」を開くか、/_emdash/admin/import/wordpress にアクセスします。

  2. WXRファイルをアップロードするか、エクスポーターの移行用のキーを貼り付けるか、WordPressのURLを入力します。

  3. 分析結果を確認します。WordPressの投稿タイプごとに、インポート先のコレクション、必須のフィールド、既存のフィールドとの互換性を確かめます。

  4. WordPressの投稿者を、EmDashのユーザーに対応づけます。対応づけていない元の投稿者は、ゲストのバイラインで表せるため、表示上のクレジットのためにEmDashのログインを与える必要はありません。

  5. エクスポーターでのインポートでは、メニュー、サイトのタイトルとキャッチフレーズ、ロゴとファビコン、対応しているSEOの値をインポートするかどうかを選びます。これらの切り替えは、WXRでのインポートにはありません。

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

  7. 添付ファイルが見つかった場合は、メディアの段階を実行します。EmDashは元のデータをダウンロードし、設定したストレージアダプターを通して保存し、コンテンツ内の該当するURLを書き換えます。

変換のされ方

公開状態

インポーターは、WordPressの公開状態を次のように対応づけます。

WordPress EmDash
publish published
draft draft
pending draft
private draft
future、trash、または不明な状態 draft

予約投稿の日時とWordPressの公開範囲のルールは、これらの状態からは再現されません。インポートした下書きは、公開する前にすべて確認します。

本サイトの補足 やさしい解説

WordPressで「予約投稿」「非公開」「レビュー待ち」だった記事は、EmDashではすべて下書き（draft）として取り込まれます。予約していた公開日時も引き継がれません。インポートしたあとに、下書きになった記事を1つずつ確認し、必要なものを公開し直すか、予約公開を設定し直します。

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

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

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

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

投稿タイプの既定の対応づけには、post から posts、page から pages が含まれます。カスタム投稿タイプは、使えない文字を取り除いたコレクションのスラッグを使います。準備の段階で、分析結果が必要とする標準のフィールド（タイトル、Portable Textの本文、抜粋、アイキャッチ画像）が追加されます。

型に互換性のある既存のフィールドは、そのまま使われます。型が一致しない場合、そのコレクションの対応づけはできません。インポーターが既存のフィールドを別の型に変換することはありません。

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

WXRの分析では、内部用ではない投稿メタのキーを報告し、フィールド名と型を提案します。ただし、WXRのデータベースへのインポートで書き込むのは、インポートされる標準のフィールドで、任意のメタのキーをすべてコピーするわけではありません。分析結果は、別途変換が必要になりそうなフィールドのチェックリストとして扱います。

EmDash Exporterでの移行では、インポート先のコレクションに対応するフィールドがある場合、カスタムメタとAdvanced Custom Fields（ACF）の値をコピーできます。また、インポートの切り替えを有効にしている場合は、対応しているアイキャッチ画像と、YoastまたはRank MathのSEOのフィールドを作成して値を入れられます。シリアライズされたPHPの値、リピーター、フレキシブルコンテンツ、プラグイン独自の構造は、WordPressでの表現がEmDashのフィールドの型と一致すると決めつけず、確認します。

投稿者とバイライン

対応づけたWordPressの投稿者は、エントリーの所有者になります。表示上のクレジットにはバイラインを使います。ユーザーの対応づけがない場合、EmDashはWordPressの投稿者の情報をもとに、ゲストのバイラインを作成するか、既存のものを再利用します。

タクソノミー

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

メディア

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

EmDashが添付ファイルをダウンロードしている間は、元のサイトにアクセスできる状態にしておく必要があります。添付ファイルのURLからのリダイレクトは、たどる前に検証されます。

途中で止まったインポートのやり直し

管理画面のインポートは、既存のエントリーをスキップするように作られていますが、照合の範囲に注意が必要です。

  • 既存のコンテンツは、WordPressのIDではなく、コレクション、スラッグ、ロケールで照合されます。
  • 前回と今回の間で元のスラッグが変わった場合は、両方のエントリーを確認し、重複を手動で解消します。
  • メディアの段階をもう一度実行すると、すでに保存されている、データが同一のファイルを、コンテンツのハッシュによって再利用します。
  • エクスポーターでの処理は、一定の大きさに区切って送信します。ブラウザーでの処理をやり直すと、コンテンツのページがもう一度実行され、スキップされたエントリーから関連の対応表が作り直されます。

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

切り替える前の確認

インポートしたサイトを、元のサイトと照らし合わせて確認します。

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

新しいサイトが本番で問題なく動き、切り戻しが不要になるまで、バックアップとWordPressの環境は残しておきます。

トラブルシューティング

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

「ツール」→「エクスポート」からファイルをもう一度エクスポートし、ダウンロードが完了したことを確かめます。文字コードを変えてしまうツールでXMLを編集しないでください。

コレクションに互換性がないと表示される

同じスラッグで型の異なる既存のフィールドがあります。やり直す前に、投稿タイプの対応づけを変えるか、「コンテンツタイプ」でフィールドを調整します。準備の段階では、足りないフィールドは追加しますが、既存のフィールドの型は変更しません。

メディアのURLのダウンロードに失敗する

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

テーマの対応

一覧のルートには getEmDashCollection()、スラッグのルートには getEmDashEntry() を使います。entry.id はルートの識別子で、通常はスラッグです。entry.data.id は保存されたコンテンツのIDで、関連を扱うヘルパーで使います。

次のルートは、インポートした投稿を描画します。

src/pages/posts/[slug].astro
---
import { decodeSlug, getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.redirect("/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.redirect("/404");
---

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

ルートとコンポーネントの対応づけは、WordPressテーマの移植を参照してください。エンドポイントの仕様と、やり直しの正確な範囲は、コンテンツのインポートを参照してください。

訳の誤りを報告する