Skip to content

La extensión no se deja depurar: dónde encontrar los registros y cómo leer los errores ​

La hiciste siguiendo Tu primera extensión de Chrome: Hello World en 15 minutos, ahora le añades alguna función nueva y el resultado: al pulsar el icono el popup no aparece o queda en blanco, escribiste console.log y no lo ves en ninguna parte, la funcionalidad funciona a ratos, fetch a la API externa falla siempre. No te apresures a cambiar el código: la primera lección de la depuración de extensiones de Chrome es encontrar los registros en el lugar correcto y leer la información de los errores.

Qué podrás hacer al terminar ​

  • Distinguir en 60 segundos dos tipos de problemas: «no se cargó» (cuadro de diálogo de error al cargar) y «se cargó pero hay errores» (botón Errors en rojo)
  • Encontrar de una vez los lugares de registro de los tres bloques de código: Service Worker, popup y content script, sin buscar console.log por toda la interfaz
  • Conocer los textos originales de 6 errores de alta frecuencia en extensiones de Chrome, sabiendo la causa y la solución de cada uno
  • Pasar el texto del error tal cual a la IA; si dos rondas de autochequeo no dan resultado, sube el nivel de la petición de ayuda con tres materiales

⏳ Primera revisión: inspección rápida en 60 segundos ​

Abre la página de gestión de extensiones y determina primero a qué tipo pertenece el problema:

text
# 1. Escribe en la barra de direcciones, abre la página de gestión de extensiones y localiza la tarjeta de tu extensión
chrome://extensions

# 2. Cuadro de diálogo de error al cargar → el manifest está roto, la extensión no se cargó → mira «Problemas relacionados con manifest y permisos»

# 3. Botón Errors en rojo → se cargó pero hay errores, ábrelo y copia el texto original → clasifica el problema según el texto del error

# 4. Ambos lugares limpios → confirma que la extensión está habilitada, pulsa «Recargar» y reproduce el síntoma una vez más

# 5. Sigues sin pistas → casi seguro estás mirando los registros en el lugar equivocado → mira «Dónde encontrar los registros», cambia a la consola correcta y repite

🔧 Diagnóstico de problemas frecuentes ​

Los textos de error siguientes provienen literalmente del ejemplo Broken Color del tutorial oficial de depuración de extensiones de Chrome, agrupados por componente de la extensión, cada uno con su causa y solución.

Dónde encontrar los registros: en la depuración de extensiones de Chrome primero mira el lugar correcto ​

«Escribí console.log y no veo la salida en ninguna parte» ​

Causa: los registros de los tres bloques de código de la extensión se imprimen en tres lugares distintos entre sí; si miras el equivocado no verás ni uno.

Solución: clasifica cada caso—

Dónde está el códigoDónde están los registrosCómo abrirlos
Service WorkerPágina de extensiones Inspect views DevTools abiertos desde el enlace de al ladochrome://extensions → pulsa el enlace service worker de la tarjeta de tu extensión
popupLos DevTools propios del popupClic derecho en el popup abierto → «Inspeccionar»
content scriptConsola de la página web anfitrionaEn la página de destino F12,top selecciona tu extensión en el desplegable de al lado

Deberías ver: el console.log de cada bloque de código aparece en su lugar correspondiente. Para qué sirve cada uno de los tres bloques de código, ver Content Script y Service Worker: el cerebro y las manos de la extensión.

💡 Otras páginas completas de la extensión

Las páginas de la extensión mostradas como pestañas (como una página de opciones a página completa): haz clic derecho «Inspeccionar» directamente en la página para ver los registros, o vuelve a la página de gestión de extensiones a mirar Errors.

«La funcionalidad funciona a ratos, el service worker parece dormirse» ​

Causa: no necesariamente es una impresión equivocada. Durante el Inspect (con DevTools abiertos) el service worker se mantiene activo todo el tiempo, y muchos problemas «que solo se revelan tras dormirse» no se reproducen entonces; solo al cerrar los DevTools se termina según su ciclo de vida normal.

