Aller au contenu principal

Dépanner et déboguer les Blueprints

Les erreurs de Blueprint pointent généralement vers l’un de ces trois endroits :

  • Le JSON du Blueprint n’est pas valide.
  • Playground n’a pas pu récupérer le Blueprint ou l’une de ses ressources.
  • Une étape du Blueprint s’est exécutée, mais WordPress, PHP, WP-CLI ou une extension a échoué.

Commencez par le nom d’erreur exact affiché par Playground, puis utilisez la section correspondante ci-dessous.

Liste de vérification rapide​

  • Collez le Blueprint dans l’éditeur de Blueprints pour valider le schéma JSON.
  • Si le Blueprint est chargé depuis une URL, ouvrez cette URL directement dans une fenêtre de navigation privée et confirmez qu’elle télécharge du JSON valide ou un bundle ZIP de Blueprint.
  • Si une étape échoue, notez son numéro dans BlueprintStepExecutionError. L’étape échouée est généralement l’élément à cette position après le développement des raccourcis de Blueprint.
  • Ouvrez les outils de développement du navigateur et consultez les onglets Console et Network pour obtenir des détails sur le téléchargement, CORS, PHP ou l’activation d’extensions.
  • Pour les échecs d’activation d’extension ou de thème, consultez le panneau Logs de Playground ou la console du navigateur pour les avertissements PHP et les erreurs fatales.

InvalidBlueprintError​

InvalidBlueprintError signifie que le Blueprint ne correspond pas au format de données Blueprint. La sortie d’erreur contient généralement des chemins comme /steps/2/pluginData ou /preferredVersions.

Propriété inattendue activate​

activate doit se trouver dans options, pas directement sur l’étape ni dans pluginData.

{
	"step": "installPlugin",
	"pluginData": {
		"resource": "wordpress.org/plugins",
		"slug": "woocommerce"
	},
	"options": {
		"activate": true
	}
}

Propriété inattendue plugins dans preferredVersions​

preferredVersions accepte uniquement php et wp. Installez les extensions avec le raccourci de premier niveau plugins ou avec une étape explicite installPlugin.

{
	"preferredVersions": {
		"php": "8.3",
		"wp": "latest"
	},
	"plugins": ["sqlite-database-integration"]
}

slug, url, path ou files manquant​

L’objet de ressource est incomplet ou utilise une forme incorrecte. Corrections courantes :

  • Extension WordPress.org : { "resource": "wordpress.org/plugins", "slug": "akismet" }
  • URL ZIP : { "resource": "url", "url": "https://example.com/plugin.zip" }
  • Répertoire Git : { "resource": "git:directory", "url": "https://github.com/org/repo", "ref": "trunk", "refType": "branch" }

Consultez les références des ressources pour voir toutes les formes de ressource prises en charge.

Propriétés d’installation d’extension mélangées​

Utilisez pluginData pour installPlugin. Ne fournissez pas à la fois pluginData et d’anciens exemples ou objets personnalisés comme pluginZipFile.

La ressource d’extension WordPress.org nécessite aussi un slug séparé :

{
	"step": "installPlugin",
	"pluginData": {
		"resource": "wordpress.org/plugins",
		"slug": "woocommerce"
	}
}

N’écrivez pas "resource": "wordpress.org/plugins/woocommerce".

BlueprintFetchError​

BlueprintFetchError signifie que Playground n’a pas pu charger le fichier passé à ?blueprint-url=.

Vérifiez que l’URL :

  • Est publique et ne nécessite pas de cookies, de connexion, de session temporaire ni de VPN.
  • Renvoie HTTP 200 lorsqu’elle est ouverte directement.
  • Sert du JSON valide ou un bundle ZIP avec blueprint.json à l’intérieur.
  • Envoie Access-Control-Allow-Origin: * ou un autre en-tête qui autorise https://playground.wordpress.net.
  • Utilise une URL de fichier brut, pas une page HTML de dépôt.

Pour GitHub, utilisez des URL raw.githubusercontent.com au lieu de github.com/.../blob/.... Pour GitLab, utilisez l’URL de fichier brut au lieu d’une page /-/blob/.

# Good
https://raw.githubusercontent.com/WordPress/blueprints/trunk/blueprints/welcome/blueprint.json

# Not a raw JSON response
https://github.com/WordPress/blueprints/blob/trunk/blueprints/welcome/blueprint.json

Les URL de tunnel temporaires, les URL de développement local et les assets de release en brouillon échouent souvent parce que le navigateur ne peut pas les atteindre ou parce qu’ils n’autorisent pas les requêtes cross-origin. Déplacez le Blueprint vers un hébergeur public avec CORS activé.

