Você abre o console, e antes de qualquer coisa da sua aplicação rodar lá estão quatro linhas vermelhas sobre source maps que não conseguiram carregar. O instinto é ir procurar a configuração da sua build, porque as palavras nomeiam uma coisa que a build produz.

Esse é geralmente o lugar errado, e a razão é importante saber, porque leva uns dez segundos para dizer de quem é o problema e a maioria das pessoas nunca aprende o truque.

O que está sendo pedido na verdade

Um arquivo minificado pode carregar um apontador para um mapa que o traduz de volta para o código fonte de que foi feito. Existem duas maneiras de anexar um.

A forma comum é um comentário no fim do arquivo, //# sourceMappingURL=bundle.js.map. A outra é um header HTTP, e a MDN é bem específica sobre qual vence: o header SourceMap “tem precedência sobre uma anotação de fonte (sourceMappingURL=path-to-map-js.map), e se ambos estiverem presentes, a URL do header é usada para resolver o arquivo do source map.” Existe também um header X-SourceMap mais antigo, que é obsoleto.

Para o que o mapa serve é igualmente específico. Nas palavras da MDN, “As ferramentas de desenvolvedor usam o source map para reconstruir o código fonte original a partir do JavaScript otimizado retornado na resposta, permitindo que os desenvolvedores façam debug do código original em vez do formato que foi otimizado para envio.”

Quem faz a requisição, que é o primeiro fato útil

A própria documentação do Chrome responde isso numa sentença: “Quando você abre DevTools, ele tenta carregar source maps, se houver.”

Então a requisição é feita pelas suas ferramentas de desenvolvedor, na sua máquina, porque você as abriu. Um visitante com o console fechado não busca esses arquivos e não vê essas linhas. Tudo o que isso está custando, não está custando para eles.

Só isso descarta a maior parte do pânico. Uma página não está quebrada por isso, nada fica mais lento para ninguém, e nenhum comportamento voltado para o usuário depende disso.

Por que geralmente não é seu

Aqui está a parte que economiza a tarde.

O apontador vive dentro do arquivo que foi entregue. Se esse arquivo saiu da sua própria build, o apontador é seu e o mapa ausente também é. Mas uma grande parte dessas linhas vem de código que você não escreveu: um pacote que foi publicado no npm com o comentário sourceMappingURL deixado dentro e o arquivo .map deixado fora, porque o publicador o excluiu do pacote para manter o download pequeno.

O seu bundler copiou esse comentário fielmente, porque é um comentário num arquivo que foi pedido para incluir. Não há nada na sua configuração que o produziu e nada lá que possa corrigi-lo.

Então leia a URL no erro antes de mudar qualquer coisa. Se o caminho aponta para a sua saída de build, é seu. Se aponta dentro de um chunk de vendor, um caminho node_modules, ou um CDN que você não controla, é uma decisão de empacotamento de outra pessoa e suas opções são ignorar ou parar de carregá-lo.

As três coisas que realmente causam isso

O mapa nunca foi publicado. O caso mais comum, e o de cima. Nada para consertar.

O mapa existe mas a requisição não consegue passar. O Chrome nota que requisições de source map “podem ser tratadas como cross-origin e não conseguir passar”, que é o caso que vale conhecer porque parece idêntico no console e não é um arquivo ausente em tudo. Um mapa em uma origem diferente sem headers permissivos falha da mesma forma que um que nunca foi enviado.

O mapa foi deliberadamente não implantado. Muitos times constroem mapas e mantêm fora do diretório público de propósito, para que o código fonte original não seja baixável por ninguém que abra as ferramentas de desenvolvedor. Essa é uma escolha defensável, e a linha do console é seu custo.

Pare de adivinhar e leia a lista

O Chrome tem um painel que responde isso por arquivo em vez de deixar você casar linhas do console com bundles. Developer Resources mostra uma coluna Status, para ver se o carregamento teve êxito ou falhou, e uma coluna Error com a mensagem para cada um. Também deixa você carregar um mapa na mão, que é como você verifica que um mapa que você manteve privado está correto.

Aquela lista é a diferença entre “o console está cheio de erros de source map” e “três desses são de uma dependência e um é nosso”.

O que fazer, em ordem

Se pertence a uma dependência: nada. É ruído gerado pela sua própria ferramenta sobre o empacotamento de outra pessoa. Nenhum usuário é afetado e nenhuma mudança de build vai removê-lo.

Se é seu e você quer mapas funcionando, envie o arquivo .map ao lado do bundle, ou mantenha privado e envie para o seu rastreador de erros, que é onde ganha mais e expõe menos. Um stack trace contra código minificado é quase inútil, e esse é o arquivo que conserta isso.

Se você só quer o console silencioso, a configuração fica em DevTools em vez de no seu projeto: Settings, depois Preferences, depois Sources, onde a documentação do Chrome aponta para a checkbox JavaScript source maps. Desligá-lo impede as requisições e as linhas junto com elas.

O custo que ninguém conta

Um console com uma dúzia de avisos permanentes nele não é gratuito, e o preço não é performance.

É que todos aprendem a ignorar. Quando o console sempre tem vermelho nele, vermelho para de ser um sinal, e a única linha que importa chega no meio de onze que não importam. O erro sobre uma propriedade indefinida que explica o checkout quebrado está sentado quatro linhas abaixo de um aviso de source map que está lá desde março.

Isso importa mais quando outra pessoa está fazendo a procura. Uma captura de tela de um console de um usuário, ou um log capturado anexado a um relato de bug, chega com tudo isso nele, e a pessoa lendo precisa saber quais linhas são móvel permanente antes de conseguir ver o que é novo.

Session Replay

Extensão gratuita para Chrome. Um clique na página que está com problema captura a tela, o console e o log de rede, e te devolve um link para colar no ticket.

Baixe a extensão

Saber quais dessas linhas sempre iam estar lá é o maior parte do que torna um console capturado legível.

A versão resumida

  • A requisição é feita pelas suas ferramentas de desenvolvedor quando você as abre, não pela página. Nenhum visitante vê isso e nada fica mais lento para eles.
  • Leia a URL na mensagem primeiro. Um caminho node_modules ou vendor significa que é empacotamento de uma dependência, e não há nada na sua build para mudar.
  • Um mapa cross-origin falha de um jeito que parece exatamente como um ausente.
  • Developer Resources lista o status e o erro por arquivo, o que bate ler linhas do console.
  • A checkbox que o silencia é uma preferência de DevTools, não uma configuração de projeto.
  • O custo real é um console que ninguém lê cuidadosamente mais, incluindo a pessoa que você o enviou para.