Pular para o conteúdo principal

Solução de problemas e depuração de Blueprints

Erros de Blueprint geralmente apontam para um destes três lugares:

  • O JSON do Blueprint é inválido.
  • O Playground não conseguiu buscar o Blueprint ou um dos recursos dele.
  • Uma etapa do Blueprint foi executada, mas o WordPress, PHP, WP-CLI ou um plugin falhou.

Comece pelo nome exato do erro mostrado pelo Playground e use a seção correspondente abaixo.

Lista de verificação rápida​

  • Cole o Blueprint no editor de Blueprints para validar o esquema JSON.
  • Se o Blueprint for carregado de uma URL, abra essa URL diretamente em uma janela privativa do navegador e confirme que ela baixa um JSON válido ou um pacote ZIP de Blueprint.
  • Se uma etapa falhar, anote o número da etapa em BlueprintStepExecutionError. A etapa com falha normalmente é o item nessa posição depois que os atalhos de Blueprint são expandidos.
  • Abra as ferramentas de desenvolvedor do navegador e verifique as abas Console e Network para detalhes de download, CORS, PHP ou ativação de plugins.
  • Para falhas de ativação de plugin/tema, confira o painel Logs do Playground ou o console do navegador para avisos e erros fatais de PHP.

InvalidBlueprintError​

InvalidBlueprintError significa que o Blueprint não corresponde ao formato de dados do Blueprint. A saída do erro normalmente contém caminhos como /steps/2/pluginData ou /preferredVersions.

Propriedade inesperada activate​

activate deve ficar dentro de options, não diretamente na etapa nem dentro de pluginData.

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

Propriedade inesperada plugins em preferredVersions​

preferredVersions aceita somente php e wp. Instale plugins com o atalho plugins no nível superior ou com uma etapa explícita installPlugin.

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

slug, url, path ou files ausente​

O objeto de recurso está incompleto ou usa o formato errado. Correções comuns:

  • Plugin do WordPress.org: { "resource": "wordpress.org/plugins", "slug": "akismet" }
  • URL de ZIP: { "resource": "url", "url": "https://example.com/plugin.zip" }
  • Diretório Git: { "resource": "git:directory", "url": "https://github.com/org/repo", "ref": "trunk", "refType": "branch" }

Consulte Referências de recursos para ver todos os formatos de recurso compatíveis.

Propriedades mistas de instalação de plugin​

Use pluginData para installPlugin. Não forneça pluginData junto com exemplos antigos ou objetos personalizados como pluginZipFile.

O recurso de plugin do WordPress.org também precisa de um slug separado:

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

Não escreva "resource": "wordpress.org/plugins/woocommerce".

BlueprintFetchError​

BlueprintFetchError significa que o Playground não conseguiu carregar o arquivo passado para ?blueprint-url=.

Verifique se a URL:

  • É pública e não exige cookies, login, sessão temporária ou VPN.
  • Retorna HTTP 200 quando aberta diretamente.
  • Serve JSON válido ou um pacote ZIP com blueprint.json dentro.
  • Envia Access-Control-Allow-Origin: * ou outro cabeçalho que permita https://playground.wordpress.net.
  • Usa uma URL de arquivo bruto, não uma página HTML de repositório.

Para GitHub, use URLs raw.githubusercontent.com em vez de github.com/.../blob/.... Para GitLab, use a URL de arquivo bruto em vez de uma página /-/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

URLs temporárias de túnel, URLs de desenvolvimento local e assets de lançamento em rascunho costumam falhar porque o navegador não consegue acessá-los ou porque eles não permitem requisições de origem cruzada. Mova o Blueprint para um host público com CORS ativado.

O arquivo de Blueprint não é JSON válido nem arquivo ZIP​

Isso significa que o Playground recebeu uma resposta, mas ela não era um Blueprint. A URL pode ter retornado uma página HTML, página 404, visualizador de arquivo de repositório, aviso de proxy, página de login ou ZIP corrompido.

Abra a URL diretamente e verifique se:

  • URLs JSON retornam JSON de Blueprint válido.
  • URLs de pacote ZIP baixam um arquivo ZIP real.
  • Pacotes de Blueprint contêm blueprint.json na raiz do ZIP.
  • A resposta não é uma pequena página HTML ou texto de erro.

URIError: URI malformed​

URIError: URI malformed normalmente aponta para um fragmento de Blueprint codificado incorretamente na URL, não para uma etapa de Blueprint com falha. Verifique escapes % inválidos, fragmentos codificados duas vezes ou JSON bruto colado depois de #. Reconstrua o link a partir do Blueprint original e codifique-o uma vez, ou use Base64. Consulte Fragmentos de Blueprint codificados.

ResourceDownloadError​

