[Solução de problemas comuns] Um resumo dos erros comuns no VSCode e como resolvê-los

Olá! Sou alguém que, sem nenhum conhecimento de programação, conseguiu criar um site por conta própria com a ajuda da IA. Eu entendo perfeitamente os seus momentos de "não entendo". Porque, há apenas alguns meses, eu estava exatamente no mesmo lugar, quebrando a cabeça.

Especialmente quando você está apenas começando com o VSCode (Visual Studio Code), o fluxo interminável de mensagens de erro pode ser realmente desanimador, certo? Você só pensa: "Eu só quero escrever um código...!"

Neste artigo, explicarei os erros mais comuns que realmente encontrei e superei no VSCode, detalhando as soluções de uma forma mais fácil de entender do que em qualquer outro lugar, evitando jargões o máximo possível. O objetivo é simples: ajudá-lo a experimentar aquele momento de "Funciona!". Depois de ler isto, os erros não serão mais assustadores. Vamos resolvê-los juntos, um por um!

[O Básico Absoluto] Os Três Tesouros da Solução de Problemas para Tentar Primeiro!

Antes de entrarmos em erros específicos, existem alguns "fundamentos" que quero que você tente primeiro, não importa o problema que esteja enfrentando. Você ficaria surpreso com quantos problemas podem ser resolvidos apenas com estes passos.

1. Antes de mais nada, "Reinicie"

Pode ser difícil de acreditar, mas esta é a solução mais eficaz. Se você pensar "Algo está errado", primeiro, feche completamente o VSCode e abra-o novamente. Se uma extensão não conseguiu carregar ou é apenas uma falha temporária, isso geralmente corrige o problema num instante. É como reiniciar o computador quando ele está com problemas.

2. Desative temporariamente todas as extensões

O VSCode é tão útil graças às suas "extensões" convenientes. No entanto, às vezes, essas extensões podem entrar em conflito umas com as outras e causar erros inesperados.

Para verificar se uma extensão é a causa, o recurso "Bissecção de Extensão" é muito útil.

Abra a Paleta de Comandos (mac: Cmd + Shift + P, Win: Ctrl + Shift + P).
Digite >Extensions: Bisect e execute.
Siga as instruções na tela, e o VSCode desativará automaticamente as extensões pela metade, ajudando você a identificar a extensão problemática.

Se isso resolver o problema, então uma de suas extensões é a culpada. Assim que encontrar a extensão problemática, desative-a ou reveja suas configurações.

3. Isole o problema

Tente se lembrar "desde quando" e "após que ação" este erro começou a aparecer.

Logo após instalar uma nova extensão?
Apenas ao abrir um arquivo específico?
Está tudo bem com arquivos HTML, mas o erro aparece em arquivos JavaScript?

Ser capaz de identificar as condições sob as quais o problema ocorre é um atalho para resolvê-lo.

[Por Cenário] Os Erros que Me Fizeram Chorar... Problemas Comuns e Soluções de Copiar e Colar

A partir daqui, apresentarei erros específicos que realmente encontrei durante o desenvolvimento do meu site e que demorei um pouco para resolver. Tenho certeza de que você encontrará o erro que está na sua tela agora.

Caso 1: Texto ilegível! O Erro de "Mojibake"

Você pensou que tinha escrito em seu arquivo HTML, mas quando o visualiza no navegador, ele se transforma em símbolos misteriosos como ï¿½ï¿½ï¿½... Este é um erro de "mojibake" (texto ilegível), um caminho que todo iniciante deve percorrer.

Causa:
Isso é causado por uma incompatibilidade entre a "codificação de caracteres" em que o arquivo é salvo e a codificação de caracteres que o navegador assume que está sendo usada. No passado, formatos como Shift_JIS eram comuns no Japão, mas agora o padrão global é UTF-8.

Solução:
Vamos alterar as configurações do VSCode para salvar todos os arquivos futuros em UTF-8. Uma vez que você definir isso, nunca mais terá que se preocupar com texto ilegível.

No mac, pressione Cmd + , (vírgula), e no Windows, pressione Ctrl + , (vírgula) para abrir as configurações. Em seguida, clique no ícone do arquivo no canto superior direito para abrir settings.json e cole o seguinte código.

{
  // Configurações relacionadas a arquivos
  "files.encoding": "utf8", // Define a codificação de caracteres padrão para UTF-8 ao abrir arquivos
  "files.autoGuessEncoding": true, // Adivinha automaticamente a codificação de caracteres ao abrir arquivos
  "files.eol": "\n" // Unifica o final da linha para LF (\n)
}

Se já houver algo escrito dentro de {}, basta adicionar os itens de configuração (como "files.encoding": "utf8",) dentro.

Caso 2: Comando não funciona! O Erro "command not found"

No desenvolvimento web, você geralmente usa comandos como npm e git no terminal embutido do VSCode. No entanto, às vezes, ao digitar um comando, você recebe um erro como zsh: command not found: npm, como se estivesse dizendo "Não conheço esse comando".

Causa:
Isso ocorre porque o comando (programa) não está instalado no seu computador, ou está instalado, mas o seu computador não sabe onde ele está (ou seja, o PATH não está configurado).

Solução:
Primeiro, vamos verificar se ele está realmente instalado. Por exemplo, para o Node.js (que inclui o comando npm), tente digitar o seguinte comando no terminal.

node -v

Se um número de versão (por exemplo, v20.11.0) for exibido, ele está instalado. Se você receber command not found, significa que não está instalado. Instale-o a partir do site oficial do Node.js.

Se você ainda receber o erro mesmo que ele esteja instalado, tente reiniciar o VSCode. Imediatamente após a instalação, o VSCode pode não ter reconhecido o novo PATH.

