O HTML funciona localmente, mas perde imagens no link? Seis testes de URL

Uma imagem que aparece no computador pode sumir quando o HTML é publicado em um subdiretório. Antes de trocar de hospedagem, vale conferir qual endereço o navegador está tentando carregar.

Estou desenvolvendo o Plopino, uma ferramenta para compartilhar páginas HTML por link. O problema abaixo é relevante nesse contexto, mas a explicação e os testes também servem para outros serviços de hospedagem estática.

A barra muda o destino

Considere esta estrutura:

index.html
assets/
  logo.svg
  site.css
pages/
  details.html

Se a página está em https://example.com/b/demo/, o caminho /assets/logo.svg aponta para a raiz do domínio. Já ./assets/logo.svg aponta para a pasta assets dentro de /b/demo/.

Outro detalhe: /b/demo e /b/demo/ não são a mesma base para resolver uma referência relativa. O servidor pode redirecionar uma forma para a outra, mas é preciso conferir o endereço final no navegador.

Seis casos reproduzíveis

Salve como check-paths.mjs e execute com Node.js:

import assert from 'node:assert/strict';

const cases = [
  ['https://example.com/b/demo/', '/assets/logo.svg', '/assets/logo.svg'],
  ['https://example.com/b/demo/', './assets/logo.svg', '/b/demo/assets/logo.svg'],
  ['https://example.com/b/demo/', 'assets/logo.svg', '/b/demo/assets/logo.svg'],
  ['https://example.com/b/demo/pages/details.html', '../assets/logo.svg', '/b/demo/assets/logo.svg'],
  ['https://example.com/b/demo/assets/site.css', './logo.svg', '/b/demo/assets/logo.svg'],
  ['https://example.com/b/demo', './assets/logo.svg', '/b/assets/logo.svg'],
];

for (const [base, reference, expected] of cases) {
  const actual = new URL(reference, base).pathname;
  assert.equal(actual, expected);
  console.log(reference + ' + ' + base + ' => ' + actual);
}
console.log(cases.length + ' URL checks passed');

Executei os seis casos acima e a saída final foi 6 URL checks passed. Eles cobrem caminhos a partir da raiz, caminhos relativos, uma página em uma subpasta, uma folha de estilos externa e uma base sem a barra final.

No CSS externo, referências relativas dentro de url() usam a URL da própria folha de estilos como base. No HTML com um elemento base, também é necessário conferir document.baseURI: a URL da página pode não ser a base efetiva.

Limite do teste: isso verifica o cálculo das URLs. Não comprova que os arquivos existem, que o servidor permite acessá-los ou que as imagens renderizam.

Depois do cálculo, confira a resposta

Na aba Network do navegador, selecione a requisição que falhou e compare:

• Caminho diferente do esperado: confira a barra inicial, a base efetiva e a pasta da página ou do CSS.
• Caminho correto com 404: compare a estrutura enviada e as letras maiúsculas/minúsculas do nome do arquivo.
• Status 200 com uma página HTML: examine o corpo da resposta e o Content-Type. Uma página de fallback não é o SVG ou CSS solicitado.
• Redirecionamento para login ou acesso negado: investigue a permissão de compartilhamento separadamente do caminho do recurso.

Alterar uma causa por vez ajuda a não misturar um problema de URL com outro de arquivos ou permissões.

Teste o que o destinatário vai receber

Abra o link final em um navegador sem login. Confira uma imagem, uma interação importante e o layout em uma janela estreita. O preview local não demonstra o que outra pessoa consegue acessar.

Também vale enviar uma pergunta específica junto do link: “Esta é a versão de 9 de outubro. Selecione o pacote completo e confira se os itens de entrega correspondem ao escopo.” Se a página puder ser atualizada mantendo o endereço, registre a versão revisada separadamente quando isso for importante. Um link estável não é um registro de aprovação.

Referência: MDN — resolução de referências relativas.

Texto organizado com auxílio de IA. As seis asserções de URL foram executadas; o exemplo não representa um teste completo de hospedagem nem um caso de cliente.