コンテンツへスキップ

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グループを追加します:

JSON
{
  "$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にはフィールド、タームとの関連付け、許可されたメタデータが保存されます:

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をコミット境界として扱い、キーを明示的に除外してください。

JSON
"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を返せます。これにより、投稿はデフォルトのままにしてタームを保持できます。

PHP
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は対象外です。

次のステップ