Memindahkan Konten Database ke File dengan Sinkronisasi Konten
Blok, template, dan halaman berbasis file sudah tersimpan di repositori Anda. Sebagian konten tidak sesuai dengan model tersebut karena dibuat oleh editor di panel admin: anggota tim, lokasi kantor, studi kasus. Konten itu tetap penting bagi proyek. Situs staging memerlukan halaman tim yang sama dengan produksi, pengembang baru memerlukan data yang realistis, dan peninjau perlu melihat perubahan jabatan. Dump database tidak menyelesaikan masalah ini dengan baik. Dump membawa semuanya, ID berbeda di setiap lingkungan, dan tak seorang pun meninjau diff SQL.
Content Sync mengatasi kesenjangan itu. Sebuah perintah WP-CLI memproyeksikan daftar izin pos, term, relasi, dan metadata ke dalam berkas JSON dan HTML di tema Anda. Perintah lain menerapkan berkas tersebut ke basis data lain. Setiap entitas mendapat UID portabel, dan referensi antarentitas hanya ditulis ulang jika Anda menetapkannya.
Panduan ini membahas direktori tim: mengekspornya ke berkas, meninjaunya, mengedit berkas, memindahkannya ke lingkungan baru, dan memangkasnya dengan aman.
Contoh
Tema mendaftarkan jenis pos acme_member dan taksonomi acme_team di setiap lingkungan. Setiap pos anggota dapat memuat:
| Kunci meta | Isi |
|---|---|
_acme_role |
Jabatan, berupa string biasa |
_acme_mentor |
ID pos anggota lain |
_thumbnail_id |
ID lampiran potret |
_acme_api_token |
Token integrasi yang tidak boleh masuk ke git |
Content Sync tidak pernah mendaftarkan jenis pos atau taksonomi. Keduanya harus tersedia di setiap tempat Anda melakukan push.
Langkah 1: Konfigurasikan Content Sync
Content Sync nonaktif sampai Anda mengaktifkannya di blockstudio.json. Sebelum itu, setiap perintah mengembalikan satu baris skipped:
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.
Tambahkan grup 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"
}
}
Setiap kunci menetapkan batas:
postTypesdantaxonomiesadalah daftar izin. Apa pun di luar daftar tersebut tidak dibaca, ditulis, atau dipangkas.postTypesyang kosong berarti tidak ada pos yang disentuh.meta.includemengizinkan kunci meta, dengan wildcard*.meta.excludeselalu mengesampingkannya, sedangkan_edit_lock,_edit_last, dan_wp_old_slugdikecualikan secara default.meta.referencesmenyatakan nilai meta mana yang merupakan ID. Content Sync tidak pernah menebak bahwa bilangan bulat adalah ID.idmemberi nama pada kumpulan konten. Nama ini disimpan pada setiap entitas yang disinkronkan, dan pemangkasan hanya menyentuh entitas dari kumpulan yang sama.pathadalah folder keluaran, relatif terhadap direktori tema aktif.
Langkah 2: Tarik
Pratinjau proyeksi terlebih dahulu. Tidak ada yang ditulis, dan UID yang ditampilkan belum disimpan:
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
Lalu lakukan penarikan sungguhan. Ini menetapkan _blockstudio_content_uid permanen pada setiap entitas yang belum memilikinya dan menulis berkas:
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
Hasilnya di tema:
content/
├── media/
│ └── manifest.json
├── posts/
│ └── acme_member/
│ ├── jane.5d4bf9b5.html
│ ├── jane.5d4bf9b5.json
│ └── sam.208db72e.json
└── terms/
└── acme_team/
└── leadership.7491a6a1.json
Nama berkas menggabungkan slug dengan bagian awal UID. Pos JSON memuat bidang, relasi term, dan meta yang diizinkan:
{
"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"
}
}
Relasi term dan gambar mini menggunakan UID, bukan ID lokal. Isi pos berada di jane.5d4bf9b5.html sebagai markup blok mentah. Pos dengan konten kosong, seperti milik Sam, tidak mendapat berkas .html. _acme_mentor milik Sam disimpan sebagai UID Jane karena kunci tersebut ditetapkan sebagai referensi post.
Langkah 3: Tinjau Sebelum Melakukan Commit
Jalankan status sebelum melakukan commit. Perintah ini membandingkan berkas dan basis data, serta menandai data berisiko:
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.
Wildcard _acme_* menangkap token tersebut. Perlakukan meta.include sebagai batas commit dan kecualikan kunci itu secara eksplisit:
"meta": {
"include": ["_acme_*", "_thumbnail_id"],
"exclude": ["_acme_api_token"],
"references": {
"_acme_mentor": { "kind": "post" },
"_thumbnail_id": { "kind": "attachment" }
}
}
Perintah pull berikutnya menulis ulang sam.208db72e.json tanpa token dan membiarkan berkas lainnya tetap utuh. status juga memperingatkan tentang ID numerik di dalam isi markup blok, karena Content Sync tidak menulis ulang ID dalam berkas .html.
Lakukan commit pada folder content/.
Langkah 4: Edit Berkas dan Lakukan Push
Berkas adalah sumber kebenaran untuk push. Ubah peran Jane di berkas JSON dari Design Lead menjadi Head of Design, lalu periksa dampaknya:
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 menampilkan rencana yang sama dalam urutan push. Terapkan rencana itu:
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
Push memvalidasi seluruh rencana sebelum menulis. Referensi yang ditetapkan tetapi belum terselesaikan, konflik slug, jenis pos yang tidak ada, dan berkas yang formatnya keliru akan menghentikan proses.
WordPress memberikan waktu modifikasi baru pada pos yang diperbarui, sementara berkas masih menyimpan nilai modified lama. Karena itu, proses status tepat setelah push ini melaporkan pos Jane sebagai conflict dengan pesan “Database changed since last sync.” Jalankan pull sekali setelah push untuk merekam waktu baru; kemudian status melaporkan unchanged.
Langkah 5: Pindahkan Konten ke Lingkungan Lain
Di lingkungan baru, berkas menjelaskan pos yang belum ada. Dalam contoh ini, term dan lampiran potret sudah tersedia di sana dengan UID yang sama, jadi hanya dua anggota yang belum ada:
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
Pos-pos itu mendapat ID lokal baru, 536 dan 537. Referensinya ikut disesuaikan: _acme_mentor Sam kini memuat 536, Jane kembali berada di term leadership, dan _thumbnail_id miliknya menunjuk ke lampiran lokal dengan UID yang cocok. Induk pos, induk term, dan relasi term selalu disimpan sebagai UID; nilai meta hanya ditulis ulang untuk kunci dalam meta.references.
Memangkas dengan Aman
Menghapus berkas tidak akan menghapus apa pun saat push kecuali Anda memintanya. Hapus sam.208db72e.json dan coba pangkas:
wp bs content push --prune
Error: Refusing to prune without --yes. Re-run with --dry-run to inspect the plan or --yes to confirm.
Simulasi menunjukkan apa yang akan dihapus:
wp bs content push --prune --dry-run
action entity id uid message
...
would-prune-trash post 537 208db72e-...
push --prune --yes lalu memindahkan pos Sam ke tempat sampah dan melaporkan pruned-trash. Beberapa pengaman membatasi cakupannya:
- Hanya entitas milik kumpulan konten ini (
content.id) yang menjadi kandidat. - Hanya jenis pos dan taksonomi yang dikonfigurasi yang dipertimbangkan.
- Seluruh rencana sumber diurai dan divalidasi sebelum apa pun ditulis atau dipangkas. Jika ada berkas JSON dengan format keliru di folder, push melaporkan baris
errorseperticould not be read: Syntax errordan tidak memangkas apa pun.
Tindakan default adalah trash. Filter blockstudio/content/orphan_action dapat mengembalikan trash, delete, atau keep untuk setiap entitas. Dengan begitu, term tetap dipertahankan sementara pos mengikuti default:
add_filter(
'blockstudio/content/orphan_action',
function ( string $action, string $type ) {
return 'term' === $type ? 'keep' : $action;
},
10,
2
);
Dengan pengaturan ini, term yatim dilaporkan sebagai would-prune-keep, bukan would-prune-trash.
Media
Berkas media tidak pernah disalin. content.media menentukan apa yang terjadi pada referensi lampiran yang ditetapkan:
"manifest"(default) menyimpan UID lampiran dan mencantumkannya dicontent/media/manifest.jsonbeserta jalur, jenis MIME, dan teks alternatif. Push mengharuskan setiap UID lampiran yang dirujuk tersedia di target, jadi pindahkan unggahan terlebih dahulu melalui alur kerja media yang biasa Anda gunakan."none"tidak menyertakan referensi lampiran yang ditetapkan dalam berkas. JSON milik Jane kemudian hanya memuat_acme_role. Karena kunci yang tidak disertakan tidak diterapkan saat push, pos target yang sudah ada akan mempertahankan gambar mininya saat ini.
Mengunci Entitas
Terkadang lingkungan target perlu mempertahankan versinya sendiri dari sebuah pos. Tetapkan nilai yang bernilai benar pada meta _blockstudio_content_locked pos tersebut, lalu push akan melewatinya dengan baris locked dan pesan “Locked entity skipped.” Hapus meta itu untuk menyertakannya kembali.
Aturan Kepemilikan
- Post yang dikelola oleh halaman berbasis file dikecualikan secara default. Dengan
includePageSyncManaged: true, Content Sync dapat menyinkronkan meta yang dikonfigurasi untuk post tersebut, tetapi Page Sync tetap mengelolapost_contentmiliknya. Proyeksi JSON tersebut membawabodyOwner: "page-sync", dan pull secara eksplisit melaporkan isi yang dilewati. Salinan tinjauan.htmlyang sudah ada dipertahankan dan diabaikan oleh push. Sinkronkan halaman di lingkungan target sebelum melakukan push proyeksi metadatanya. - Penulis diabaikan secara default karena pengguna tidak disinkronkan. Dengan
authors: "login", file post menyimpan login penulis dan push mencocokkannya dengan pengguna yang sudah ada; pengguna yang tidak ditemukan menyebabkan kesalahan prapemeriksaan. pulltidak pernah menghapus file. Jika entitas di database sudah tidak ada, pull melaporkan filenya sebagai kedaluwarsa dan menyerahkan pembersihannya kepada Anda.
Kapan Sebaiknya Tidak Digunakan
Content Sync cocok untuk konten terkurasi dengan sedikit perubahan: puluhan atau ratusan entri, hingga beberapa ribu jika datanya terstruktur dan dibagi ke dalam jenis pos yang terfokus. Fitur ini bukan pengganti pencadangan atau migrasi basis data. Pesanan, kiriman formulir, log, analitik, dan konten editorial bervolume tinggi sebaiknya ditangani oleh alat tersebut. Definisi taksonomi, berkas biner media, dan ID di dalam markup blok berada di luar cakupannya.
Langkah Berikutnya
- Referensi Content Sync: semua kunci konfigurasi, format berkas, dan status sinkronisasi yang disimpan.
- Membangun Situs Dokumentasi: konten yang bermula di berkas lalu disinkronkan ke WordPress melalui arah sebaliknya.
- Membangun Halaman Berbasis Berkas: halaman yang strukturnya dikelola oleh templat dalam tema.