ResourceDownloadError significa que o Blueprint carregou, mas uma etapa não conseguiu baixar um recurso, como um ZIP de plugin, ZIP de tema, arquivo WXR ou arquivo de site importado.

Confirme se a URL do recurso:

  • Baixa o arquivo real, não uma página HTML, aviso de redirecionamento ou artefato expirado.
  • É pública e não exige autenticação.
  • Permite requisições de origem cruzada.
  • É a URL direta do arquivo. Algumas páginas de release e de artefatos de CI são páginas para pessoas, não downloads diretos.
  • Ainda existe. Links temporários e artefatos de CI podem expirar.

Para código-fonte em um repositório Git, prefira um recurso git:directory. Use um recurso url para artefatos ZIP criados e já disponíveis publicamente para download.

BlueprintStepExecutionError​

BlueprintStepExecutionError significa que uma etapa específica falhou depois que o Blueprint começou a ser executado. A mensagem inclui um número de etapa:

BlueprintStepExecutionError: Error when executing the blueprint step #4

Use esse número para inspecionar a etapa correspondente. Se o Blueprint usa atalhos como plugins, login, siteOptions ou constants, o Playground os expande em etapas antes de executar o Blueprint. Use steps explícitas quando a ordem for importante.

Parâmetros de consulta de URL como ?plugin=..., ?theme=..., ?php=..., ?wp=... e ?networking=yes também criam um Blueprint implícito. Erros dessas URLs ainda são erros de execução de Blueprint, e as etapas geradas afetam o número de etapa informado.

PHP.run() failed with exit code 255​

O código de saída 255 normalmente significa que o PHP encontrou um erro fatal. Procure a primeira linha Fatal error, Uncaught ou TypeError na saída. A grande página HTML de erro ao redor dela costuma ser a tela genérica de erro crítico do WordPress.

Para tornar a saída mais útil durante a depuração, ative as constantes de depuração do WordPress perto do início do Blueprint:

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

Depois execute o Blueprint novamente e confira o painel Logs do Playground ou o console do navegador.

PHP.run() failed with exit code 1​

O código de saída 1 costuma aparecer quando o WP-CLI ou o WordPress retorna um erro da aplicação. Leia primeiro a seção Stderr. Ela normalmente informa o argumento sem suporte, o recurso ausente ou a falha específica do comando.

Alguns comandos WP-CLI se comportam de forma diferente no Playground porque o WordPress é executado em WebAssembly com SQLite. Mantenha os comandos pequenos e teste-os individualmente antes de adicionar uma cadeia longa a um Blueprint.

Undefined constant ABSPATH​

Isso normalmente acontece em uma etapa runPHP que chama APIs do WordPress sem antes carregar o WordPress.

Adicione wp-load.php antes de qualquer função, constante, opção ou API de plugin do WordPress:

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

Plugin could not be activated​

Erros de ativação de plugin geralmente vêm do próprio plugin, não do executor de Blueprints. Causas comuns:

  • O plugin exige uma versão mais recente do PHP ou do WordPress.
  • O plugin tem um erro fatal na ativação.
  • O plugin depende de outro plugin que não está instalado ou ativado.
  • O plugin faz um redirecionamento ou imprime uma saída inesperada durante a ativação.
  • O ZIP do plugin é extraído para uma pasta ou arquivo principal com nome diferente do caminho que a etapa está ativando.

Se o erro disser que a versão atual do PHP ou do WordPress não atende aos requisitos mínimos, defina preferredVersions:

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

WordPress exited with exit code 0​

A ativação pode falhar mesmo quando o WordPress sai com código 0. Isso normalmente significa que o WordPress retornou uma resposta de erro de ativação, em vez de uma falha do processo PHP. Quando a mensagem disser Inspect the "debug" logs, verifique o painel Logs do Playground, o console do navegador ou a saída da CLI.

Procure avisos de PHP, redirecionamentos ou saída impressa durante a ativação, plugins de dependência ausentes ou requisitos mínimos de PHP/WordPress do plugin.

Current PHP or WordPress version does not meet minimum requirements​

Erros de incompatibilidade de versão costumam incluir textos como:

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.

Defina preferredVersions para uma versão compatível de PHP e WordPress, ou use uma versão do plugin/tema compatível com as versões disponíveis no Playground.

Se o erro for:

Failed to download WordPress 6.9.0 (HTTP 404)

a compilação solicitada do WordPress não está disponível. Use latest, uma versão lançada compatível ou um valor beta/nightly compatível.

Se o erro disser Plugin file does not exist, inspecione o nome da pasta instalada. Para URLs ZIP com nomes de pasta incomuns, defina targetFolderName:

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

Se o plugin tiver dependências, instale e ative essas dependências primeiro com etapas explícitas.

Theme could not be activated​