Blueprint file is neither a valid JSON nor a ZIP file​

Cela signifie que Playground a reçu une réponse, mais que cette réponse n’était pas un Blueprint. L’URL a pu renvoyer une page HTML, une page 404, un aperçu de fichier de dépôt, un avertissement de proxy, une page de connexion ou un ZIP corrompu.

Ouvrez l’URL directement et vérifiez que :

  • Les URL JSON renvoient du JSON de Blueprint valide.
  • Les URL de bundle ZIP téléchargent une véritable archive ZIP.
  • Les bundles de Blueprint contiennent blueprint.json à la racine du ZIP.
  • La réponse n’est pas une petite page d’erreur HTML ou texte.

URIError: URI malformed​

URIError: URI malformed indique généralement un fragment de Blueprint encodé cassé dans l’URL, pas une étape de Blueprint échouée. Vérifiez les échappements % invalides, les fragments doublement encodés ou le JSON brut collé après #. Reconstruisez le lien depuis le Blueprint d’origine et encodez-le une seule fois, ou utilisez Base64. Consultez les fragments de Blueprint encodés.

ResourceDownloadError​

ResourceDownloadError signifie que le Blueprint s’est chargé, mais qu’une étape n’a pas pu télécharger une ressource comme un ZIP d’extension, un ZIP de thème, un fichier WXR ou une archive de site importée.

Confirmez que l’URL de la ressource :

  • Télécharge le fichier réel, pas une page HTML, un avertissement de redirection ou un artifact expiré.
  • Est publique et ne nécessite pas d’authentification.
  • Autorise les requêtes cross-origin.
  • Est l’URL directe du fichier. Certaines pages de release et pages d’artifacts CI sont des pages destinées aux humains, pas des téléchargements directs.
  • Existe encore. Les liens temporaires et les artifacts CI peuvent expirer.

Pour du code source dans un dépôt Git, préférez une ressource git:directory. Utilisez une ressource url pour des artifacts ZIP construits qui sont déjà téléchargeables publiquement.

BlueprintStepExecutionError​

BlueprintStepExecutionError signifie qu’une étape précise a échoué après le démarrage du Blueprint. Le message inclut un numéro d’étape :

BlueprintStepExecutionError: Error when executing the blueprint step #4

Utilisez ce numéro pour inspecter l’étape correspondante. Si votre Blueprint utilise des raccourcis comme plugins, login, siteOptions ou constants, Playground les développe en étapes avant d’exécuter le Blueprint. Utilisez des steps explicites lorsque l’ordre compte.

Les paramètres de requête d’URL comme ?plugin=..., ?theme=..., ?php=..., ?wp=... et ?networking=yes créent aussi un Blueprint implicite. Les erreurs issues de ces URL restent des erreurs d’exécution de Blueprint, et les étapes générées influencent le numéro d’étape indiqué.

PHP.run() failed with exit code 255​

Le code de sortie 255 signifie généralement que PHP a rencontré une erreur fatale. Recherchez la première ligne Fatal error, Uncaught ou TypeError dans la sortie. La grande page d’erreur HTML qui l’entoure est généralement l’écran générique d’erreur critique de WordPress.

Pour rendre la sortie plus utile pendant le débogage, activez les constantes de débogage WordPress près du début du Blueprint :

{
	"step": "defineWpConfigConsts",
	"consts": {
		"WP_DEBUG": true,
		"WP_DEBUG_LOG": true,
		"WP_DEBUG_DISPLAY": true,
		"WP_DISABLE_FATAL_ERROR_HANDLER": true
	}
}

Relancez ensuite le Blueprint et consultez le panneau Logs de Playground ou la console du navigateur.

PHP.run() failed with exit code 1​

Le code de sortie 1 apparaît souvent lorsque WP-CLI ou WordPress renvoie une erreur applicative. Lisez d’abord la section Stderr. Elle nomme généralement l’argument non pris en charge, la ressource manquante ou l’échec propre à la commande.

Certaines commandes WP-CLI se comportent différemment dans Playground parce que WordPress s’exécute dans WebAssembly avec SQLite. Gardez les commandes courtes et testez-les individuellement avant d’ajouter une longue chaîne à un Blueprint.

Undefined constant ABSPATH​

Cela se produit généralement dans une étape runPHP qui appelle des API WordPress sans charger WordPress au préalable.

Ajoutez wp-load.php avant toute fonction, constante, option ou API d’extension WordPress :

{
	"step": "runPHP",
	"code": "<?php require '/wordpress/wp-load.php'; update_option('blogname', 'Demo site');"
}

