콘텐츠 동기화로 데이터베이스 콘텐츠를 파일로 옮기기
블록, 템플릿, 파일 기반 페이지는 이미 저장소에 있습니다. 하지만 팀원, 사무실 위치, 사례 연구처럼 관리 화면에서 편집자가 만드는 일부 콘텐츠는 이 방식에 들어맞지 않습니다. 그래도 이런 콘텐츠는 프로젝트에 중요합니다. 스테이징 사이트에도 프로덕션과 같은 팀 페이지가 필요하고, 새 개발자에게는 현실적인 데이터가 있어야 하며, 검토자는 누군가 직함을 변경했을 때 이를 확인할 수 있어야 합니다. 데이터베이스 덤프로는 이런 문제를 제대로 해결할 수 없습니다. 모든 데이터를 담고, 환경마다 ID가 다르며, 누구도 SQL diff를 검토하지 않습니다.
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 행 하나만 반환합니다.
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는 Jane의 UID로 저장됩니다. 이 키가 post 참조로 지정되어 있기 때문입니다.
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의 게시물이 “Database changed since last sync.” 메시지와 함께 conflict으로 보고됩니다. 푸시 후 pull을 한 번 실행해 새 시간을 기록하면 status가 unchanged을 보고합니다.
5단계: 다른 환경으로 콘텐츠 이동
새 환경에는 아직 존재하지 않는 게시물을 파일이 설명합니다. 이 예시에서는 용어와 프로필 사진 첨부 파일이 동일한 UID로 이미 존재하므로 구성원 게시물 두 개만 누락되어 있습니다.
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 용어에 속하며, Jane의 _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 파일이 있으면 푸시가
error행(예:could not be read: Syntax 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를 저장하고content/media/manifest.json에 경로, MIME 유형, 대체 텍스트와 함께 나열합니다. 푸시 대상에 참조된 첨부 파일 UID가 있어야 하므로 먼저 평소 사용하던 미디어 워크플로우로 업로드 파일을 옮기세요."none"은 선언된 첨부 파일 참조를 파일에서 제외합니다. 그러면 Jane의 JSON에는_acme_role만 포함됩니다. 생략된 키는 푸시할 때 적용되지 않으므로 대상에 이미 있는 게시물의 썸네일은 유지됩니다.
엔터티 잠그기
대상 환경에서 게시물 하나의 자체 버전을 유지해야 할 때가 있습니다. 해당 게시물의 _blockstudio_content_locked 메타에 참으로 평가되는 값을 설정하면 푸시가 해당 게시물을 건너뛰고 locked 행 및 “Locked entity skipped.” 메시지를 표시합니다. 메타를 삭제하면 다시 포함됩니다.
소유권 규칙
- 파일 기반 페이지에서 관리하는 게시물은 기본적으로 제외됩니다.
includePageSyncManaged: true를 사용하면 Content Sync가 설정된 메타 데이터를 동기화할 수 있지만, 해당 게시물의post_content는 Page Sync가 계속 관리합니다. 이러한 JSON 프로젝션에는bodyOwner: "page-sync"가 포함되며, pull은 건너뛴 본문을 명시적으로 보고합니다. 기존.html검토용 사본은 보존되며 push에서 무시됩니다. 메타데이터 프로젝션을 push하기 전에 대상 환경에서 페이지를 동기화하세요. - 사용자는 동기화되지 않으므로 작성자는 기본적으로 무시됩니다.
authors: "login"를 사용하면 게시물 파일에 작성자의 로그인 정보가 저장되고 push가 이를 기존 사용자에 연결합니다. 사용자가 없으면 사전 검사 오류가 발생합니다. pull는 파일을 삭제하지 않습니다. 데이터베이스 항목이 사라지면 pull은 해당 파일을 오래된 파일로 보고하고 정리는 사용자에게 맡깁니다.
사용하지 말아야 할 경우
Content Sync는 엄선된 변경 빈도가 낮은 콘텐츠에 적합합니다. 항목이 수십 개나 수백 개일 때 사용할 수 있으며, 데이터가 구조화되어 있고 게시물 유형별로 잘 나뉘어 있다면 수천 개 초반까지 처리할 수 있습니다. 데이터베이스 백업이나 마이그레이션을 대체하지는 않습니다. 주문, 양식 제출, 로그, 분석 데이터, 대량 편집 콘텐츠는 해당 도구를 사용하세요. 분류 체계 정의, 미디어 바이너리, 블록 마크업 내부의 ID는 지원 범위에 포함되지 않습니다.
다음 단계
- Content Sync 참조: 모든 구성 키, 파일 형식, 저장된 동기화 상태를 설명합니다.
- 문서 사이트 구축: 파일에서 시작해 다른 방향으로 WordPress에 동기화되는 콘텐츠를 다룹니다.
- 파일 기반 페이지 구축: 테마의 템플릿이 구조를 관리하는 페이지를 다룹니다.