Cómo Depurar Extensiones de Chrome: Guía Paso a Paso

Sebastian Gomez

Jul 21, 2024

Updated: Jun 25, 2026

Cómo Depurar Extensiones de Chrome: Guía Paso a Paso

Depurar extensiones de Chrome puede ser un desafío, especialmente para quienes están empezando en el desarrollo de estas herramientas. En este post exploraremos cómo puedes depurar eficazmente tus extensiones de Chrome y resolver los problemas más comunes que pueden surgir durante el desarrollo. Vamos a recorrerlo paso a paso.

Comenzando con la Depuración

Manifest File: El archivo manifest.json es crucial para cualquier extensión de Chrome. Un error muy común es tener una configuración incorrecta en este archivo.

Ejemplo de un error típico: asegúrate de que las propiedades estén correctamente escritas. Por ejemplo, la propiedad permissions debe estar en plural y la versión del manifest debe ser precisa.

Hoy en día Chrome solo ejecuta extensiones con Manifest V3. Manifest V2 fue retirado de forma progresiva durante 2024 y 2025, y ya no funciona en ningún canal del navegador. Por eso, tu manifest siempre debe declarar "manifest_version": 3. Como recordarás de capítulos anteriores de esta serie, dedicamos un capítulo entero a Manifest V3, así que aquí seguimos esa misma línea.

{
    "name": "Mi Extensión",
    "version": "1.0",
    "manifest_version": 3,
    "permissions": ["tabs"]
}

Errores Comunes en el Manifest:

Permisos incorrectos: asegúrate de que los permisos estén en un array, no en un objeto.
Versiones: al actualizar tu extensión, incrementa el número de version adecuadamente para reflejar los cambios mayores o menores.
Versión del manifest desactualizada: si vienes de una extensión antigua con "manifest_version": 2, debes migrarla a la versión 3, porque MV2 ya no se ejecuta.

Depurando el Service Worker

En Manifest V3, el background script se reemplazó por un Service Worker. Este puede desactivarse cuando no está en uso, lo que a veces dificulta la depuración: si lo abres y no ves actividad, puede que simplemente esté inactivo.

Inspeccionar el Service Worker:

Abre chrome://extensions/ y activa el modo de desarrollador (Developer mode) en la esquina superior derecha.
Localiza tu extensión y haz clic en el enlace "Inspect views: service worker" (Inspeccionar vistas: service worker). Esto abre las DevTools directamente conectadas al Service Worker, con su consola y sus breakpoints.
Para una vista de bajo nivel de todos los Service Workers registrados, visita chrome://serviceworker-internals. Desde ahí puedes ver su estado, detenerlos o forzar su arranque.

Reactivar el Service Worker: refresca la extensión desde chrome://extensions/ (botón de recargar) para asegurarte de que el Service Worker vuelva a estar activo, y observa su estado en la consola para confirmar que está corriendo.

Nota: el idle timeout del Service Worker se amplió respecto a las primeras versiones de MV3. Mientras haya puertos de mensajes o eventos activos, el temporizador de inactividad se reinicia, así que un Service Worker que está procesando mensajes no se apaga en medio de la tarea. Esto mejora bastante la experiencia de depuración frente a las versiones iniciales de MV3.

Uso de la librería chrome.runtime

La librería chrome.runtime es esencial para manejar mensajes y eventos dentro de tu extensión.

Errores de conexión: un error muy común es "Could not establish connection. Receiving end does not exist.". Suele aparecer al enviar mensajes entre el Service Worker, los content scripts y el popup.

Las causas reales más frecuentes son:

No hay ningún listener registrado. El extremo que recibe el mensaje debe registrar chrome.runtime.onMessage. Si ese listener no existe, no hay quien reciba la conexión.
El content script todavía no se ha inyectado. Si haces chrome.tabs.sendMessage a una pestaña antes de que su content script esté cargado, no hay receptor listo. Asegúrate de que la pestaña y el content script estén disponibles antes de enviar el mensaje.

Solución: registra el listener en el receptor y verifica que el destino esté listo antes de enviar. En Manifest V3, chrome.runtime.sendMessage admite promesas, así que te recomiendo usar la versión basada en promesas en lugar de callbacks, porque hace el manejo de errores mucho más claro.

// Receptor: registra el listener
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.type === "PING") {
    sendResponse({ ok: true });
  }
});

// Emisor: sendMessage basado en promesas (MV3)
const response = await chrome.runtime.sendMessage({ type: "PING" });
console.log(response);

Depurando el Popup de la Extensión

El popup de la extensión es la interfaz que los usuarios ven al interactuar con ella. Es importante asegurarse de que funcione correctamente.

Abrir las herramientas de desarrollo:

Haz clic derecho en el popup y selecciona "Inspeccionar" para abrir las DevTools de Chrome conectadas al popup.
Usa la pestaña "Console" para ver errores y los mensajes de console.log.

Depurando AJAX y red: usa la pestaña "Network" para monitorizar las peticiones y asegurarte de que las respuestas sean las esperadas.

Depurando el Content Script

El content script interactúa directamente con las páginas web. Para depurarlo:

Consola de desarrollo:

Abre las herramientas de desarrollo de la página y ve a la pestaña "Sources".
Selecciona tu content script y usa breakpoints para pausar la ejecución y revisar el estado del DOM.

Monitoreo de Permisos

Asegúrate de que tu extensión tenga los permisos correctos para realizar las operaciones necesarias.

Declaración de permisos: en el archivo manifest.json, declara todos los permisos necesarios.

{
    "permissions": ["tabs", "storage", "contextMenus"]
}

Nota: tabs es un permiso bastante amplio. Si solo necesitas acceder a la pestaña activa cuando el usuario interactúa con tu extensión, prefiere activeTab: pide menos a tus usuarios y reduce la superficie de permisos que Chrome muestra al instalar.

Revisar Extensiones de Otros

Para aprender y obtener inspiración, puedes revisar el código de otras extensiones instaladas.

Acceder a las extensiones instaladas:

En macOS: Library/Application Support/Google/Chrome/Default/Extensions.
En Windows: C:\Users\[TuUsuario]\AppData\Local\Google\Chrome\User Data\Default\Extensions.

Analizar el código: examina archivos como manifest.json y los scripts para entender cómo funcionan y cómo están estructurados.

Ejercicios propuestos

Toma una extensión de ejemplo con "manifest_version": 2 y migra su manifest a Manifest V3, ajustando el background script a un Service Worker.
Provoca a propósito el error "Could not establish connection. Receiving end does not exist." enviando un mensaje a una pestaña sin content script, y luego corrígelo registrando un listener onMessage.
Cambia el permiso tabs por activeTab en una extensión sencilla y comprueba que sigue funcionando para tu caso de uso.

Resumen en 3 puntos

En 2026 Chrome solo ejecuta extensiones con Manifest V3, así que tu manifest siempre debe declarar "manifest_version": 3.
Depura el Service Worker desde chrome://extensions/ con "Inspect views: service worker" y revisa chrome://serviceworker-internals para un control de bajo nivel.
La mayoría de los errores de mensajería vienen de un listener onMessage ausente o de un content script no inyectado; usa chrome.runtime.sendMessage basado en promesas para un manejo de errores más claro.

Espero que este post te haya ayudado a comprender mejor cómo depurar tus extensiones de Chrome. Si tienes alguna pregunta o necesitas más detalles, no dudes en dejar un comentario. ¡Hasta la próxima!