Plugin could not be activated​

Les erreurs d’activation d’extensions viennent généralement de l’extension elle-même, pas de l’exécuteur de Blueprints. Causes fréquentes :

  • L’extension nécessite une version plus récente de PHP ou de WordPress.
  • L’extension déclenche une erreur fatale pendant l’activation.
  • L’extension dépend d’une autre extension qui n’est pas installée ou activée.
  • L’extension effectue une redirection ou affiche une sortie inattendue pendant l’activation.
  • Le ZIP de l’extension s’extrait dans un dossier ou un fichier principal dont le nom ne correspond pas au chemin activé par l’étape.

Si l’erreur indique que la version actuelle de PHP ou de WordPress ne respecte pas les prérequis minimaux, définissez preferredVersions :

{
	"preferredVersions": {
		"php": "8.3",
		"wp": "latest"
	}
}

WordPress exited with exit code 0​

L’activation peut échouer même quand WordPress se termine avec le code 0. Cela signifie généralement que WordPress a renvoyé une réponse d’erreur d’activation, plutôt qu’un plantage du processus PHP. Quand le message indique Inspect the "debug" logs, consultez le panneau Logs de Playground, la console du navigateur ou la sortie de la CLI.

Cherchez des avertissements PHP, des redirections ou une sortie imprimée pendant l’activation, des extensions dépendantes manquantes ou des prérequis minimaux PHP/WordPress de l’extension.

Current PHP or WordPress version does not meet minimum requirements​

Les erreurs d’incompatibilité de version contiennent souvent un texte comme :

Current PHP version (7.4.33) does not meet minimum requirements. The plugin requires PHP 8.0.

ou :

Current WordPress version (6.9.4) does not meet minimum requirements. The plugin requires WordPress 7.0.

Définissez preferredVersions avec une version compatible de PHP et de WordPress, ou utilisez une version de l’extension ou du thème compatible avec les versions disponibles dans Playground.

Si l’erreur est :

Failed to download WordPress 6.9.0 (HTTP 404)

la build WordPress demandée n’est pas disponible. Utilisez latest, une version publiée prise en charge ou une valeur beta/nightly prise en charge.

Si l’erreur indique Plugin file does not exist, inspectez le nom du dossier installé. Pour les URL ZIP dont les noms de dossier sont inhabituels, définissez targetFolderName :

{
	"step": "installPlugin",
	"pluginData": {
		"resource": "url",
		"url": "https://example.com/my-plugin.zip"
	},
	"options": {
		"activate": true,
		"targetFolderName": "my-plugin"
	}
}

Si l’extension a des dépendances, installez et activez d’abord ces dépendances avec des étapes explicites.

Theme could not be activated​

Les échecs d’activation de thèmes signifient généralement que le nom du dossier du thème est incorrect, que le ZIP du thème s’est extrait dans un répertoire inattendu ou que le code du thème a causé une erreur WordPress/PHP.

Utilisez installTheme avec options.activate lors de l’installation d’un thème :

{
	"step": "installTheme",
	"themeData": {
		"resource": "wordpress.org/themes",
		"slug": "twentytwentyfour"
	},
	"options": {
		"activate": true
	}
}

Si vous utilisez une étape activateTheme autonome, fournissez le nom du dossier dans wp-content/themes, pas une URL complète ni un nom de fichier ZIP.

Could not write to a file​

Les erreurs comme celle-ci signifient que le répertoire parent n’existe pas :

Could not write to "/wordpress/wp-content/plugins/example/index.php":
There is no such file or directory OR the parent directory does not exist.

Créez d’abord le répertoire avec mkdir, ou utilisez writeFiles avec une ressource literal:directory.

[
	{
		"step": "mkdir",
		"path": "/wordpress/wp-content/plugins/example"
	},
	{
		"step": "writeFile",
		"path": "/wordpress/wp-content/plugins/example/index.php",
		"data": "<?php /* Plugin Name: Example */"
	}
]

Could not unzip file​

Cela signifie généralement que le fichier n’est pas une archive ZIP valide. L’URL peut avoir renvoyé une page HTML, une réponse d’erreur, une page de connexion ou un fichier tronqué.

Si la sortie indique Could not unzip file. Error code: 19, vérifiez que le téléchargement est bien une archive ZIP. Une petite taille de fichier signifie souvent que le serveur a renvoyé une page d’erreur HTML au lieu de l’archive.

Ouvrez l’URL directement et confirmez que le navigateur télécharge un ZIP. Si vous utilisez un artefact GitHub ou CI, utilisez une URL de téléchargement direct et vérifiez que la release ou l’artefact est public.