Falhas de ativação de tema geralmente significam que o nome da pasta do tema está errado, que o ZIP do tema foi extraído para um diretório inesperado ou que o código do tema causou um erro do WordPress/PHP.

Use installTheme com options.activate ao instalar um tema:

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

Se você usar uma etapa independente activateTheme, passe o nome da pasta dentro de wp-content/themes, não uma URL completa ou o nome do arquivo ZIP.

Could not write to a file​

Erros como este significam que o diretório pai não existe:

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.

Crie o diretório primeiro com mkdir ou use writeFiles com um recurso 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​

Isso normalmente significa que o arquivo não é um ZIP válido. A URL pode ter retornado uma página HTML, uma resposta de erro, uma página de login ou um arquivo truncado.

Se a saída disser Could not unzip file. Error code: 19, verifique se o download é um arquivo ZIP. Um tamanho de arquivo pequeno costuma significar que o servidor retornou uma página HTML de erro em vez do arquivo.

Abra a URL diretamente e confirme que o navegador baixa um ZIP. Se você estiver usando um artefato do GitHub ou de CI, use uma URL de download direto e garanta que a release ou o artefato seja público.

Armadilhas de comandos WP-CLI​

A etapa wp-cli executa o WP-CLI dentro do Playground. Ela é útil para tarefas de configuração, mas nem todo comando ou recurso de shell se comporta como em um terminal local.

Correções comuns:

  • Use o nome de etapa "wp-cli", não "wpcli" nem "cli".
  • Mantenha os comandos focados. Prefira várias etapas wp-cli em vez de um comando de shell complexo.
  • Evite substituições de shell como $(...) em Blueprints compartilhados. Use runPHP para lógica que precisa das APIs do WordPress.
  • Confira os nomes dos parâmetros no comando WP-CLI que você está usando. Por exemplo, parâmetros específicos podem diferir entre wp post list, wp post delete e comandos fornecidos por plugins.
  • Se um comando WP-CLI fornecido por plugin falhar com um stack trace do plugin, a correção normalmente pertence a esse plugin ou aos dados de entrada passados ao comando.
  • Se um comando falhar com unknown --post_type parameter ou unknown --format parameter, verifique se as flags pertencem a outro comando no pipeline.
  • Se um comando de plugin falhar com Unsupported argument type passed to WP_CLI::error_to_string(): 'NULL', confirme que o plugin está ativo, os dados importados existem e a entrada do comando aponta para um recurso válido.

WP-CLI: Error establishing a database connection on mounted sites​

Ao usar wp-cli com um site Playground montado, por exemplo via --mount-before-install, você pode encontrar "Error establishing a database connection." Isso acontece porque o WordPress Playground carrega o plugin de integração de banco de dados SQLite a partir de seus arquivos internos por padrão, não do diretório montado.

Adicione explicitamente o plugin de integração SQLite ao site WordPress montado:

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

Depois execute o Blueprint com o site montado:

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

Ferramentas de depuração​

Editor de Blueprints​

Use o editor de Blueprints no navegador para criar, validar e pré-visualizar Blueprints.

Atenção

O editor está em desenvolvimento e o Playground incorporado às vezes falha ao carregar. Para contornar isso, atualize a página.

Inspeção do sistema de arquivos e do banco de dados​

Algumas etapas de Blueprint, como writeFile, alteram o sistema de arquivos interno. Outras, como runSql, alteram o banco de dados.

Para inspecionar o estado final, instale plugins como SQL Buddy e WPide. Você pode vê-los em ação em https://playground.wordpress.net/?plugin=sql-buddy&plugin=wpide.

Você também pode inspecionar uma instância do Playground pelo console do navegador usando window.playground:

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

Consulte a API PlaygroundClient completa.

Console do navegador e requisições de rede​

Abra as ferramentas de desenvolvedor do navegador para verificar erros de JavaScript, logs de depuração de PHP e requisições de rede com falha. No Chrome, Firefox e Edge, pressione Ctrl + Shift + I no Windows/Linux ou Cmd + Option + I no macOS.

Safari

Se você ainda não ativou o menu Develop, acesse Safari > Settings... > Advanced e marque Show features for web developers.

Registro de erros personalizado​

Você pode gravar suas próprias mensagens com error_log() em uma etapa runPHP e depois conferir o painel Logs do Playground ou o console do navegador.

Captura de logs de erro

Ao baixar sua instância do Playground como ZIP pela opção "Download as zip", o arquivo também inclui debug.log.

Peça ajuda​

Se você precisar de ajuda, abra uma issue e inclua:

  • O JSON do Blueprint ou a URL pública do Blueprint.
  • A mensagem de erro exata.
  • O número da etapa com falha, se mostrado.
  • Navegador, sistema operacional e se você usou o site, a API JavaScript ou a CLI.
  • Saída relevante do console, da rede ou da CLI.