Content Script y Service Worker: el cerebro y las manos de la extensión
En la lección anterior levantaste el esqueleto de la extensión con manifest.json. En esta lección conocerás a los dos roles más importantes de una extensión: el service worker es el cerebro, permanece en segundo plano respondiendo a eventos; el content script son las manos y los pies, se mete en la página web para leerla y modificarla. Solo distinguiendo estos dos roles podrás explicar bien tus requisitos, y la IA podrá colocar el código en el archivo correcto.
Qué podrás hacer al terminar
- Explicar qué puede y qué no puede hacer cada uno: el content script y el service worker
- Declarar el background service worker y content_scripts en manifest.json, y hacer que funcionen de verdad
- Verificar con tus propias manos el «mundo aislado (isolated world)»: la página web y tu script no pueden ver las variables JS de la otra, pero comparten el mismo DOM
- Saber dónde ver los registros de cada uno: esta es la base para la depuración de la próxima lección
Tu situación actual
- Pides a la IA que escriba una extensión y de golpe genera service-worker.js y content-script.js, y no sabes por qué hacen falta dos ni para qué sirve cada uno
- El script se inyecta en la página pero no logra leer las variables de la propia web; quieres modificar la página desde segundo plano y la IA te dice que «no se puede»
- Pusiste console.log en el código pero no encuentras la salida: no está en la página de extensiones ni en la consola de la web
Cuándo usar esta técnica
Esta lección es para ti si: quieres añadir a tu extensión la capacidad de «modificar páginas web» o «responder a eventos del navegador en segundo plano», o quieres entender la estructura de archivos de las extensiones generadas por IA.
Y no quieres: colocar el código en el archivo equivocado y rehacerlo una y otra vez, ni encontrarte con errores sin saber dónde buscar los registros.
🎒 Preparativos antes de empezar
- Haber leído el curso previo«Explicación detallada de manifest.json: referencia rápida de campos de MV3»
- Tener a mano un proyecto de extensión que se pueda cargar localmente con Load unpacked (con uno tipo Hello Extensions basta)
- Saber abrir
chrome://extensionsy recargar la extensión (haz clic en el icono de actualizar de la tarjeta de la extensión) - Saber abrir el DevTools de una página web (clic derecho en la página → «Inspeccionar») para ver la consola
Idea central
Imagina la extensión como una persona:
- service worker (el cerebro, es decir, el script en segundo plano de la extensión): oficialmente se le llama el «central event handler» (centro de eventos) de la extensión. No depende de ninguna página y espera eventos en segundo plano del navegador: cerrar pestañas, hacer clic en notificaciones, navegar a una nueva página, todo eso le corresponde; «se carga cuando se necesita y se descarga cuando está inactivo». No puede acceder al DOM; si quiere modificar una página, solo puede ordenarle al content script que lo haga.
- content script (las manos): la definición oficial es «un archivo que se ejecuta en el entorno de la página web»; usa el DOM estándar para leer la página, modificarla y devolver información al cuerpo de la extensión.
- Mundo aislado (isolated world): el content script vive en un entorno de ejecución privado al que ni la página web ni otras extensiones pueden acceder; tampoco puede ver las variables JS de la página. Pero el DOM es compartido: ambos lados ven la misma página.
| content script (las manos) | service worker (el cerebro) | |
|---|---|---|
| Dónde se ejecuta | Dentro de una página web concreta | En segundo plano del navegador, sin depender de ninguna página |
| ¿Puede manipular el DOM? | ✅ Puede leer y modificar | ❌ No puede |
| Ciclo de vida | Acompaña a la página | Se inicia bajo demanda y se detiene al quedar inactivo |
| APIs de extensión directamente disponibles | Pocas (dom, i18n, storage, algunos métodos de runtime) | Como centro de eventos, responde a todo tipo de eventos de extensión |
| Tareas típicas | Cambiar estilos de la página, leer el contenido de la página | Escuchar eventos de pestañas/notificaciones, gestionar pestañas |
| Dónde ver los registros | Consola de la página web anfitriona | Inspect views de la página de extensiones |
💡 ¿Los tutoriales antiguos no coinciden?
El "background script" de los tutoriales antiguos de MV2 es el service worker de hoy: cambió el nombre, no el rol. Hoy en día las extensiones se escriben solo con MV3; no copies el código antiguo tal cual.
Hazlo conmigo
Paso 1: declarar el service worker (el script en segundo plano de la extensión)
Por qué: primero hay que registrar el cerebro, para que Chrome sepa a quién debe iniciar en segundo plano.
Añade un fragmento background en manifest.json:
"background": {
"service_worker": "service-worker.js"
}Crea un nuevo archivo service-worker.js en el directorio raíz de la extensión:
console.log("service worker 已启动");Vuelve a chrome://extensions y recarga la extensión.
Deberías ver: en la tarjeta de la extensión aparece la zona Inspect views, con un enlace azul al service worker; ábrelo y en la consola del DevTools encontrarás tu registro.
💡 ¿El registro «desaparece» al poco tiempo?
El service worker se inicia bajo demanda y se detiene al quedar inactivo. Si al rato se duerme, no significa que esté roto: la próxima vez que haya un evento, despertará solo.
- Pequeña comprobación: poder ver «service worker iniciado» en el DevTools abierto desde Inspect views
Paso 2: escribir el primer content script (inyección estática con content_scripts)
Por qué: manos y pies no crecen solos — hay que declararlos estáticamente con content_scripts en el manifest para que se inyecten automáticamente en los sitios web que especifiques.
Añade en manifest.json (matches es obligatorio y determina en qué páginas se inyecta; el siguiente es el ejemplo de la documentación oficial, cambia el dominio por el sitio web en el que realmente quieres que actúe):
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"js": ["content-script.js"]
}
]En el ejemplo oficial también hay una línea "css": ["my-styles.css"] — un content script puede inyectar solo JS, solo CSS, o ambos, según lo que necesites.
Crea content-script.js en el directorio raíz de la extensión:
console.log("[content script] 注入成功,页面标题:", document.title);
document.body.style.border = "5px solid red";Recarga la extensión y luego actualiza la página web de destino — al modificar un content script hay que hacer ambos pasos: «recargar la extensión + actualizar la página anfitriona».
Deberías ver: aparece un borde rojo alrededor de la página web de destino; en la Consola de las DevTools de la página web están los logs que imprimiste (atención: es la Consola de la página web, no la de la página de la extensión).
- Pequeña comprobación: aparece el borde rojo y en la Consola de la página web se ven los logs del content script
Paso 3: verifica con tus propios ojos el mundo aislado (isolated world)
Por qué: es el punto que más confunde a los principiantes — «el script claramente corre en la página, ¿cómo es que no puede leer las variables de la web?». La respuesta es el mundo aislado, y verlo con tus propias manos es lo más ilustrativo.
Cambia content-script.js por:
var extVar = "我来自插件";
console.log("[content script] 我能读到页面标题:", document.title);
document.body.style.border = "5px solid red";
// 5 秒后再读网页变量,留时间给你在网页控制台定义它
setTimeout(function () {
console.log("[content script] 读网页变量 pageVar:", window.pageVar);
}, 5000);Recarga la extensión + actualiza la página, y luego, en un plazo de 5 segundos, cambia a la Consola de la página web e introduce:
var pageVar = "我是网页自己的变量";Cuando salga el log de 5 segundos, introduce en la Consola de la página web extVar y document.body.style.border respectivamente.
Deberías ver:
el content script imprime
读网页变量 pageVar:undefined— no ve las variables de la página webal introducir
extVaren la Consola de la página web daReferenceError— la página web tampoco ve tus variablesdocument.body.style.borderdevuelve"5px solid red"— el DOM es compartido por ambos ladosPequeña comprobación: has visto con tus propios ojos los tres fenómenos y puedes relacionarlos con la frase «variables aisladas, DOM compartido»
Paso 4: asigna cada tarea al rol correcto (cuándo usar a quién)
Por qué: distinguiendo el cerebro de las manos y los pies, podrás comunicar correctamente tus necesidades a la IA, y así no escribirá el código en el archivo equivocado.
| Tu necesidad | A quién se le encarga |
|---|---|
| Inyectar código en una página web concreta, modificar la página | content script |
| No depende de la página, espera eventos en segundo plano, escucha el comportamiento del navegador, muestra notificaciones / gestiona pestañas | service worker |
| Al hacer clic en el icono de la barra de herramientas se abre una ventanita (popup) | action + popup |
| Interceptar, bloquear o modificar peticiones de red | declarativeNetRequest |
Las APIs de extensión que un content script puede usar directamente son muy pocas — las que la documentación oficial lista son dom, i18n, storage y algunos métodos de runtime (como runtime.sendMessage(), runtime.onMessage). Para usar otras APIs, hay que reenviar el mensaje al service worker para que lo haga en tu nombre — por eso estos dos archivos suelen aparecer en pareja, no es que la IA escriba de más.
Deberías ver: usando esta tabla como referencia para el código generado por la IA, la lógica que modifica la página queda en content-script.js y la escucha de eventos en service-worker.js — cada cosa en su sitio, y así podrás entender la estructura de la extensión.
Punto de control ✅
- Inspect views de la página de la extensión permite abrir las DevTools del service worker y ver los logs de arranque
- La página web de destino muestra los cambios del content script, y los logs están en la Consola de la página web
- Puedes demostrar: las variables de la página web y las del content script no se ven entre sí, el DOM es compartido
- Puedes decir a qué rol se le encarga cada uno de los 4 tipos de necesidades
- Sabes que tras modificar un content script hay que hacer ambos pasos: «recargar la extensión + actualizar la página»
Avisos de errores comunes
❌ Escribir document.querySelector(...) en el service worker
Causa: el service worker no puede acceder al DOM, así que este código falla necesariamente.
Forma correcta: todo lo que modifique la página se le encarga al content script; el service worker solo gestiona eventos y, cuando necesita tocar la página, se lo encarga por mensaje al content script.
❌ Llamar directamente a otras APIs de extensión desde un content script
Causa: la documentación oficial dice claramente que el content script está «unable to access other APIs directly» — solo puede usar directamente dom, i18n, storage y algunos métodos de runtime.
Forma correcta: usa runtime.sendMessage() para reenviar la petición al service worker, que la gestiona y te devuelve el resultado.
❌ Modificaste el content script y la página no cambia
Causa: los cambios en un content script requieren los dos pasos «recargar la extensión + actualizar la página anfitriona»; si falta uno, no verás el efecto.
Forma correcta: primero vuelve a chrome://extensions para recargar, y luego actualiza la página web de destino.
❌ Buscar el console.log del content script en la página de la extensión
Causa: el botón Errors de la página de la extensión solo registra runtime errors, console.warning y console.error; el console.log normal no se registra; los logs del content script están en la Consola de la página web anfitriona.
Forma correcta: los logs del content script se consultan en la página web; los logs del service worker sí están en Inspect views de la página de la extensión. Si no encuentras un error, vuelve primero a «Bucle de errores: alimenta el mensaje de error tal cual de vuelta» y dale el error tal cual a la IA.
Técnicas avanzadas
- Además de la declaración estática hay otras dos formas de inyección: la declaración dinámica
chrome.scripting.registerContentScripts(Chrome 96+), y la inyección programáticascripting.executeScript(la extensión la realiza cuando hace falta, por ejemplo al hacer clic en el icono de la barra de herramientas; requiere permiso de host o autorización temporalactiveTab). - Los siguientes artículos del tutorial oficial se desarrollan precisamente por roles: Run scripts on every page, Inject scripts into the active tab, Handle events with service workers — al terminar esta lección puedes continuar directamente con ellos.
- Para probar la suspensión y reactivación del service worker: abre el panel Application → Service Workers en sus DevTools y haz start/stop manualmente. Atención: hacer Inspect (inspeccionar) el service worker lo mantiene activo todo el tiempo; recuerda cerrar las DevTools al terminar la prueba.
Resumen de la lección
✅ Recuerda los dos roles con una frase:
- service worker = el cerebro: el centro de eventos de la extensión, se inicia según demanda, se detiene cuando está inactivo, no puede tocar el DOM
- content script = las manos y los pies: vive dentro de la página web, puede leer y modificar la página, protegido por el mundo aislado
- Mundo aislado: las variables JS no se ven entre sí, el DOM es compartido por ambos lados
- Ubicación de los logs: content script → Consola de la página web anfitriona; service worker → Inspect views de la página de la extensión
Repaso de los campos de configuración clave
| Campo | Valor recomendado | Descripción |
|---|---|---|
background.service_worker | "service-worker.js" | Declara el script en segundo plano de MV3 (el background script de MV2 es justamente esto) |
content_scripts[].matches | El match pattern de los sitios de destino | Obligatorio; determina en qué páginas se inyecta |
content_scripts[].js | ["content-script.js"] | Lista de archivos JS que se inyectarán |
Avance de la próxima lección
Los registros de los dos roles: uno está oculto en la página web y otro en la página de la extensión. La próxima lección 《El plugin no aparece: dónde buscar los registros y cómo leer los errores》 explica todas estas ubicaciones de una vez. Aprenderás:
- Dónde aparecen los errores cuando el manifest está mal escrito o los permisos están mal escritos
- Dónde ver los registros de popup, content script y service worker, respectivamente
- Cómo usar el botón Errors de la página de la extensión para localizar problemas rápidamente