O zip do tema estava pronto para subir, e a barra dos caminhos estava errada
O Compress-Archive do Windows PowerShell 5.1 grava os caminhos do zip com barra invertida. Testamos o que acontece no Linux e como conferir antes.
Segunda-feira, 9 de novembro. A versão nova do tema de um portal que a gente mantém estava pronta, testada, e o zip, montado com um comando de PowerShell que todo mundo usa no Windows: Compress-Archive. Antes de enviar pelo painel do WordPress, por hábito, listamos o que tinha dentro do arquivo. As 81 entradas estavam assim:
setupdodev\assets\
setupdodev\404.php
setupdodev\style.css
Barra invertida. O zip foi refeito na hora, com barras normais, e subiu sem problema. Mas a pergunta ficou: o que teria acontecido se ele tivesse ido daquele jeito?
Por que isso é um problema
A especificação do formato ZIP, a APPNOTE da PKWARE (versão 6.3.10, item 4.4.17.1), é clara: todas as barras do caminho devem ser barras normais (/), e não invertidas, para os sistemas Unix entenderem. O Windows aceita as duas. O Linux, onde roda quase todo WordPress, não trata a barra invertida como separador de pasta: para ele, setupdodev\style.css é o nome de um arquivo só.
O que testamos hoje
Montamos um tema mínimo (style.css, index.php e um CSS numa subpasta) e repetimos o caminho com as duas versões do PowerShell que convivem no Windows 11:
Windows PowerShell 5.1.26100 meutema\assets\ meutema\style.css ...
PowerShell 7.6.9 meutema/assets/ meutema/style.css ...
O mesmo comando, o mesmo nome, resultados diferentes. O powershell.exe, que vem instalado em todo Windows, grava barra invertida. O pwsh, que você instala à parte, grava certo.
Depois, extraímos o zip do 5.1 num Ubuntu com duas ferramentas:
- o
unzipdo Info-ZIP avisou "appears to use backslashes as path separators", corrigiu sozinho e montou as pastas certas, mas terminou com código de saída 1. Num script que para no primeiro erro, a implantação para ali; - o
zipfiledo Python 3.14 não avisou nada e criou quatro arquivos soltos, com a barra invertida no nome:meutema\style.cssna raiz, e nenhuma pastameutema.
O que a gente não testou: o que o próprio WordPress faz com esse zip num servidor Linux. Ele extrai com o ZipArchive do PHP ou com o PclZip, e não tínhamos um PHP em Linux à mão para provar. Não vamos afirmar o resultado. O que dá para dizer é que duas ferramentas comuns fizeram duas coisas diferentes, e uma delas desmontou o tema sem avisar.
A pegadinha da conferência
A primeira ideia para conferir o zip no Windows é o tar -tf arquivo.zip, que já vem no sistema. Fizemos. Ele listou meutema/assets/, com barra normal: o tar do Windows (bsdtar 3.8.9) converte na hora de mostrar e esconde o problema. Se a sua conferência é essa, ela passa um zip errado.
O que mostra a verdade é ler o nome gravado de cada entrada. No PHP, uma linha:
php -r '$z=new ZipArchive; $z->open($argv[1]); for($i=0;$i<$z->numFiles;$i++) echo $z->getNameIndex($i),"\n";' tema.zip
Num Linux, o próprio aviso do unzip -l já entrega.
O que mudamos na nossa rotina
Zip de tema ou de plugin, aqui, não sai mais do Compress-Archive do Windows PowerShell. Testamos três caminhos que gravam certo: o PowerShell 7, o git archive --format=zip (que ainda tem a vantagem de levar só o que está versionado) e um script com o ZipArchive do PHP. E a listagem das entradas antes do envio virou passo fixo, junto com a versão no cabeçalho do style.css.
Para quem envia o mesmo pacote para vinte sites, o custo de um zip torto se multiplica por vinte. Dez segundos de conferência antes valem mais do que qualquer reversão depois.
Para ir além
- O que o visitante vê enquanto o seu site atualiza: a janela em que o pacote está sendo trocado
- Staging ou atualizar direto no ar?: onde testar o pacote antes
O pacote conferido antes de chegar ao site
No Sites Station, o envio de plugin por zip para vários sites confere o nome de cada entrada antes de mandar qualquer coisa: caminho com .., absoluto ou com barra invertida recusa o pacote inteiro, com a mensagem "O pacote traz um caminho inválido". Tema por zip o painel ainda não instala; para tema, a conferência continua sendo sua.
Comece o teste grátis e mande o próximo plugin para todos os sites de uma vez, sem abrir um wp-admin.