Publicarea unui site Blockstudio
Copierea unui dosar de temă pe un server este suficientă pentru blocuri: Blockstudio le descoperă din sistemul de fișiere, iar cache-urile sale detectează singure modificările intrărilor. Un site real are și alte componente. Paginile bazate pe fișiere ajung în baza de date numai când le sincronizați. O pre-randare statică continuă să afișeze HTML de ieri până când ceva o înlocuiește. Un CDN din față continuă să afișeze ceea ce a memorat în cache.
Acest ghid creează o implementare pentru o temă numită acme, care include Blockstudio prin Composer. Acoperă ce rulează în CI, ce rulează pe server după copierea fișierelor, cum se citește raportul de sincronizare a paginilor și ce comenzi wp bs trebuie incluse într-o versiune.
Lansarea, ilustrată
- Construire. CI instale les dépendances de production Composer.
- Téléverser. Le thème, y compris
vendor/, arrive sur le serveur. - Synchroniser les pages.
wp bs pages syncmet les articles de page en adéquation avec les fichiers et affiche un rapport. - Actualiser le cache d’origine. Les HTML stockés sont purgés lorsque des pages ont changé, puis remis en cache.
- Purger le CDN. En dernier, afin que le nœud périphérique recharge le cache depuis une origine à jour.
Les étapes 3 et 4 nécessitent WP-CLI sur le serveur. Le script ci-dessous utilise aussi jq pour lire JSON.
Étape 1 : Composer dans CI
Intégrez Blockstudio au thème et validez composer.lock, afin que CI installe la version exacte que vous avez testée :
{
"require": {
"blockstudio/blockstudio": "^7.0"
}
}
<?php
require_once __DIR__ . '/vendor/autoload.php';
Dans CI, installez sans les paquets de développement :
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
Blockstudio se lance depuis l’autoloader, et ses propres dépendances d’exécution sont intégrées au paquet et leurs espaces de noms y sont isolés. Lorsqu’il est chargé depuis un répertoire vendor/, son outil de mise à jour GitHub intégré est désactivé ; Composer reste donc le seul moyen de changer de version.
Étape 2 : Déterminer ce qui doit être accessible en écriture
Blockstudio écrit des fichiers générés à l’exécution. Repérez leur emplacement avant qu’un déploiement ne remplace ou ne verrouille un répertoire :
- Les caches d’exécution se trouvent par défaut sous
wp-content/blockstudio/cache/. Vous pouvez définircache.pathsur un volume dédié accessible en écriture. Si vous changez le chemin, le cache sera vide. - Les ressources de blocs compilées sont écrites par défaut dans un dossier
_distà côté de chaque bloc. Si votre répertoire de version est en lecture seule ou remplacé à chaque déploiement, définissezassets.outputsurcachepour les placer plutôt dans le répertoire de cache :
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"assets": {
"output": "cache"
}
}
Vous n’avez pas besoin de vider les caches lors d’un déploiement. Chaque entrée de cache est indexée par ses données d’entrée, notamment les fichiers de blocs, les réglages, le thème et les extensions actifs, ainsi que les versions de WordPress, PHP et Blockstudio. Une version qui les modifie obtient donc de nouvelles clés. Dans production et staging, Blockstudio fait confiance à un instantané de surveillance validé pendant 20 secondes avant de vérifier à nouveau les fichiers ; un changement peut donc prendre jusqu’à 20 secondes à être détecté. Le filtre blockstudio/cache/watch_debounce modifie cette durée.
Étape 3 : Synchroniser les pages
Les articles de page ne changent qu’à la suite d’une synchronisation explicite. Les requêtes du frontend, de l’interface d’administration, Ajax, REST, cron et les requêtes WP-CLI ordinaires ne recherchent jamais les sources de pages et n’écrivent jamais d’articles de page. Le déploiement doit le demander :
wp bs pages sync --format=json
Sur un site dont le thème comporte deux pages, about et contact, la première exécution les crée :
{
"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": []
}
Comment lire le résultat :
created,updated,unchanged,removedetfailedindiquent le nombre de pages. Si l’empreinte de la source d’une page n’a pas changé, aucun article ni métadonnée d’article n’est écrit et aucun hook de mise à jour n’est déclenché.- Chaque passage compare l’inventaire complet des pages.
fullReconciliationindique si le passage compte comme une synchronisation complète :truelors de la première exécution, avec--full, ou lorsque le moteur de synchronisation lui-même a changé, etfalselorsqu’une identité issue d’une synchronisation précédente réussie existe. Les outils en aval peuvent s’en servir pour décider s’il faut tout reconstruire. sourceIdentityest une empreinte déterministe de l’inventaire des pages et du moteur de synchronisation. La commande la stocke après un passage réussi.
Sans --format=json, la commande affiche une ligne récapitulative et une ligne de réussite. Dans un journal CI, qui n’est pas un terminal, les champs de la ligne sont séparés par des tabulations :
discovered created updated unchanged removed failed source_id
2 0 1 1 0 0 7bd575b4ee6c0a948f439dd83ce5fa403f8113c9406c3b13b6ade2f2b19f3c2c
Success: File-backed pages synchronized.
Cette exécution a suivi une modification de about/index.php : une page a été mise à jour, l’autre est restée inchangée.
En cas d’échec de la synchronisation
La commande se termine avec le statut 1 lorsque la découverte ou la synchronisation signale une erreur, ce qui fait échouer l’étape CI. Le rapport JSON est tout de même affiché : enregistrez-le dans le journal. Un page.json mal formé ressemble à ceci :
{
"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"
}
}
]
}
Les pages gérées dont les sources ont disparu ne sont supprimées qu’après un passage sans erreur ; ainsi, un échec de synchronisation lors d’un déploiement ne détruit pas les pages en ligne. Par défaut, les pages supprimées sont placées dans la corbeille ; le filtre blockstudio/pages/orphan_action peut renvoyer trash, delete ou keep.
L’exécuter à chaque déploiement
Exécutez la synchronisation même si aucune page n’a changé. Si vous déployez dans des répertoires de version et basculez un lien symbolique, le modèle et les chemins de mise en page de la version précédente resteront associés à une page inchangée jusqu’à leur actualisation lors de la prochaine synchronisation. Cette actualisation ne modifie ni post_content ni la date de modification.
--authoritative et --full
Une synchronisation normale préserve le contenu que les éditeurs ont modifié dans les blocs avec clé. --authoritative remplace plutôt le contenu géré par celui des fichiers et peut supprimer un verrou Page Sync. Utilisez-le lorsque les fichiers doivent prévaloir : pour réinitialiser un site de préproduction ou pour un site où personne ne modifie dans l’éditeur les pages gérées par des fichiers. Ne l’incluez pas dans chaque déploiement d’un site avec des éditeurs actifs.
--full marque le passage comme une synchronisation complète, quelle que soit l’identité stockée. La comparaison des pages est déjà complète à chaque passage ; ce drapeau modifie donc fullReconciliation dans le rapport, et non les pages vérifiées. Transmettez-le si une étape ultérieure déclenche une reconstruction complète en fonction de cette valeur.
Les outils écrits en PHP peuvent appeler directement Blockstudio\Pages::reconcile(). Cette fonction renvoie le même rapport, mais ne stocke pas l’identité : appelez Blockstudio\Pages::store_successful_source_identity() une fois le reste de la version vérifié, par exemple après l’activation d’un artefact statique.
Étape 4 : Actualiser le cache statique
Dacă site-ul folosește pre-randare statică în modul implicit signature, postările actualizate de pagină din WP-CLI nu invalidează automat datele stocate HTML. Citiți raportul și ștergeți datele stocate când s-a schimbat ceva, apoi încălziți cache-ul:
#!/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}'
Chaque exécution wp bs prerender warm met en file d’attente les URL publiques obsolètes, en génère jusqu’à warm.concurrency et affiche un récapitulatif. Lors de ce passage, quatre des six URL en file ont été prises en charge et les quatre ont échoué à la génération :
{"queued":6,"processed":4,"warmed":0,"skipped":0,"failed":4}
Une URL dont la génération échoue reste obsolète et est remise en file d’attente lors de la prochaine exécution. C’est pourquoi la boucle s’arrête au premier passage qui ne réchauffe rien, au lieu d’attendre une file vide. Les éléments restants seront traités par le réchauffeur planifié ou lors de la prochaine visite anonyme.
En mode graph, le réchauffeur par URL est désactivé et warm ne met rien en file d’attente. Les sites Graph remplacent les étapes 2 et 3 par leur propre compilation, qui génère les URL concernées et active le résultat de manière atomique. Voir les modes signature et graphe.
Étape 5 : Le workflow CI
Le workflow ci-dessous est un exemple GitHub Actions. Le principe s’applique à tout système CI : compiler, téléverser, exécuter le script sur le serveur et purger le 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 avec cancel-in-progress: false met une seconde mise en production en attente derrière celle en cours, au lieu de l’annuler en plein milieu d’une synchronisation. La version 8.2 de PHP est le minimum requis par Blockstudio. Remplacez la dernière étape par l’CDN de purge de votre API.
Commandes de maintenance
Ces commandes n’ont pas leur place dans chaque version, mais le guide de déploiement doit les mentionner.
Vider l’arriéré des anciens verrous. Les versions antérieures à 7.6.14 laissaient un fichier .build.lock pour chaque modification de contenu. Après la mise à niveau, WP-Cron les supprime par lots limités. Pour vérifier, puis vider l’arriéré en une fois :
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 conserve pour le passage suivant les verrous datant de moins d’une heure ou encore détenus par une requête en cours. Ne supprimez jamais les fichiers de verrou à la main pendant que le site reçoit du trafic.
Vider le cache d’exécution. wp bs cache clear purge tout le cache du site actuel, et wp bs cache clear --scope=runtime purge une portée dans tous les espaces de noms. La prochaine requête repartira d’un cache vide : exécutez cette commande en période de faible trafic et uniquement si nécessaire, car les changements des données d’entrée renouvellent déjà les clés.
Supprimer Blockstudio. Une installation Composer n’a pas de hook de désactivation d’extension ; aucun événement cron n’est donc déplanifié et le drop-in de réponse anticipée n’est pas supprimé lorsque le paquet disparaît. Exécutez cette commande avant de supprimer la dépendance :
wp bs teardown
Cette commande supprime les événements cron et l’état de pré-génération statique appartenant à cette installation, laisse intacts les drop-ins et fichiers de configuration externes et permet une réactivation ultérieure propre.
Pașii următori
- Construire des pages à partir de fichiers : les pages synchronisées par ce déploiement.
- Référence des pages : le comportement de synchronisation, le PHPraport de synchronisationAPI et le contrat d’identité du déploiement.
- CLIréférence : toutes les commandes
wp bs. - Mise en cache : emplacement du cache, identité, conservation et arriéré des verrous.
- Servir WordPress en tant que HTMLstatique : le cache actualisé à l’étape 4.
- Composer : installations en tant qu’extension, extension obligatoire, thème et extension intégrée au thème.