Caso 3: O código não formata! Prettier / ESLint não funcionam

No momento em que você salva um arquivo, seu código bagunçado é magicamente formatado... Isso é possível graças a formatadores/linters como Prettier e ESLint. Mas uma frustração comum é quando você o configurou, mas ele não está funcionando de jeito nenhum!

Causa:
Existem várias razões possíveis.
1. A extensão Prettier ou ESLint para o VSCode não está instalada ou está desativada.
2. O projeto não possui arquivos de configuração (.prettierrc, .eslintrc.js).
3. "Formatar ao Salvar" não está ativado nas configurações do VSCode.
4. Vários formatadores estão em conflito.

Solução:
Tente copiar e colar as seguintes configurações no arquivo settings.json que mencionamos anteriormente. Esta é uma configuração "tudo-em-um" que deve resolver todos os tipos de problemas. Esta configuração me salvou inúmeras vezes quando eu estava construindo meu site.

{
  // ----- Configurações para Formatação e Linting -----

  // Define o Prettier como o formatador padrão
  // Isso evita conflitos com outros formatadores
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // Executa a formatação automaticamente ao salvar o arquivo
  "editor.formatOnSave": true,

  // Especifica os tipos de arquivo que o ESLint deve verificar e corrigir
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // Também executa a correção automática do ESLint ao salvar o arquivo
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

【Ponto Chave】
A parte mais importante é "editor.defaultFormatter": "esbenp.prettier-vscode". O VSCode possui seus próprios recursos de formatação de código. Portanto, quando você instala a extensão Prettier, ele pode ficar confuso sobre quais instruções seguir. Esta única linha declara: "Quando se trata de formatação, deixo tudo para o Sr. Prettier!", o que evita conflitos.

Claro, isso pressupõe que você tenha as extensões Prettier e ESLint instaladas!

Caso 4: Importação não encontrada! O Erro "Cannot find module"

Ao desenvolver com JavaScript ou TypeScript, você usa import para carregar componentes (módulos) de outros arquivos. Às vezes, você pode receber um erro como Cannot find module './components/Button'.

Causa:
Isso é quase sempre um simples erro de especificação de caminho. No entanto, à medida que os projetos se tornam mais complexos, caminhos relativos como ../../../../utils/helper.js podem se aprofundar cada vez mais, tornando-os fáceis de errar (eu chamo isso de "Inferno dos ('../')").

Solução:
Para escapar deste "Inferno dos ('../')", vamos criar um arquivo de configuração chamado jsconfig.json (ou tsconfig.json para TypeScript). Este arquivo diz ao VSCode: "Este é o local base (raiz) do projeto".

Crie um arquivo chamado jsconfig.json no nível superior do seu projeto (o mesmo nível do package.json) e cole o seguinte conteúdo.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "exclude": ["node_modules"]
}

【Ponto Chave】
Qual é a grande vantagem desta configuração? Por exemplo, digamos que você queira importar um arquivo de src/components/ui/Button.jsx para src/pages/index.js, que está em um diretório completamente diferente.

Antes: import Button from '../../components/ui/Button'; (Fácil de errar o caminho...)
Depois: import Button from '@/components/ui/Button'; (@ aponta para a pasta src, então você sempre pode escrever da mesma forma!)

Com isso, você quase nunca precisará modificar suas declarações de import, mesmo que mova os arquivos. Isso é verdadeiramente revolucionário!

[Avançado] Não Tenha Mais Medo! Como Perguntar à IA Quando Ocorrer um Erro

A razão pela qual consegui construir um site sozinho do zero é, sem dúvida, graças aos assistentes de IA. Mesmo que você receba uma mensagem de erro, não há necessidade de entrar em pânico. É o melhor "material" para fazer uma pergunta à IA.

Mas apenas copiar e colar a mensagem de erro nem sempre lhe dará uma boa resposta. Existe um truque para fazer perguntas para obter boas respostas.

O Modelo de Pergunta Definitivo

Quando encontrar um erro, tente perguntar à IA usando o seguinte modelo.

Assunto: Encontrado [Conteúdo do Erro] em [Tecnologia Usada]

1. Contexto/Objetivo:
(por exemplo, estou tentando importar um componente usando Next.js e TypeScript.)

2. Problema Ocorrendo:
(por exemplo, quando executo npm run dev, a seguinte mensagem de erro é exibida no terminal.)

Cole a mensagem de erro aqui exatamente como ela é

3. Código Relevante:
(por exemplo, aqui está a parte relevante do código do arquivo onde o erro está ocorrendo.)

Cole o código aqui

4. O que eu tentei:
(por exemplo, tentei executar novamente npm install e reiniciar o VSCode, mas não resolveu o problema.)

5. Pergunta:
Por favor, diga-me a causa raiz deste erro e os passos específicos para resolvê-lo.

Ao transmitir "o que você estava tentando fazer", "o que aconteceu" e "o que você tentou" como um conjunto, a IA pode entender com precisão a situação e fornecer uma solução precisa. Os logs de erro são um tesouro de dicas. Por todos os meios, faça da IA sua melhor parceira.

Resumo

Neste artigo, expliquei os erros comuns com os quais os iniciantes tropeçam no VSCode e suas soluções específicas, com base em minhas próprias experiências.

Erros são uma parte inevitável do aprendizado da programação. Mas cada erro tem uma causa e uma maneira de ser resolvido. Uma mensagem de erro não é sua inimiga; é um sinal amigável que lhe diz: "Esta parte está errada!".

Eu ficaria muito feliz se este artigo ajudasse a transformar seu "não entendo" em "entendi!". Cada vez que você supera um erro, você está definitivamente subindo de nível. Tenha confiança e divirta-se programando!