[Solución de problemas comunes] Resumen de errores frecuentes en VSCode y cómo solucionarlos

¡Hola! Soy alguien que, partiendo de cero conocimientos de programación, ha conseguido crear un sitio web de forma autodidacta con la ayuda de la IA. Entiendo perfectamente vuestro "no lo entiendo". Porque hace solo unos meses, yo estaba en el mismo lugar, rompiéndome la cabeza.

Especialmente al empezar a usar VSCode (Visual Studio Code), la sucesión interminable de mensajes de error puede ser realmente desalentadora, ¿verdad? Y tú solo piensas: "¡Si yo solo quiero escribir código!".

En este artículo, explicaré los errores más comunes con los que me encontré y que superé en VSCode, desglosando las soluciones de una manera más fácil de entender que en cualquier otro lugar, evitando la jerga tanto como sea posible. El objetivo es simple: ayudaros a experimentar ese momento de "¡Funciona!". Después de leer esto, los errores ya no darán miedo. ¡Vamos a solucionarlos juntos, uno por uno!

[Lo más básico] ¡Los tres tesoros de la solución de problemas que debes probar primero!

Antes de entrar en errores específicos, hay algunos "fundamentos" que quiero que probéis primero, sin importar el problema al que os enfrentéis. Os sorprenderá la cantidad de problemas que se pueden resolver solo con estos pasos.

1. Ante todo, "Reiniciar"

Puede que sea difícil de creer, pero esta es la solución más eficaz. Si piensas "Algo va mal", primero, cierra completamente VSCode y vuelve a abrirlo. Si una extensión no se cargó correctamente o es solo un fallo temporal, esto a menudo lo soluciona en un instante. Es como reiniciar el ordenador cuando no funciona bien.

2. Desactiva temporalmente todas las extensiones

VSCode es tan útil gracias a sus prácticas "extensiones". Sin embargo, a veces estas extensiones pueden entrar en conflicto entre sí y causar errores inesperados.

Para comprobar si una extensión es la causa, la función "Bisección de extensiones" es muy útil.

Abre la Paleta de comandos (mac: Cmd + Shift + P, Win: Ctrl + Shift + P).
Escribe >Extensions: Bisect y ejecútalo.
Sigue las instrucciones en pantalla y VSCode desactivará automáticamente las extensiones por la mitad, ayudándote a identificar la extensión problemática.

Si esto soluciona el problema, entonces una de tus extensiones es la culpable. Una vez que encuentres la extensión problemática, desactívala o revisa su configuración.

3. Aislar el problema

Intenta recordar "desde cuándo" y "después de qué acción" comenzó a aparecer este error.

¿Justo después de instalar una nueva extensión?
¿Solo al abrir un archivo específico?
¿Funciona bien con archivos HTML, pero el error aparece en archivos JavaScript?

Ser capaz de identificar las condiciones en las que ocurre el problema es un atajo para resolverlo.

[Por situación] Los errores que me hicieron llorar... Problemas comunes y soluciones de copiar y pegar

A partir de aquí, presentaré errores específicos que encontré realmente durante el desarrollo de mi sitio web y que me llevaron un tiempo resolver. Estoy seguro de que encontrarás el error que tienes en tu pantalla ahora mismo.

Caso 1: ¡Texto corrupto! El error "Mojibake"

Creías que habías escrito en tu archivo HTML, pero cuando lo ves en el navegador, se convierte en símbolos misteriosos como ï¿½ï¿½ï¿½... Este es un error de "mojibake" (texto corrupto), un camino por el que todo principiante debe pasar.

Causa:
Esto se debe a una discrepancia entre la "codificación de caracteres" en la que se guarda el archivo y la codificación de caracteres que el navegador asume que se está utilizando. En el pasado, formatos como Shift_JIS eran comunes en Japón, pero ahora el estándar global es UTF-8.

Solución:
Cambiemos la configuración de VSCode para guardar todos los archivos futuros en UTF-8. Una vez que configures esto, nunca más tendrás que preocuparte por el texto corrupto.

En mac, presiona Cmd + , (coma), y en Windows, presiona Ctrl + , (coma) para abrir la configuración. Luego, haz clic en el icono de archivo en la esquina superior derecha para abrir settings.json y pega el siguiente código.

{
  // Configuración relacionada con los archivos
  "files.encoding": "utf8", // Establecer la codificación de caracteres predeterminada a UTF-8 al abrir archivos
  "files.autoGuessEncoding": true, // Adivinar automáticamente la codificación de caracteres al abrir archivos
  "files.eol": "\n" // Unificar el final de línea a LF (\n)
}

Si ya hay algo escrito dentro de {}, simplemente agrega los elementos de configuración (como "files.encoding": "utf8",) dentro.

Caso 2: ¡El comando no funciona! El error "command not found"

En el desarrollo web, a menudo se utilizan comandos como npm y git en la terminal integrada de VSCode. Sin embargo, a veces, al escribir un comando, aparece un error como zsh: command not found: npm, como si te dijera "No conozco ese comando".

Causa:
Esto se debe a que el comando (programa) no está instalado en tu ordenador, o está instalado, pero tu ordenador no sabe dónde está (es decir, el PATH no está configurado).

Solución:
Primero, comprobemos si realmente está instalado. Por ejemplo, para Node.js (que incluye el comando npm), prueba a escribir el siguiente comando en la terminal.

node -v

Si se muestra un número de versión (por ejemplo, v20.11.0), está instalado. Si obtienes command not found, significa que no está instalado en absoluto. Instálalo desde el sitio web oficial de Node.js.

Si sigues recibiendo el error a pesar de que está instalado, prueba a reiniciar VSCode. Inmediatamente después de la instalación, es posible que VSCode no haya reconocido el nuevo PATH.

