部署一个 Blockstudio 网站
只要将主题文件夹复制到服务器,区块就能正常工作:Blockstudio 会从文件系统中发现区块,其缓存也会自动检测输入的变化。实际网站还涉及更多环节。基于文件的页面只有在同步后才会进入数据库。静态预渲染内容会一直提供昨天的 HTML,直到有内容替换它。前面的 CDN 也会继续提供它缓存的内容。
本指南将介绍如何部署名为 acme 的主题,该主题通过 Composer 打包 Blockstudio。内容涵盖 CI 中运行的任务、文件部署到服务器后运行的任务、如何阅读页面同步报告,以及发布流程应包含哪些 wp bs 命令。
发布流程一图概览
- 构建。 CI 安装生产环境 Composer 依赖。
- 上传。 包含
vendor/在内的主题会部署到服务器。 - 同步页面。
wp bs pages sync将页面文章与文件保持一致,并输出报告。 - 刷新源站缓存。 页面有更改时清除已存储的 HTML,然后重新预热。
- 清除 CDN。 最后执行,让边缘节点从全新的源站重新填充缓存。
步骤 3 和 4 需要服务器上有 WP-CLI。下面的脚本还会使用 jq 来读取 JSON。
步骤 1:在 CI 中安装 Composer
将 Blockstudio 打包到主题中并提交 composer.lock,这样 CI 就会安装你测试过的确切版本:
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
在 CI 中安装时不包含开发依赖:
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
Blockstudio 从自动加载器启动,其运行时依赖也已打包并在包内使用命名空间。当它从 vendor/ 目录加载时,内置的 GitHub 更新器会被禁用,因此只有 Composer 能更改版本。
步骤 2:确定哪些目录必须可写
Blockstudio 会在运行时写入生成的文件。在部署替换或锁定目录之前,先确认写入位置:
- 运行时缓存默认位于
wp-content/blockstudio/cache/下。如果需要,可将cache.path指向专用的可写卷。更改路径后缓存将从空状态开始。 - 已编译的区块资源默认写入每个区块旁边的
_dist文件夹。如果发布目录为只读,或每次部署都会被替换,请将assets.output设为cache,让这些文件改为写入缓存目录:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"assets": {
"output": "cache"
}
}
部署时无需清除缓存。每个缓存条目都以其输入为键,其中包括区块文件、设置、当前主题和插件,以及 WordPress、PHP 和 Blockstudio 版本,因此更改这些内容的发布会生成新的键。在 production 和 staging 中,Blockstudio 会信任经过验证的监视快照 20 秒,然后才再次检查文件,因此更改可能需要最多 20 秒才会被发现。blockstudio/cache/watch_debounce 过滤器可以更改这个时间窗口。
步骤 3:同步页面
页面文章只会通过明确的同步操作发生变化。前端、管理后台、Ajax、REST、cron 和普通的 WP-CLI 请求都不会发现页面源文件或写入页面文章。部署时必须执行以下操作:
wp bs pages sync --format=json
在主题中有两个页面 about 和 contact 的网站上,首次运行会创建这两个页面:
{
"discovered": 2,
"created": 2,
"updated": 0,
"unchanged": 0,
"removed": 0,
"failed": 0,
"fullReconciliation": true,
"sourceId": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd",
"sourceIdentity": {
"commit": "",
"dirtyHash": "",
"inventoryHash": "aaec5b9dd13d74eea872117b6167caa7a5d5c1abad9572fba22f6ddf6340adfe",
"engineFingerprint": "2c442442bb49f91e7187560e6db8f3475caa0b62b47708cab95b6ff13aba4469",
"hash": "f88baddfd5a1deb94eb8c9bbeca10d5a0d47a72f16b50efdb25a7127945af7dd"
},
"pages": {
"about": {
"status": "created",
"postId": 545,
"locked": false
},
"contact": {
"status": "created",
"postId": 546,
"locked": false
}
},
"errors": []
}
如何理解这些数据:
created、updated、unchanged、removed和failed统计页面数量。如果页面的源文件指纹未发生变化,则不会写入文章或文章元数据,也不会触发更新钩子。- 每次执行都会比较完整的页面清单。
fullReconciliation会报告此次执行是否算作完整同步:首次运行时为true,传入--full时也为此值,或者同步引擎本身发生变化时为此值;如果存在先前成功同步的标识,则为false。下游工具可用它来决定是否重建全部内容。 sourceIdentity是页面清单和同步引擎的确定性指纹。命令会在成功执行后保存它。
不带 --format=json 时,命令会输出一行摘要和一条成功提示。在 CI 日志中(此时不是终端),摘要行以制表符分隔:
discovered created updated unchanged removed failed source_id
2 0 1 1 0 0 7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.
这次运行是在编辑 about/index.php 后执行的:一个页面已更新,另一个未更改。
同步失败时
如果发现或同步过程中报告错误,命令会以状态码 1 退出,导致 CI 步骤失败。仍会输出 JSON 报告,请将其记录到日志中。格式错误的 page.json 如下所示:
{
"discovered": 0,
...
"failed": 1,
...
"pages": [],
"errors": [
{
"code": "invalid_page_json",
"message": "Invalid page.json file.",
"context": {
"path": ".../wp-content/themes/acme/pages/pricing/page.json"
}
}
]
}
只有在执行过程无错误结束后,源文件已消失的受管理页面才会被清理,因此同步失败的发布不会破坏线上页面。默认情况下,被移除的页面会移至回收站;blockstudio/pages/orphan_action 过滤器可以返回 trash、delete 或 keep。
每次部署都运行
即使页面没有变化,也要运行同步。如果你部署到发布目录并切换符号链接,那么即使页面未更改,它仍会指向上一版本的模板和布局路径,直到下一次同步刷新这些路径。此刷新不会触及 post_content 或修改日期。
--authoritative 和 --full
普通同步会保留编辑者在带键区块中更改的内容。--authoritative 则会用文件中的受管理内容替换现有内容,并可能清除页面同步锁。适用于以文件为准的场景,例如重置暂存站点,或没有人在编辑器中修改由文件管理的页面时。对于有活跃编辑者的站点,不要在每次部署时都使用它。
--full 会将此次执行标记为完整同步,无论保存的标识是什么。每次执行都会完成页面比较,因此此标志只会更改报告中的 fullReconciliation,不会改变检查哪些页面。后续步骤需要依据该值执行完整重建时,请传入此标志。
使用 PHP 编写的工具可以直接调用 Blockstudio\Pages::reconcile()。它会返回同一份报告,但不会保存标识:在发布的其余部分(例如已激活的静态资源)验证通过后,调用 Blockstudio\Pages::store_successful_source_identity()。
步骤 4:刷新静态缓存
如果网站在默认的 signature 模式下使用 静态预渲染,由 WP-CLI 更新的页面文章不会自行清除已存储的 HTML。读取报告;只要有任何更改就清除缓存,然后预热:
#!/usr/bin/env bash
set -euo pipefail
cd /var/www/example.com
report=$(mktemp)
# 1. Reconcile file-backed pages and keep the report.
if ! wp bs pages sync --format=json > "$report"; then
cat "$report"
exit 1
fi
jq '{discovered, created, updated, unchanged, removed}' "$report"
# 2. Drop stored HTML when page content changed.
changed=$(jq '.created + .updated + .removed' "$report")
if [ "$changed" -gt 0 ]; then
wp bs prerender purge
fi
# 3. Re-warm in bounded passes until a pass warms nothing.
for _ in $(seq 1 50); do
warmed=$(wp bs prerender warm | jq '.warmed')
[ "$warmed" -gt 0 ] || break
done
wp bs prerender status | jq '{files, queue}'
每次 wp bs prerender warm 运行都会将过期的公开 URL 加入队列,最多渲染其中的 warm.concurrency 个,并输出摘要。在这次执行中,六个排队的 URL 有四个被领取,但四个都未能渲染:
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}
未能渲染的 URL 会继续处于过期状态,并在下次运行时重新入队。因此循环会在首次没有预热任何内容时停止,而不是一直等到队列清空。剩余内容由定时预热程序或下一次匿名访问处理。
在 graph 模式下,按 URL 运行的预热程序会关闭,且 warm 不会将任何内容加入队列。图站点会用自己的构建替代步骤 2 和 3,渲染受影响的 URL,并以原子方式激活结果。参见签名模式和图模式。
步骤 5:CI 工作流
以下工作流是一个 GitHub Actions 示例。其流程适用于任何 CI 系统:构建、上传、在服务器上运行脚本,然后清除 CDN。
name: Deploy
on:
push:
branches: [main]
concurrency:
group: deploy-production
cancel-in-progress: false
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: "8.2"
tools: composer:v2
- name: Install production dependencies
run: composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
- name: Configure SSH
run: |
mkdir -p ~/.ssh
echo "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
ssh-keyscan example.com >> ~/.ssh/known_hosts
- name: Upload the theme
run: |
rsync -az --delete --exclude ".git" --exclude ".github" \
./ deploy@example.com:/var/www/example.com/wp-content/themes/acme/
- name: Sync pages and refresh the static cache
run: ssh deploy@example.com 'bash -s' < scripts/post-deploy.sh
- name: Purge the CDN
run: curl -fsS -X POST "${{ secrets.CDN_PURGE_URL }}"
concurrency 配合 cancel-in-progress: false 使用时,会将第二次推送排在正在运行的部署之后,而不是在同步中途取消它。PHP 8.2 是 Blockstudio 的最低版本要求。将最后一步替换为你的 CDN 清除 API 的操作。
维护命令
这些命令不属于每次发布流程,但部署手册应介绍它们。
清理旧锁积压。 7.6.14 之前的版本会在每次内容更改时留下一个 .build.lock 文件。升级后,WP-Cron 会分批删除这些文件。检查积压并一次性清理:
wp bs cache status
wp bs cache cleanup
0 legacy build lock(s) across 0 cache namespace(s).
Next cleanup batch in 0 second(s).
cleanup 会将创建时间不到一小时的锁,以及仍由正在运行的请求持有的锁,留到下次执行处理。网站正在提供服务时,切勿手动删除锁文件。
清除运行时缓存。 wp bs cache clear 会清除当前站点的所有缓存,wp bs cache clear --scope=runtime 会清除所有命名空间中某个作用域的缓存。下一个请求会从空缓存开始重建,因此应在流量较低时运行,并且只在确有需要时运行:输入发生变化时,缓存键已经会自动轮换。
移除 Blockstudio。 Composer 安装没有插件停用钩子,因此包消失时,不会取消 cron 事件的计划,也不会移除提前提供服务的 drop-in 文件。移除依赖项之前,请运行此命令:
wp bs teardown
它会移除本安装所拥有的 cron 事件和静态预渲染状态,保留其他组件的 drop-in 文件和配置文件不变,并确保之后重新启用时从干净状态开始。