Pièges des commandes WP-CLI​

L’étape wp-cli exécute WP-CLI dans Playground. Elle est utile pour les tâches de configuration, mais toutes les commandes ou fonctionnalités du shell ne se comportent pas comme dans un terminal local.

Corrections fréquentes :

  • Utilisez le nom d’étape "wp-cli", pas "wpcli" ni "cli".
  • Gardez les commandes ciblées. Préférez plusieurs étapes wp-cli à une seule commande shell complexe.
  • Évitez les substitutions shell comme $(...) dans les Blueprints partagés. Utilisez runPHP pour la logique qui nécessite les API WordPress.
  • Vérifiez les noms de paramètres dans la commande WP-CLI que vous utilisez. Par exemple, les paramètres propres à une commande peuvent différer entre wp post list, wp post delete et les commandes fournies par des extensions.
  • Si une commande WP-CLI fournie par une extension échoue avec une trace de pile de l’extension, la correction se trouve généralement dans cette extension ou dans les données d’entrée transmises à la commande.
  • Si une commande échoue avec unknown --post_type parameter ou unknown --format parameter, vérifiez si ces options appartiennent à une autre commande du pipeline.
  • Si une commande d’extension échoue avec Unsupported argument type passed to WP_CLI::error_to_string(): 'NULL', confirmez que l’extension est active, que les données importées existent et que l’entrée de la commande pointe vers une ressource valide.

WP-CLI: Error establishing a database connection sur les sites montés​

Lorsque vous utilisez wp-cli avec un site Playground monté, par exemple via --mount-before-install, vous pouvez rencontrer "Error establishing a database connection." Cela se produit parce que WordPress Playground charge par défaut l’extension d’intégration de base de données SQLite depuis ses fichiers internes, pas depuis le répertoire monté.

Ajoutez explicitement l’extension d’intégration SQLite au site WordPress monté :

{
	"preferredVersions": {
		"php": "8.3",
		"wp": "latest"
	},
	"plugins": ["sqlite-database-integration"],
	"steps": [
		{
			"step": "login",
			"username": "admin"
		}
	]
}

Exécutez ensuite le Blueprint avec le site monté :

mkdir wordpress
npx @wp-playground/cli server --mount-before-install=wordpress:/wordpress --blueprint=./blueprint.json

Outils de débogage​

Éditeur de Blueprints​

Utilisez l’éditeur de Blueprints dans le navigateur pour créer, valider et prévisualiser des Blueprints.

Attention

L’éditeur est en cours de développement et le Playground intégré échoue parfois à se charger. Pour contourner le problème, actualisez la page.

Inspection du système de fichiers et de la base de données​

Certaines étapes de Blueprint, comme writeFile, modifient le système de fichiers interne. D’autres, comme runSql, modifient la base de données.

Pour inspecter l’état final, installez des extensions comme SQL Buddy et WPide. Vous pouvez les voir en action sur https://playground.wordpress.net/?plugin=sql-buddy&plugin=wpide.

Vous pouvez aussi inspecter une instance Playground depuis la console du navigateur via window.playground :

await playground.isDir('/wordpress/wp-content/plugins');
await playground.listFiles('/wordpress/wp-content/plugins');

Consultez l’API PlaygroundClient complète.

Console du navigateur et requêtes réseau​

Ouvrez les outils de développement du navigateur pour vérifier les erreurs JavaScript, les journaux de débogage PHP et les requêtes réseau échouées. Dans Chrome, Firefox et Edge, appuyez sur Ctrl + Shift + I sous Windows/Linux ou sur Cmd + Option + I sous macOS.

Safari

Si vous n’avez pas activé le menu Développement, allez dans Safari > Settings... > Advanced et cochez Show features for web developers.

Journalisation d’erreurs personnalisée​

Vous pouvez écrire vos propres messages avec error_log() dans une étape runPHP, puis consulter le panneau Logs de Playground ou la console du navigateur.

Capture des erreurs de journal

Lorsque vous téléchargez votre instance Playground sous forme de ZIP via l’option "Download as zip", l’archive inclut aussi debug.log.

Demander de l’aide​

Si vous avez besoin d’aide, ouvrez une issue et incluez :

  • Le JSON du Blueprint ou l’URL publique du Blueprint.
  • Le message d’erreur exact.
  • Le numéro de l’étape en échec, s’il est affiché.
  • Le navigateur, le système d’exploitation et si vous avez utilisé le site web, l’API JavaScript ou la CLI.
  • La sortie pertinente de la console, du réseau ou de la CLI.