Solución:

  1. Para reproducir el problema mantén los DevTools abiertos (entra desde el enlace de Inspect views), para que el worker no se duerma a mitad.
  2. Para verificar el comportamiento real cierra los DevTools, dejando que el worker se termine según su ciclo de vida normal.
  3. Para iniciarlo o detenerlo manualmente: copia el ID de la extensión que aparece sobre Inspect views en la página de extensiones, abre chrome-extension://<你的扩展ID>/manifest.json en el navegador, inspecciona esa página y entra al panel Application, en el apartado Service Workers; usa los enlaces junto a status para iniciar o detener.

Problemas relacionados con manifest y permisos ​

「Failed to load extension / Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536. / Could not load manifest.」 ​

Causa: el nombre o el formato de un campo de manifest.json está mal — por ejemplo, escribir "version" en lugar de "versions"; la extensión no llegó a cargarse. Este cuadro de diálogo de error aparece al cargar y Chrome señala dónde está el problema.

Solución:

  1. Compara manifest.json con el campo señalado en el cuadro de diálogo y corrige la escritura (versions → version).
  2. Guarda, vuelve a chrome://extensions y pulsa «Recargar».
  3. Deberías ver: el cuadro de diálogo ya no aparece y la tarjeta de la extensión se muestra con normalidad.
  4. Si tras varios intentos no lo arreglas, copia el mensaje de error completo tal cual para la IA y adjunta todo el contenido de manifest.json.

💡 Prevenir este tipo de errores por adelantado

En el editor de código, asocia al manifest.json el JSON schema de Chrome manifest (json.schemastore.org/chrome-manifest); los campos mal escritos y los campos obligatorios que falten se marcarán en rojo directamente.

「Permission 'activetab' is unknown or URL pattern is malformed.」 ​

Causa: el nombre del permiso está mal escrito, por ejemplo activeTab escrito todo en minúsculas activetab. Ojo: con este tipo de error la extensión sí se carga correctamente; solo se pone rojo el botón Errors de la página de extensiones, así que es el más fácil de pasar por alto.

Solución:

  1. Abre chrome://extensions y pulsa el botón Errors en rojo de la tarjeta de la extensión.
  2. Corrige la ortografía del permiso señalado en el error: activetab → activeTab.
  3. Pulsa Clear all en la esquina superior derecha para borrar los registros antiguos y recarga la extensión.
  4. Deberías ver: el botón Errors ya no se pone rojo.

「Las peticiones fetch() a una API externa fallan siempre」 ​

Causa: el manifest no declara la URL de destino como host permission. Para fetch() un servidor externo hay que declarar antes esa URL en el manifest; de lo contrario, la petición ni siquiera se envía — el mismo código funciona en una página web normal, esa es la diferencia.

Solución:

  1. Declara el sitio de destino como host permission en el manifest.
  2. Guarda, recarga la extensión y vuelve a enviar la petición.
  3. Deberías ver: la petición aparece en el panel Network del popup (cómo capturarla, ver «Problemas relacionados con popup»).

Problemas relacionados con Service Worker ​

「Service worker registration failed. Status code: 15.」 ​

Causa: el service worker lanza un error ya en la fase de arranque (registro), por ejemplo onInstalled escrito en minúsculas oninstalled. Mientras dura el fallo de registro, no se puede abrir ni el DevTools del worker; hay que arreglar esto primero.

Solución:

  1. Vuelve a chrome://extensions y pulsa Errors; lo primero que aparece es este fallo de registro.
  2. La causa real suele estar en el segundo error, justo después (ver la sección siguiente); corrige el código según ese.
  3. Tras corregir, pulsa Clear all y recarga. Deberías ver: este error ya no aparece en Errors.

「Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')」 ​

Causa: se llama a addListener sobre un objeto undefined — casi seguro el nombre de la API está mal escrito (por ejemplo onInstalled en lugar de oninstalled), no se obtiene el objeto y la llamada siguiente explota.

