Falhas de upload de arquivos: diagnóstico e soluções práticas

Tim Koschützki

Cofundador · Berlim, Alemanha ·

Uploads de arquivos são parte fundamental de muitas aplicações web, mas muitas vezes viram fonte de frustração quando as coisas não saem como planejado. Entender os motivos mais comuns por trás das falhas de upload e saber diagnosticar e resolver esses problemas rapidamente pode economizar muito tempo e dor de cabeça.

Motivos comuns para erros de upload de arquivos

Falhas de upload de arquivos costumam ter origem em alguns problemas comuns:

Limites de tamanho de arquivo: servidores costumam impor um tamanho máximo de arquivo.
Conectividade de rede: conexões instáveis ou lentas podem interromper uploads.
Compatibilidade de formato de arquivo: servidores podem rejeitar tipos de arquivo não suportados.
Problemas de armazenamento no servidor: falta de espaço em disco ou limites de cota podem interromper uploads.
Configurações incorretas do servidor: ajustes errados no servidor podem impedir que os uploads sejam concluídos.

Como diagnosticar problemas de upload de arquivos com ferramentas

Um diagnóstico eficaz começa com as ferramentas certas:

Ferramentas de desenvolvedor do navegador: inspecione as requisições de rede para identificar códigos de status HTTP e mensagens de erro.
Logs do servidor: verifique os logs em busca de mensagens de erro detalhadas relacionadas a uploads de arquivos.
Ferramentas de monitoramento: use ferramentas como Prometheus ou Grafana para monitorar os recursos do servidor e detectar problemas de armazenamento ou de memória.

Considerações de segurança para uploads de arquivos

Uploads de arquivos representam riscos de segurança significativos se não forem tratados corretamente. Siga estas boas práticas de segurança:

Valide as extensões de arquivo: mantenha uma lista de extensões permitidas em vez de uma lista de bloqueio.
Verifique o conteúdo do arquivo: use bibliotecas de validação de conteúdo para confirmar o tipo do arquivo.
Renomeie os arquivos enviados: gere nomes de arquivo aleatórios para evitar ataques de directory traversal.
Armazene os arquivos fora do webroot: guarde os arquivos enviados em um local que não seja acessível diretamente pelo servidor web.
Faça varredura contra malware: implemente uma verificação antivírus para os arquivos enviados.
Implemente Content Disarm & Reconstruction (CDR): neutralize conteúdo potencialmente malicioso em documentos.

Medidas preventivas para evitar erros de upload de arquivos

Adotar medidas preventivas pode reduzir bastante os problemas de upload:

Documente e comunique com clareza aos usuários as restrições de tamanho e de formato de arquivo.
Implemente validação no lado do cliente para detectar problemas antes que os arquivos cheguem ao servidor.
Monitore e gerencie regularmente a capacidade de armazenamento do servidor.
Configure os servidores corretamente, garantindo permissões e ajustes adequados.

Soluções passo a passo para corrigir erros comuns de upload

Limites de tamanho de arquivo

Ajuste as configurações no lado do servidor (por exemplo, upload_max_filesize e post_max_size no PHP). Implemente uploads em partes (chunks) para lidar com arquivos grandes de forma eficiente.

Como implementar uploads em partes

Em um endpoint de partes personalizado, aguarde cada resposta antes de enviar a próxima parte e interrompa o envio em caso de erros HTTP. O exemplo a seguir pressupõe um <input id="file-upload" type="file"> existente e endpoints de servidor que autenticam cada requisição, isolam os uploads por ID, validam offsets e tamanhos totais e só finalizam arquivos completos. Ele demonstra o tratamento de erros, não um protocolo retomável completo. Ao criar um novo uploader retomável, use um servidor e um cliente tus consolidados.

const fileInput = document.getElementById('file-upload')
fileInput.addEventListener('change', (event) => {
  handleFileUpload(event).catch(() => {
    console.error('Upload failed; check the network response and server logs')
  })
})

async function handleFileUpload(event) {
  const file = event.target.files?.[0]
  if (!file) return
  const uploadId = crypto.randomUUID()
  const chunkSize = 1024 * 1024 // 1MB chunks
  let start = 0

  while (start < file.size) {
    await uploadChunk(file.slice(start, start + chunkSize), start, file, uploadId)
    start += chunkSize
  }
  const response = await fetch('/upload-complete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ uploadId, fileName: file.name, totalSize: file.size }),
  })
  if (!response.ok) throw new Error(`Upload finalization failed: ${response.status}`)
}

async function uploadChunk(chunk, start, file, uploadId) {
  const formData = new FormData()
  formData.append('file', chunk)
  formData.append('start', start)
  formData.append('fileName', file.name)
  formData.append('uploadId', uploadId)
  formData.append('totalSize', file.size)

  const response = await fetch('/upload-chunk', { method: 'POST', body: formData })
  if (!response.ok) throw new Error(`Chunk upload failed: ${response.status}`)
}

Problemas de conectividade de rede

Implemente uploads retomáveis usando protocolos como o tus.io.

Como implementar uploads retomáveis com tus.io

Instale o tus-js-client:

npm install tus-js-client

Implementação básica, com file obtido de um input de arquivo e um endpoint tus configurado:

import { Upload } from 'tus-js-client'

const upload = new Upload(file, {
  endpoint: 'https://your-tus-server.com/files/',
  retryDelays: [0, 1000, 3000, 5000],
  onError: () => console.error('Upload failed after retries'),
})
upload.findPreviousUploads().then((previousUploads) => {
  if (previousUploads.length > 0) upload.resumeFromPreviousUpload(previousUploads[0])
  upload.start()
}).catch(() => console.error('Unable to initialize the upload'))

Compatibilidade de formato de arquivo

Especifique com clareza os formatos suportados e valide os tipos de arquivo tanto no lado do cliente quanto no do servidor.

Problemas de armazenamento no servidor

Monitore regularmente o uso de disco e automatize a limpeza de arquivos temporários.

Configurações incorretas do servidor

Audite regularmente as configurações do servidor e use ferramentas como Ansible ou Terraform.

Conclusão e recursos adicionais

Entender e tratar falhas de upload de arquivos de forma proativa melhora a confiabilidade e a experiência do usuário. Para saber mais, consulte o MDN Web Docs e o tus.io.

Para um tratamento robusto de uploads de arquivos, considere o serviço de uploads de arquivos da Transloadit.