Caso 3: ¡El código no se formatea! Prettier / ESLint no funcionan

En el momento en que guardas un archivo, tu código desordenado se formatea mágicamente... Esto es posible gracias a formateadores/linters como Prettier y ESLint. ¡Pero una frustración común es cuando lo has configurado, pero no funciona en absoluto!

Causa:
Hay varias razones posibles.
1. La extensión Prettier o ESLint para VSCode no está instalada o está desactivada.
2. Faltan archivos de configuración en el proyecto (.prettierrc, .eslintrc.js).
3. "Formatear al guardar" no está habilitado en la configuración de VSCode.
4. Varios formateadores están en conflicto.

Solución:
Intenta copiar y pegar la siguiente configuración en el archivo settings.json que mencionamos antes. Esta es una configuración "todo en uno" que debería resolver todo tipo de problemas. Esta configuración me salvó innumerables veces cuando estaba creando mi sitio web.

{
  // ----- Configuración para formateo y linter -----

  // Establecer Prettier como formateador predeterminado
  // Esto evita conflictos con otros formateadores
  "editor.defaultFormatter": "esbenp.prettier-vscode",

  // Ejecutar automáticamente el formateo al guardar el archivo
  "editor.formatOnSave": true,

  // Especificar los tipos de archivo que ESLint debe comprobar y corregir
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // También ejecutar la corrección automática de ESLint al guardar el archivo
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

【Punto clave】
La parte más importante es "editor.defaultFormatter": "esbenp.prettier-vscode". VSCode tiene sus propias capacidades de formato de código integradas. Por lo tanto, cuando instalas la extensión Prettier, puede confundirse sobre qué instrucciones seguir. ¡Esta línea declara: "En lo que respecta al formato, ¡se lo dejo todo al Sr. Prettier!" lo que evita conflictos.

Por supuesto, ¡esto supone que tienes instaladas las extensiones de Prettier y ESLint!

Caso 4: ¡Importación no encontrada! El error "Cannot find module"

Al desarrollar con JavaScript o TypeScript, se utiliza import para cargar componentes (módulos) de otros archivos. A veces puedes obtener un error como Cannot find module './components/Button'.

Causa:
Esto es casi siempre un simple error de especificación de la ruta. Sin embargo, a medida que los proyectos se vuelven más complejos, las rutas relativas como ../../../../utils/helper.js pueden volverse cada vez más profundas, lo que las hace fáciles de equivocar (a esto lo llamo el "Infierno de los ('../')").

Solución:
Para escapar de este "Infierno de los ('../')", creemos un archivo de configuración llamado jsconfig.json (o tsconfig.json para TypeScript). Este archivo le dice a VSCode: "Esta es la ubicación base (raíz) del proyecto".

Crea un archivo llamado jsconfig.json en el nivel superior de tu proyecto (el mismo nivel que package.json) y pega el siguiente contenido.

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

【Punto clave】
¿Qué tiene de bueno esta configuración? Por ejemplo, digamos que quieres importar un archivo de src/components/ui/Button.jsx en src/pages/index.js, que está en un directorio completamente diferente.

Antes: import Button from '../../components/ui/Button'; (Es fácil equivocarse de ruta...)
Después: import Button from '@/components/ui/Button'; (¡@ apunta a la carpeta src, por lo que siempre puedes escribirlo de la misma manera!)

¡Con esto, casi nunca necesitarás modificar tus sentencias import aunque muevas los archivos! ¡Esto es realmente revolucionario!

[Avanzado] ¡No tengas más miedo! Cómo preguntar a la IA cuando tienes un error

La razón por la que pude construir un sitio web por mí mismo desde cero es, sin duda, gracias a los asistentes de IA. Incluso si recibes un mensaje de error, no hay necesidad de entrar en pánico. Es el mejor "material" para hacerle una pregunta a la IA.

Pero simplemente copiar y pegar el mensaje de error no siempre te dará una buena respuesta. Hay un truco para hacer preguntas y obtener buenas respuestas.

La plantilla de pregunta definitiva

Cuando te encuentres con un error, intenta preguntarle a la IA usando la siguiente plantilla.

Asunto: Se encontró [Contenido del error] en [Tecnología utilizada]

1. Contexto/Objetivo:
(Ej.: Estoy intentando importar un componente usando Next.js y TypeScript.)

2. Problema que ocurre:
(Ej.: Cuando ejecuto npm run dev, se muestra el siguiente mensaje de error en la terminal.)

Pega el mensaje de error aquí exactamente como está

3. Código relevante:
(Ej.: Aquí está la parte relevante del código del archivo donde ocurre el error.)

Pega el código aquí

4. Lo que he intentado:
(Ej.: He intentado volver a ejecutar npm install y reiniciar VSCode, pero no se ha solucionado el problema.)

5. Pregunta:
Por favor, dime la causa raíz de este error y los pasos específicos para resolverlo.

Al transmitir "qué estabas tratando de hacer", "qué sucedió" y "qué has intentado" como un conjunto, la IA puede comprender con precisión la situación y proporcionar una solución precisa. Los registros de errores son un tesoro de pistas. Por todos los medios, haz de la IA tu compañero definitivo.

Resumen

En este artículo, he explicado los errores comunes con los que tropiezan los principiantes en VSCode y sus soluciones específicas, basándome en mis propias experiencias.

Los errores son una parte inevitable del aprendizaje de la programación. Pero cada error tiene una causa y una forma de resolverse. Un mensaje de error no es tu enemigo; es una señal amistosa que te dice: "¡Esta parte está mal!".

Me alegraría enormemente si este artículo ayuda a convertir tu "no lo entiendo" en "¡lo entiendo!". Cada vez que superas un error, definitivamente estás subiendo de nivel. ¡Ten confianza y disfruta de la codificación!