Content Syncでデータベースのコンテンツをファイルに移す
ブロック、テンプレート、ファイルベースのページはすでにリポジトリにあります。一方、チームメンバー、オフィスの所在地、事例紹介など、管理画面で編集者が作成するコンテンツは、この方法には当てはまりません。こうしたコンテンツもプロジェクトにとって重要です。ステージングサイトには本番環境と同じチームページが必要で、新しい開発者には実際に近いデータが必要です。また、レビュー担当者は誰かが役職名を変更したときに確認できるべきです。データベースのダンプでは、こうした問題をうまく解決できません。すべてのデータが含まれ、環境ごとにIDが異なり、SQLの差分を確認する人もいないからです。
Content Syncはこのギャップを埋めます。WP-CLIコマンドで、投稿、ターム、関連付け、メタデータの許可リストをJSONファイルとHTMLファイルに変換してテーマに保存できます。別のコマンドで、それらのファイルを別のデータベースに適用します。各エンティティには移植可能なUIDが割り当てられ、エンティティ間の参照は宣言したものだけが書き換えられます。
このガイドではチームディレクトリを例に、ファイルへの取り込み、確認、ファイルの編集、新しい環境への移行、安全な整理の手順を説明します。
例
テーマは、すべての環境でacme_member投稿タイプとacme_teamタクソノミーを登録します。各メンバーの投稿には次の情報を持たせられます:
| メタキー | 内容 |
|---|---|
_acme_role |
役職名を示す単純な文字列 |
_acme_mentor |
別のメンバーの投稿ID |
_thumbnail_id |
顔写真の添付ファイルID |
_acme_api_token |
gitに絶対に含めてはならない連携トークン |
Content Syncが投稿タイプやタクソノミーを登録することはありません。適用先のすべての環境に存在している必要があります。
手順1: Content Syncを設定する
blockstudio.jsonで有効にするまで、Content Syncは無効です。それまでは、コマンドを実行するとskippedの行が1つだけ返されます:
wp bs content status
action entity id uid message
skipped content default Content Sync is disabled. Set content.enabled to true to run this command.
contentグループを追加します:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"content": {
"enabled": true,
"id": "team",
"path": "content",
"postTypes": ["acme_member"],
"taxonomies": ["acme_team"],
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
},
"media": "manifest"
}
}
各キーで対象範囲を限定します:
postTypesとtaxonomiesは許可リストです。範囲外のものが読み取り、書き込み、整理されることはありません。postTypesが空の場合、投稿は処理されません。meta.includeでメタキーを許可リストに指定します。*ワイルドカードを使えます。meta.excludeが常に優先され、_edit_lock、_edit_last、_wp_old_slugは既定で除外されます。meta.referencesでは、どのメタ値がIDなのかを宣言します。Content Syncは、整数がIDかどうかを推測しません。idはコンテンツセットの名前です。同期するすべてのエンティティに保存され、整理の対象は同じセットのエンティティに限られます。pathは出力先のフォルダーです。現在のテーマディレクトリからの相対パスで指定します。
手順2: 取り込む
まず変換内容をプレビューします。何も書き込まれず、表示されたUIDもまだ保存されていません:
wp bs content pull --dry-run
action entity id uid message
would-write post 530 4c8e9997-... .../posts/acme_member/jane.4c8e9997.json
would-write post 531 6cddc303-... .../posts/acme_member/sam.6cddc303.json
would-write term 4 6661b6d9-... .../terms/acme_team/leadership.6661b6d9.json
続いて実際に取り込みます。UIDを持たない各エンティティに永続的な_blockstudio_content_uidを割り当て、ファイルを書き出します:
wp bs content pull
action entity id uid message
written post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
written post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
written term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
written media manifest .../media/manifest.json
テーマ内の結果は次のとおりです:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
ファイル名にはスラッグとUIDの先頭部分が使われます。投稿JSONにはフィールド、タームとの関連付け、許可されたメタデータが保存されます:
{
"uid": "5d4bf9b5-16b7-4975-acc6-51dc1d4e49ec",
"type": "acme_member",
"status": "publish",
"slug": "jane",
"title": "Jane Doe",
"date": "2026-10-13T03:03:02+00:00",
"modified": "2026-10-13T03:03:02+00:00",
"parent": null,
"menuOrder": 0,
"terms": {
"acme_team": [
"7491a6a1-702c-4a29-9993-9ae7b2a79c0a"
]
},
"meta": {
"_acme_role": "Design Lead",
"_thumbnail_id": "72a2db75-6fd2-41f9-8d3c-b323ce3b3551"
},
"metaEncoding": {
"_acme_role": "scalar",
"_thumbnail_id": "scalar"
}
}
タームとの関連付けとサムネイルには、環境ごとのIDではなくUIDが使われます。投稿本文は、隣接するjane.5d4bf9b5.htmlに生のブロックマークアップとして保存されます。Samの投稿のようにコンテンツが空の場合、.htmlファイルは作成されません。Samの_acme_mentorには、post参照として宣言されているため、JaneのUIDが保存されます。
手順3: コミット前に確認する
コミット前にstatusを実行します。ファイルとデータベースを比較し、リスクのあるデータにもフラグを付けます:
wp bs content status
action entity id uid message
unchanged post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
unchanged post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
warning meta _acme_api_token Allowlisted meta key may contain secrets or PII; review before committing synced files.
_acme_*のワイルドカードがトークンを捕捉しました。meta.includeをコミット境界として扱い、キーを明示的に除外してください。
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
次のpullはトークンなしでsam.208db72e.jsonを書き換え、ほかのファイルには触れません。statusはブロックマークアップ本文内の数値IDについても警告します。Content Syncは.htmlファイル内のIDを書き換えないためです。
content/フォルダーをコミットしてください。
ステップ 4:ファイルを編集してプッシュする
ファイルがpushの信頼できる情報源です。JSONファイルでJaneの権限をDesign LeadからHead of Designに変更し、どうなるか確認してください。
wp bs content status
action entity id uid message
would-update post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
unchanged post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
push --dry-runはプッシュ順で同じ計画を出力します。適用してください。
wp bs content push
action entity id uid message
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
updated post 530 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
unchanged post 531 208db72e-... .../posts/acme_member/sam.208db72e.json
プッシュは書き込み前に計画全体を検証します。解決されていない宣言済み参照、スラッグの競合、投稿タイプの欠落、形式不正のファイルがあると停止します。
WordPressは更新された投稿に新しい更新日時を設定しますが、ファイルには古いmodifiedの値が残ります。そのため、このプッシュの直後にstatusを実行すると、Janeの投稿は「データベースが前回の同期後に変更されました。」というメッセージとともにconflictとして報告されます。プッシュ後にpullを1回実行して新しい日時を記録すると、その後statusはunchangedを報告します。
ステップ 5:コンテンツを別の環境に移動する
新しい環境では、ファイルにまだ存在しない投稿が記述されています。この例では、タームと肖像画像の添付ファイルが同じUIDで既に存在するため、不足しているのは2人のメンバーだけです。
wp bs content status
action entity id uid message
missing-db post jane 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
missing-db post sam 208db72e-... .../posts/acme_member/sam.208db72e.json
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
wp bs content push
action entity id uid message
unchanged term 4 7491a6a1-... .../terms/acme_team/leadership.7491a6a1.json
created post 536 5d4bf9b5-... .../posts/acme_member/jane.5d4bf9b5.json
created post 537 208db72e-... .../posts/acme_member/sam.208db72e.json
投稿には新しいローカルID 536と537が割り当てられました。参照先も追従しています。Samの_acme_mentorには536が入り、Janeは再びleadershipタームに属し、彼女の_thumbnail_idは一致するUIDを持つローカル添付ファイルを指しています。投稿の親、タームの親、タームとの関係は常にUIDで保存されます。メタ値が書き換えられるのはmeta.referencesに含まれるキーだけです。
安全な削除
ファイルを削除しても、明示的に指定しない限りプッシュ時に何も削除されません。sam.208db72e.jsonを削除して、削除処理を試してください。
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
ドライランでは削除対象が表示されます。
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yesを実行すると、Samの投稿はゴミ箱に移動され、pruned-trashと報告されます。対象を限定するため、いくつかの保護措置があります。
- このコンテンツセット(
content.id)が所有するエンティティのみが候補です。 - 設定された投稿タイプとタクソノミーのみが対象です。
- 書き込みや削除の前に、ソース計画全体を解析して検証します。フォルダー内に形式不正のJSONファイルがあると、プッシュは
could not be read: Syntax errorのようなerror行を報告し、何も削除しません。
デフォルトの動作はtrashです。blockstudio/content/orphan_actionフィルターは、エンティティごとにtrash、delete、またはkeepを返せます。これにより、投稿はデフォルトのままにしてタームを保持できます。
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
これを設定すると、孤立したタームはwould-prune-trashではなくwould-prune-keepとして報告されます。
メディア
メディアファイルはコピーされません。content.mediaは、宣言された添付ファイル参照の扱いを決めます。
"manifest"(デフォルト)は添付ファイルのUIDを保存し、パス、MIMEタイプ、代替テキストとともにcontent/media/manifest.jsonに一覧表示します。プッシュ先に参照された添付ファイルUIDがすべて存在する必要があるため、まず通常のメディア移行手順でアップロードしてください。"none"は宣言された添付ファイル参照をファイルに含めません。その場合、JaneのJSONには_acme_roleだけが含まれます。省略されたキーはプッシュ時に適用されないため、既存のプッシュ先投稿のサムネイルはそのまま残ります。
エンティティをロックする
プッシュ先の環境で、ある投稿の独自バージョンを保持したい場合があります。その投稿の_blockstudio_content_lockedメタにtruthy値を設定すると、プッシュはlocked行と「ロックされたエンティティをスキップしました。」というメッセージを出して、その投稿をスキップします。再び対象に含めるには、このメタを削除してください。
所有権のルール
- ファイルベースのページで管理される投稿は、デフォルトで除外されます。
includePageSyncManaged: trueを指定すると、Content Syncは設定されたメタデータを同期できますが、Page Syncは引き続きpost_contentを管理します。これらのJSON投影にはbodyOwner: "page-sync"が含まれ、pullでは本文がスキップされたことが明示的に報告されます。既存の.htmlレビュー用コピーは保持され、pushでは無視されます。メタデータの投影をpushする前に、対象環境でページを同期してください。 - ユーザーは同期されないため、作成者はデフォルトで無視されます。
authors: "login"を指定すると、投稿ファイルに作成者のログイン名が保存され、push時に既存ユーザーへ解決されます。ユーザーが見つからない場合は、事前確認でエラーになります。 pullはファイルを削除しません。データベースのエンティティがなくなると、pullはそのファイルを古いものとして報告し、削除はユーザーに委ねます。
使用に適さないケース
Content Syncは、変更頻度の低い厳選されたコンテンツに適しています。数十から数百件、データが構造化され、用途別の投稿タイプに分割されていれば数千件程度まで扱えます。データベースのバックアップや移行の代わりにはなりません。注文、フォーム送信、ログ、分析データ、大量の編集コンテンツには、それぞれ専用のツールを使ってください。タクソノミー定義、メディアのバイナリデータ、ブロックマークアップ内のIDは対象外です。
次のステップ
- Content Syncリファレンス:設定キー、ファイル形式、保存される同期状態のすべて。
- ドキュメントサイトの構築:ファイルから始まり、WordPressへ同期されるコンテンツ。
- ファイルベースのページの構築:テーマのテンプレートが構造を管理するページ。