WordPress から Contentful への移行

今回は、WordPress のデータ（記事、メディアなど）を Contentful へ移行するためのツール・スクリプト群を作成しました。せっかくなので、実際に動かすための手順を紹介します。なお、コードは以下のリポジトリで展開しています。

• https://github.com/haramizu/wordpress2contentful

移行準備手順

WordPress のデータの準備

移行作業を進める前に、WordPress から以下のデータを取得してください。

1. 管理画面にログインをします
2. ツール - エクスポートを選択
3. すべてのコンテンツを選択して、xml ファイルを確保
4. メディアファイルをエクスポートから、画像ファイルを一式ダウンロード

ダウンロードしたファイル一式は、wordpress/ ディレクトリ配下に保存をしてください。なお、xmlファイルは解凍の必要はありませんが、画像ファイルは以下のコマンドで解凍が必要になります。

# 解凍先ディレクトリを作成
mkdir -p wordpress/media/

# 解凍・展開を実行
tar -xvf wordpress/media-export-197841949-from-0-to-1255.tar -C wordpress/media/

環境変数の設定

Contentful API にアクセスするための認証情報を設定します。

プロジェクトのルートディレクトリに .env または .env.local ファイルを作成し、必要なAPI情報を記載してください。本スクリプトは、安全のために .env より優先して .env.local から環境変数を読み込みます。

cp .env.example .env

(※ ローカル専用キーとして .env.local を作成し編集することも推奨します)

.env の設定項目は以下のとおりです。

# Contentful のスペースID
CONTENTFUL_SPACE_ID=YOUR_SPACE_ID

# Contentful Content Management API (CMA) アクセストークン
# WordPress からのデータを Contentful に書き込むために必須のトークンです。
# 個人設定 (Personal settings) -> Access Tokens から生成可能です。
CONTENTFUL_MANAGEMENT_TOKEN=YOUR_MANAGEMENT_TOKEN

# Contentful Content Delivery API (CDA) アクセストークン (オプション)
# 公開済みコンテンツの読み込みに使用します。
CONTENTFUL_ACCESS_TOKEN=YOUR_ACCESS_TOKEN

# Contentful Content Preview API (CPA) アクセストークン (オプション)
# 下書き段階のコンテンツの読み込みに使用します。
CONTENTFUL_PREVIEW_ACCESS_TOKEN=YOUR_PREVIEW_ACCESS_TOKEN

# 移行先の環境ID (デフォルト: master)
# 通常は sandbox 環境や master 環境を指定します。
CONTENTFUL_ENVIRONMENT=master

# 移行先デフォルトロケール（デフォルト: ja-JP）
# お使いの Contentful スペースのロケールに合わせて指定してください（例: ja-JP, en-US など）。
CONTENTFUL_LOCALE=ja-JP

Contentful 環境のクリーンアップ

移行テストを複数回実行する場合など、Contentful 上のエントリーやアセットをすべて削除して初期状態にクリーンアップするためのスクリプトを用意しました。

クリーンアップの実行手順

1. 依存関係のインストール（初回のみ）

   npm install

2. 安全確認のためのドライラン（確認のみ）

   npm run cleanup

   ターゲットのスペースIDと環境IDが表示され、実行には -- --confirm フラグが必要な旨が表示されます。

3. 実際の削除の実行

   npm run cleanup -- --confirm

npm run cleanup -- --confirm --keep-media

実際のスクリプトの動作

実際に移行をする際には、ステップをいくつかに分けてそれぞれのファイルとして用意をしています。

Content Type作成

移行に必要なコンテンツモデル（Category, Tag, Blog Post）を Contentful 側に自動で作成・設定します。また、wordpress/content/ 配下の最新のXMLファイルを検出して確認します。

npm run setup

これを実行すると、３つのコンテンツタイプが作成されます。

メディアファイルのアップロード

wordpress/media/ 配下に解凍したメディアファイルを Contentful Asset として一括アップロードおよび公開（Publish）します。

• 処理はレートリミットを考慮して安全に行われ、各ファイルは相対パスを基に一意な決定論的 ID（Deterministic ID）で登録されるため、再実行時はすでにアップロード・公開済みのファイルをスキップします。

メディアアップロードの実行

npm run media-upload

記事・カテゴリ・タグのアップロード

パースしたXMLからカテゴリ、タグ、記事データ（Blog Post）を読み込み、Contentful の該当コンテンツモデルへ移行・登録します。

• すべてのカテゴリ・タグが自動的に作成および公開（Publish）されます。
• 記事の移行時、対応するカテゴリ、タグ、および featuredImage（アイキャッチ画像など）の参照リンク（References）が自動的に紐付きます。
• 移行されたエントリーは決定論的 ID（例: wp_post_<wordpressId>）を持つため、再実行時は安全に更新（上書き）され、二重登録は発生しません。
• 元の WordPress のステータスが publish の記事のみ、アップロード後に自動公開（Publish）されます。

コンテンツアップロードの実行は以下のコマンドで実行します。

npm run content-upload

プロジェクト構成

このプロジェクトは、以下のような構成になっています。

詳しくは、リポジトリにある README.md を参照してください。