跳转到正文

使用内容同步将数据库内容移入文件

区块、模板和基于文件的页面已经存放在仓库中。有些内容不适用于这种模式,因为编辑人员是在管理后台中创建的:团队成员、办公地点、案例研究。这些内容对项目仍然很重要。预发布站点需要与生产环境相同的团队页面,新开发人员需要真实的数据,审核者也应能看到有人更改职位名称的情况。数据库转储并不能很好地解决这些问题。它们会包含所有内容,不同环境中的 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 组:

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

然后执行实际拉取。这会为每个尚无永久 _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"
    }
}

术语关联和缩略图使用的是 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 视为提交边界,并明确排除该键:

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,以记录新的时间;随后 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。这样可以保留术语,同时让文章继续使用默认操作:

PHP
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 均不在其适用范围内。

后续步骤