Upload em lote WordPress por FTP: registre na biblioteca

Você sobe 800 imagens por FTP para a pasta uploads/2025/03/, abre a biblioteca de mídia e não encontra nenhuma. O WordPress não varre a pasta: ele só lista o que está registrado na tabela de posts como anexo. Fazer upload em lote no WordPress, então, não é copiar arquivos, é copiar e registrar cada um. Este artigo mostra o caminho completo: enviar por FTP, registrar por linha de comando com wp media import e conferir depois se os anexos ficaram vinculados corretamente.

Por que os arquivos somem depois do upload em lote WordPress

A biblioteca de mídia não é um explorador de arquivos. Ela é uma consulta ao banco de dados que busca posts do tipo attachment. Cada anexo tem um registro com caminho, tipo MIME, dimensões e metadados de tamanhos gerados. Se o arquivo existe no disco mas não tem esse registro, ele é invisível no painel, não aparece em buscas e não pode ser inserido em posts.

Além disso, o WordPress organiza uploads por ano e mês. A pasta wp-content/uploads/2025/03/ só é criada quando um upload acontece naquele mês. Jogar arquivos em uma pasta que não segue esse padrão faz com que o registro aponte para um caminho que o WordPress não espera. Por isso, o passo de registro precisa saber exatamente onde o arquivo está.

Quando o upload em lote pela interface não serve

A biblioteca de mídia aceita arrastar vários arquivos, mas tem limites práticos: o upload_max_filesize e o post_max_size do PHP, o tempo de execução e a própria conexão. Acima de algumas centenas de arquivos, a aba costuma travar ou abortar no meio, deixando anexos quebrados. Para catálogos grandes, migrações ou entrega de site com muitas fotos, o caminho por FTP e WP-CLI é mais estável.

O que você precisa ter em mãos

• Acesso FTP ou SFTP ao servidor, com permissão de escrita em wp-content/uploads/.
• Acesso SSH para rodar WP-CLI. Sem SSH, o caminho muda (veja a seção sobre hospedagem compartilhada).
• Os arquivos nomeados sem espaços, acentos ou caracteres especiais. Isso evita problemas de codificação no registro.

Passo a passo: enviar por FTP e registrar com wp media import

O fluxo abaixo funciona em qualquer site com WP-CLI instalado. A ideia é separar o envio físico do registro no banco, para que você possa repetir o registro sem reenviar os arquivos.

