使用内容同步将数据库内容移入文件
区块、模板和基于文件的页面已经存放在仓库中。有些内容不适用于这种模式,因为编辑人员是在管理后台中创建的:团队成员、办公地点、案例研究。这些内容对项目仍然很重要。预发布站点需要与生产环境相同的团队页面,新开发人员需要真实的数据,审核者也应能看到有人更改职位名称的情况。数据库转储并不能很好地解决这些问题。它们会包含所有内容,不同环境中的 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
启用之前,Content Sync 处于关闭状态。在 blockstudio.json 中启用之前,每条命令都会返回一行 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
然后执行实际拉取。这会为每个尚无永久 _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"
}
}
术语关联和缩略图使用的是 UID,而不是本地 ID。文章正文以原始区块标记形式存放在旁边的 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 的文章报告为 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 术语,而她的 _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-keep,而不是 would-prune-trash。
媒体
媒体文件绝不会被复制。content.media 用于决定如何处理已声明的附件引用:
"manifest"(默认)会存储附件 UID,并在content/media/manifest.json中列出它们及其路径、MIME 类型和替代文本。推送要求目标环境中存在每个被引用附件的 UID,因此请先使用常规媒体工作流程迁移上传文件。"none"会将已声明的附件引用排除在文件之外。这样 Jane 的 JSON 中只会包含_acme_role。由于推送不会应用省略的键,目标环境中已有的文章会保留当前缩略图。
锁定实体
有时,目标环境需要保留某篇文章的本地版本。在该文章上将元数据 _blockstudio_content_locked 设为真值,推送便会跳过它,并返回一行 locked,显示消息“已跳过锁定的实体。”删除此元数据即可再次包含该文章。
所有权规则
- 默认情况下,基于文件的页面所管理的文章会被排除。启用
includePageSyncManaged: true后,Content Sync 可以同步其已配置的元数据,但 Page Sync 仍负责管理这些文章的post_content。这些 JSON 投影会携带bodyOwner: "page-sync",而拉取操作会明确报告跳过的正文。 现有的.html审阅副本会保留,并在推送时忽略。推送其元数据投影前,请先在目标环境中同步这些页面。 - 默认情况下,作者会被忽略,因为用户不会同步。启用
authors: "login"后,文章文件会存储作者的登录名,推送时会解析为现有用户;若用户不存在,预检会报错。 pull永远不会删除文件。数据库实体被删除时,拉取操作会将其文件报告为过时文件,并由你负责清理。
何时不应使用
Content Sync 适用于经过筛选、变更较少的内容:数十或数百条记录;如果数据结构化且拆分到专门的文章类型中,则可扩展到数千条左右。它不能替代数据库备份或迁移工具。订单、表单提交、日志、分析数据和高频编辑内容应交由这些工具处理。分类法定义、媒体二进制文件以及区块标记中的 ID 均不在其适用范围内。
后续步骤
- Content Sync 参考:所有配置键、文件格式和已存储的同步状态。
- 构建文档站点:内容从文件开始,并通过同步以 WordPress 相反的方向流转。
- 构建基于文件的页面:页面结构由主题中的模板管理。