Corrigir problemas de upload de imagens

Comece com um PNG pequeno. Abra o painel Network do navegador, insira a imagem e acompanhe a requisição desde o upload até o documento salvo. Faça isso em um documento de teste, não no rascunho de um cliente.

Configuração inicial: escolha onde as imagens ficam

O editor insere o conteúdo; a sua aplicação armazena os arquivos enviados. Escolha uma pasta persistente ou um object storage, configure um endpoint de upload e retorne uma URL de imagem acessível pelo navegador. Um caminho no disco do servidor não é uma URL de imagem.

Comece pela demonstração executável para a linguagem do seu servidor.
Use a URL de upload ou o handler personalizado documentados para a versão instalada. Não registre handlers concorrentes.
Siga a configuração de armazenamento de arquivos para desativar a incorporação em Base64 quando a sua aplicação exigir imagens enviadas por upload.
Insira, cole e arraste uma imagem, separadamente. Salve, recarregue e abra a URL da imagem salva no mesmo contexto em que os leitores verão o documento.

Encontre o seu sintoma

Nenhuma requisição de upload aparece

Verifique o console em busca de erros de inicialização e confirme que o script do handler foi carregado antes de o editor usá-lo. Se o HTML contém uma origem data:image/, a imagem foi incorporada em vez de enviada. Verifique a configuração real do editor, não apenas o arquivo que você pretendia implantar.

401 ou 403: a requisição é rejeitada

Inspecione a autenticação, a validação de CSRF e a autorização da pasta. Uma página de login retornada com status 200 também é um upload que falhou. Para uploads entre origens diferentes, verifique a configuração de cookies e de CORS nas duas origens. Mantenha as verificações de acesso ativadas; use o fluxo de upload autenticado da sua aplicação.

413: o arquivo é grande demais

Verifique o proxy reverso, o servidor web, o limite de multipart do framework e o limite da aplicação. O menor limite prevalece. Teste logo abaixo e logo acima do limite pretendido. O redimensionamento no navegador pode reduzir fotografias, mas os limites do servidor ainda precisam proteger o endpoint.

Resposta 200, mas nenhuma imagem

Inspecione o corpo e o content type da resposta. Ela precisa seguir um formato de resposta suportado, e não ser uma mensagem de sucesso, uma página de erro em HTML ou um caminho do sistema de arquivos. Em um handler personalizado, chame o callback de conclusão uma única vez, com a URL salva ou com um erro.

O upload funciona, mas a URL da imagem retorna 404

Abra a URL retornada diretamente. Verifique o prefixo da URL pública, o diretório virtual, o nome do arquivo com diferenciação entre maiúsculas e minúsculas, o serviço de arquivos estáticos e o armazenamento persistente. Uma URL relativa pode ser resolvida em outro caminho na página publicada. Teste a URL tanto na página do editor quanto na página do leitor.

As imagens somem depois de um reinício ou de uma implantação

Verifique se os uploads foram gravados em um diretório temporário ou em um diretório da aplicação que é substituído. Use armazenamento persistente e inclua-o na sua política de backup. Uma implantação não deve substituir os uploads dos usuários por arquivos de um pacote de demonstração.

Verifique o documento salvo, não apenas a pré-visualização

Uma pré-visualização pode aparecer antes de o upload terminar. Leia o HTML enviado, o valor armazenado e o HTML retornado depois de recarregar. Confirme que a imagem aponta para a URL final. Uma URL blob: não resolvida pertence a uma sessão do navegador; não é armazenamento durável.

Se as imagens funcionam no editor, mas somem depois de salvar, verifique o momento do envio, a validação no servidor e a política de imagens do seu sanitizador de HTML. Não desative a sanitização para fazer uma imagem aparecer. Veja salvar texto rico com imagens.

Verificações para produção

Valide o tipo de arquivo, as dimensões decodificadas e o tamanho no servidor.
Gere os nomes de armazenamento; não confie em caminhos ou nomes de arquivo enviados.
Aplique permissões por usuário ou por tenant aos uploads e ao acesso à galeria.
Mantenha imagens privadas atrás de uma entrega autorizada; uma URL pública é pública mesmo quando a página do editor exige login.
Teste a rejeição, o cancelamento e uma conexão lenta, além do sucesso.

O que enviar ao suporte

Inclua a versão do editor, o framework, uma configuração mínima, a ação que falha, o status HTTP e uma resposta com dados sensíveis removidos. Informe se o problema acontece antes do upload, depois da inserção ou depois de salvar e recarregar. Remova cookies, tokens, URLs de imagens privadas e conteúdo de clientes antes de compartilhar logs.

Exemplos de servidor: ASP.NET Core, Web Forms e MVC, PHP. Experimente a demonstração de arrastar e soltar imagens.