1. Confirme o caminho de uploads. Rode wp option get upload_path e wp option get upload_url_path. Se estiverem vazios, o padrão é wp-content/uploads com subpastas por ano e mês. Anote o caminho absoluto: wp eval 'echo wp_upload_dir()["basedir"];'.
2. Crie a pasta do mês. Se o lote é de março de 2025, crie wp-content/uploads/2025/03/ no servidor. Use o mesmo padrão que o WordPress usaria, para que o registro aponte para o lugar certo.
3. Envie os arquivos por FTP. Coloque todos na pasta do mês. Não misture subpastas de tamanhos gerados (como -150x150), porque o WordPress vai gerar esses recortes sozinho no momento do registro.
4. Registre cada arquivo com WP-CLI. O comando é wp media import. Para importar todos os arquivos de uma pasta de uma vez, use:
   wp media import wp-content/uploads/2025/03/*.jpg --porcelain
   A opção --porcelain faz o comando imprimir apenas os IDs criados, o que ajuda a conferir depois. Repita para outros formatos, como *.png e *.webp.
5. Vincule a um post, se for o caso. Se as imagens pertencem a um post específico, acrescente --post_id=123 ao comando. Isso define o anexo como filho daquele post, o que faz diferença em temas que usam galerias vinculadas.
6. Confira os anexos. Liste os últimos registros com wp post list --post_type=attachment --posts_per_page=20 --fields=ID,post_title,guid. O campo guid mostra a URL final. Se algum arquivo não aparecer, o registro falhou e o erro costuma estar no caminho.

Na prática, o comando wp media import aceita tanto um arquivo único quanto um padrão com curinga. Ele copia o arquivo para a pasta de uploads se você apontar para um caminho fora dela, mas, se o arquivo já está na pasta correta, o registro é feito no lugar. Isso evita duplicar o arquivo no disco.

Como conferir se os anexos ficaram vinculados

Depois do lote, três verificações resolvem a maior parte dos problemas:

Se a contagem não bate, o problema costuma ser permissão de leitura na pasta ou arquivo com nome inválido. Renomeie e rode o comando de novo apenas para os que faltaram.

O que fazer quando você só tem o painel da hospedagem

Sem SSH, o WP-CLI não roda. Nesse caso, o caminho é instalar um plugin de importação de mídia que varra a pasta de uploads e crie os registros. A lógica é a mesma: ele lê os arquivos e insere cada um como anexo. O risco é que plugins assim variam em qualidade e alguns não geram os metadados de tamanhos, o que faz o site servir a imagem original em vez do recorte adequado.

Outra alternativa é enviar por FTP e depois usar a própria biblioteca de mídia para subir os mesmos arquivos em lotes pequenos. É mais lento, mas evita depender de um plugin que talvez não seja mantido. Em ambos os casos, faça backup do banco antes, porque o registro mexe na tabela de posts e postmeta.

Erros comuns que quebram o lote

• Enviar para a pasta errada. Se o arquivo não está em uploads/ano/mes/, o registro aponta para um caminho que o WordPress não resolve. Confira o basedir antes.
• Nome com espaço ou acento. O FTP aceita, mas a URL gerada pode quebrar em alguns servidores. Renomeie antes de enviar.
• Rodar o comando sem --porcelain. Você perde a lista de IDs e não consegue conferir o que entrou.
• Esquecer de gerar os tamanhos. O wp media import costuma gerar os recortes, mas se o tema mudou de tamanhos depois, os antigos não existem. Rode wp media regenerate se necessário.
• Não testar em um site antes. Em uma rede de vários sites, o mesmo comando precisa ser rodado em cada instalação, com o caminho de uploads de cada uma.

Como fazer upload em lote WordPress em vários sites sem abrir o painel de cada um

Se você administra dez sites, o trabalho se multiplica: são dez pastas de uploads, dez bancos e dez execuções de WP-CLI. O caminho é automatizar o envio por SFTP e o registro por SSH em lote, com um script que percorre a lista de sites. A parte crítica é não misturar os arquivos: cada site tem seu próprio wp-content/uploads e seu próprio prefixo de tabela.

Para quem precisa repetir esse tipo de operação com frequência, um painel de gestão de vários sites WordPress centraliza o acesso e evita que você abra o gerenciador de arquivos de cada hospedagem. O 100% WP reúne atualizações, backups e monitoramento em um só lugar, o que reduz o risco de esquecer um site no meio de uma migração de mídia.

Antes de rodar o lote em produção, teste em um ambiente de staging. Se o site faz parte de uma entrega para cliente, vale seguir um checklist de handover para não deixar arquivos órfãos na biblioteca. Em migrações maiores, o mesmo cuidado se aplica ao exportar sites WordPress em lote, que também lida com muitos arquivos de uma vez.

Prevenção para o próximo upload em lote WordPress

Padronize o nome dos arquivos antes do envio, com minúsculas e hífens. Mantenha uma pasta local com o lote original, para poder reenviar se algo falhar. E registre em algum lugar quantos arquivos foram enviados e quantos anexos foram criados: essa diferença é o primeiro sinal de que algo ficou para trás.

Se o volume de arquivos é grande e recorrente, considere usar um CDN ou um serviço de armazenamento externo para as imagens, deixando a biblioteca do WordPress apenas com os registros. Isso muda a forma de registrar, mas reduz o peso no servidor.

Quando chamar alguém

Se o lote envolve milhares de arquivos, se o site está em produção e não há staging, ou se você não tem SSH nem acesso ao banco, é mais seguro pedir ajuda a quem já fez isso antes. Um erro de caminho no registro pode criar centenas de anexos quebrados, e limpar isso depois dá mais trabalho do que fazer certo na primeira vez.

Fonte: Documentação oficial do WordPress