Solución:

  1. Con el número de línea del error, revisa la ortografía y las mayúsculas del nombre de la API y restaura el nombre correcto.
  2. Recarga la extensión y abre DevTools desde Inspect views para confirmar que el worker se registra con normalidad.
  3. Deberías ver: en la Console del worker aparecen los logs que escribiste y ya no hay errores.

「Uncaught ReferenceError: tabs is not defined」 ​

Causa: el código del popup usa tabs sin definirlo (por ejemplo, se comentó el bloque de tabs.query), y la extensión no sabe en qué pestaña inyectar el script.

Solución:

  1. Clic derecho en el popup abierto → «Inspeccionar», abre el DevTools propio del popup; el error está en la Console.
  2. Añade tabs.query para obtener la pestaña actual y usa tabs[0].id para indicar el destino de la inyección.
  3. Pulsa Clear all y recarga; vuelve a abrir el popup para verificar. Deberías ver: al pulsar el botón, la pestaña de destino muestra el efecto esperado.

「No se captura ninguna petición de red del popup」 ​

Causa: el popup envía las peticiones demasiado rápido y casi siempre termina antes de que abras DevTools, por eso el panel Network queda en blanco.

Solución: en el DevTools del popup, cambia al panel Network y pulsa refrescar dentro del panel — así el popup se recarga sin cerrar DevTools y las peticiones quedan registradas.

Problemas relacionados con content script ​

「Uncaught ReferenceError: colors is not defined」 ​

Causa: el nombre de una variable en el content script está mal escrito (por ejemplo color en lugar de colors), y el script inyectado no pasa la variable correcta.

Solución:

  1. Ve a la página web anfitriona y pulsa F12 para abrir la consola — los errores del content script aparecen aquí, no en la página de extensiones.
  2. En la consola, pulsa la flecha desplegable junto a top y selecciona tu extensión para ver solo sus logs.
  3. Corrige el nombre de la variable según el error, refresca la página y reintenta. Deberías ver: el error desaparece de la consola de la página y aparece el efecto esperado.

「La página de extensiones no muestra Errors, pero la extensión no funciona」 ​

Causa: el Errors de la página de extensiones solo registra errores en tiempo de ejecución, console.warning y console.error. Muchos problemas del content script no aparecen ahí — si miras el log en el lugar equivocado, por mucho que busques no encontrarás nada.

Solución:

  1. Vuelve a revisar en la consola de la página web anfitriona (método en el punto anterior).
  2. Si los logs están limpios de verdad, el manifest ya pasó la validación con schema y la función sigue sin funcionar — deja de probar a ciegas y pide ayuda escalando con tres materiales (ver abajo).

💡 ¿Sigue sin funcionar? ​

Si tras dos rondas de autoverificación no tienes ni idea, deja de probar a ciegas. Ante cualquiera de las siguientes situaciones, escala directamente:

  • El error involucra el comportamiento de una API de Chrome y las modificaciones que la IA dio en dos rondas consecutivas no funcionan
  • Los registros están limpios, la validación del schema del manifest pasa, pero la función sigue sin surtir efecto, y ya confirmaste que no te equivocaste de ubicación de registros

Al pedir ayuda, lleva tres materiales:

  1. El texto completo de manifest.json
  2. El texto íntegro del error (incluida la traza de pila)
  3. Pasos mínimos de reproducción

Con los materiales completos, ya sea que se los envíes a la IA o vayas a hacer una pregunta, obtendrás una respuesta útil en la primera ronda. Para conocer el método concreto de devolverle el error tal cual a la IA, consulta Ciclo de errores: devuelve el mensaje de error tal cual.

En resumen, la ruta de depuración de un plugin de Chrome tiene solo 3 pasos: primero clasificar, luego encontrar la ubicación correcta de los registros y, por último, devolver el texto del error tal cual.

Avance de la próxima lección ​

Cuando el plugin funcione de forma estable, compártelo con más personas: en la siguiente página Publicar en la Chrome Web Store: registro, empaquetado y envío a revisión, el proceso completo, te guiará por todo el proceso de registrar una cuenta de desarrollador, empaquetar y enviar a revisión.

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.