Guía detallada de manifest.json: referencia rápida de campos de MV3
💡 Resumen en una frase: manifest.json es el único archivo imprescindible de una extensión: 3 campos obligatorios de la plataforma como base, 2 campos obligatorios de la tienda para publicar, y el resto se añade según las funciones.
En la lección anterior C2 Tu primera extensión de Chrome, el manifest.json se copió letra por letra: funciona, pero quizá no sabrías explicar por qué cada campo se escribe así. En esta lección lo desmontamos campo por campo: cuáles hacen que Chrome rechace la carga directamente si faltan, cuáles solo se verifican al publicar, y cómo escribir los campos opcionales de uso frecuente. A partir de ahora, tanto si lo escribes tú como si lo genera una IA, podrás leerlo, modificarlo y depurarlo.
Qué podrás hacer al terminar
- Nombrar los 3 campos obligatorios de la plataforma y los 2 campos obligatorios de la tienda de manifest.json, junto con sus límites de longitud y formato
- Partiendo del ejemplo mínimo, añadir action, background, content_scripts y permissions uno a uno a tu propio manifest
- Consultar el propósito de todos los 46 campos con una tabla de referencia rápida de campos de MV3
- Evitar los tres grandes errores de principiante: escribir comentarios en JSON, copiar tutoriales antiguos de MV2 y usar números de versión no válidos
- Revisar con una lista de verificación antes de publicar, y saber qué información no se puede cambiar después de subirla
Tu situación actual
- «La IA me generó un manifest.json, pero no entiendo nada: qué campo es obligatorio y para qué sirve cada uno»
- «Copiaba tutoriales antiguos de internet y los campos nunca coincidían; luego descubrí que era la sintaxis de MV2, trabajo en vano»
- «La carga local funcionaba perfectamente, pero al subirlo a la tienda me daba Cannot parse the manifest, y tras mucho buscar no sabía dónde estaba el error»
Cuándo usar esta técnica
Cuando necesites:
- Consultar la sintaxis y las restricciones de un campo del manifest (cuántos caracteres como máximo tiene name, cuántos segmentos puede tener version)
- Construir desde cero un manifest.json que se pueda cargar, o añadir campos de nuevas funciones a una extensión existente
- Verificar los campos obligatorios antes de publicar, y eliminar el «descubrir el error después de subirlo» antes de subirlo
Y además no quieras:
- Leer la descripción completa de los 46 campos en la documentación oficial: la tabla de referencia rápida está a una pantalla de aquí abajo
- Que Chrome rechace la carga o que la tienda rechace tu extensión por un campo mal escrito
- Confundir la sintaxis de MV2 con la de MV3, copiar mal un tutorial y pensar que Chrome está roto
🎒 Preparativos antes de empezar
- Haber completado C2 Tu primera extensión de Chrome y tener a mano ese manifest.json de Hello World que funciona
- Una herramienta para editar archivos JSON (el Bloc de notas sirve; editores como VS Code son más cómodos)
- Tener abierta la página de gestión de extensiones
chrome://extensions, para poder actualizar y verificar en cualquier momento - 10 minutos
Idea central
Chrome solo tiene un requisito estricto para cada extensión: debe haber un manifest.json en el directorio raíz, que enumera la información de estructura y comportamiento de la extensión: Chrome la reconoce gracias a él, y la tienda la revisa gracias a él.
La documentación oficial divide los 46 campos en cuatro grupos; los principiantes primero deben memorizar los dos primeros:
| Grupo | Campos | Qué pasa si faltan |
|---|---|---|
| Obligatorios de la plataforma (3) | manifest_version, name, version | Chrome rechaza la carga directamente y muestra un diálogo de error |
| Obligatorios para publicar en la tienda (2) | description, icons | Funciona localmente, pero no pasa la revisión de la tienda |
| Opcionales (37) | action, background, content_scripts, permissions, etc. | No faltan, se añaden según las funciones |
| Opcionales·exclusivos de ChromeOS (4) | file_handlers, etc. | Las extensiones de Chrome de escritorio apenas los usan |
Dos reglas de oro que atraviesan toda la página, apréndetelas primero:
- En JSON no se pueden escribir comentarios: al subirlo a la tienda dará el error
Cannot parse the manifest - manifest.json debe estar en el directorio raíz: al cargar localmente se selecciona la carpeta de la extensión, y al empaquetar el zip para publicar, el manifest también debe estar en la raíz del archivo comprimido, sin una carpeta adicional por encima
Hazlo conmigo
A continuación, ampliaremos un manifest.json de 3 campos hasta 10. Trabaja directamente en la carpeta Hello World de la lección anterior; después de cada cambio, vuelve a chrome://extensions y pulsa el icono de refrescar en la tarjeta de la extensión — al modificar el manifest hay que refrescar la extensión para que surta efecto.
Paso 1: escribe los tres campos obligatorios de la plataforma — los cimientos de manifest.json
Por qué: lo primero que hace Chrome al cargar una extensión es leer manifest.json; si falta cualquiera de estos tres campos, la carga falla directamente.
Crea (o abre) el manifest.json en el directorio raíz de la extensión y escribe:
{
"manifest_version": 3,
"name": "My First Extension",
"version": "1.0.0"
}Las restricciones de cada uno de los tres campos:
| Campo | Restricción | Explicación |
|---|---|---|
manifest_version | solo admite 3 | MV3 es la única forma actual; el 2 de los tutoriales antiguos no lo copies |
name | máximo 75 caracteres | se muestra en la tienda, en el cuadro de diálogo de instalación y en la página chrome://extensions |
version | 1-4 enteros separados por puntos, cada uno entre 0-65536 | como 1.0.0; si el formato es incorrecto, Chrome da un error explícito |
Deberías ver: un JSON con solo tres claves — eso es todo lo que exige la plataforma.
Si quieres ver con tus propios ojos cómo las reglas de formato hacen de filtro, cambia deliberadamente version a "1.0.0.0.0" (cinco segmentos) y refresca la extensión; Chrome mostrará un cuadro de diálogo de error: Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536. — al volver a 1.0.0 se recupera.
- Comprobación rápida: manifest.json está en el directorio raíz, los tres campos están presentes y el JSON no lleva comentarios
Paso 2: añade description e icons — completando el ejemplo mínimo oficial
Por qué: estos dos elementos no afectan la ejecución local, pero son de comprobación obligatoria al publicar en la Chrome Web Store; el «ejemplo de manifest mínimo» de la documentación oficial también los incluye.
Añade estos dos elementos al JSON anterior y tendrás el texto original del Minimal Manifest de la documentación oficial (también puedes sustituir name por el nombre de tu propia extensión):
{
"manifest_version": 3,
"name": "Minimal Manifest",
"version": "1.0.0",
"description": "A basic example extension with only required keys",
"icons": {
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}description: máximo 132 caracteres, se muestra en la tienda y en la página de gestión de extensionesicons: uno o más iconos; la clave es el tamaño y el valor la ruta de la imagen
Deberías ver: hasta aquí es exactamente el Minimal Manifest oficial. La imagen a la que apunta icons debe existir de verdad — puedes reutilizar el archivo de icono que ya usaste en el Hello World de la lección anterior; basta con cambiar la ruta dentro de icons por su ubicación real.
- Comprobación rápida: description no supera 132 caracteres; cada ruta de icons tiene su archivo correspondiente en la carpeta
Paso 3: añade action y background — el popup y el centro de eventos
Por qué: action determina qué ocurre al pulsar el icono de la barra de herramientas; background especifica el service worker de la extensión (el gestor de eventos). El popup de la lección anterior era obra de action.
Añade estas dos claves al manifest (ojo: añade una coma al final de la clave anterior):
"action": {
"default_popup": "hello.html",
"default_icon": "hello_extensions.png"
},
"background": {
"service_worker": "service-worker.js"
}action: define el aspecto y el comportamiento del icono de la barra de herramientas;default_popupespecifica la página que se abre al pulsar el icono,default_iconespecifica la imagen del iconobackground: el archivo JS al que apuntaservice_workeres el «cerebro» de la extensión: se inicia bajo demanda y se detiene al quedar inactivo — los usos avanzados se explican en la próxima lección
Deberías ver: tras refrescar la extensión, pulsa el icono de la barra de herramientas y el popup se abre con normalidad. Recuerda crear antes el archivo service-worker.js (por ahora basta con una línea console.log("background ready")) — todas las rutas de archivos declaradas en el manifest deben existir de verdad.
Paso 4: añade la configuración de content_scripts — el script se ejecuta automáticamente en las páginas indicadas
Por qué: si quieres que la extensión «modifique automáticamente la página al abrir cierto tipo de páginas web», lo que necesitas es la declaración estática de content_scripts — sin pulsar ningún botón, el script se inyecta solo.
Añade este bloque al manifest:
"content_scripts": [
{
"matches": ["https://*.nytimes.com/*"],
"css": ["my-styles.css"],
"js": ["content-script.js"]
}
]matches: obligatorio. Determina en qué páginas se inyecta el script, escrito con la sintaxis de match pattern (por ejemplohttps://*.nytimes.com/*); todo content script de ejecución automática debe especificar un match patternjs/css: opcionales. Archivos JS / CSS que se inyectan en el orden del array; las rutas son relativas al directorio raíz de la extensión
Deberías ver: tras refrescar la extensión, abre una página que coincida con matches y el script surte efecto automáticamente. Tras modificar el archivo del content script, además de refrescar la extensión hay que refrescar la página anfitriona. En cuanto a «por qué mi script y las variables de la página no se ven entre sí» — la próxima lección C4 trata de los mundos aislados.
Paso 5: añade las declaraciones de permissions y host_permissions
Por qué: permissions activa APIs de extensión concretas; sin declararlas no se pueden invocar; host_permissions declara con qué sitios web puede interactuar la extensión — los permisos sobre esos sitios se solicitan al usuario en el momento de la instalación.
Añade estas dos líneas al manifest:
"permissions": ["storage"],
"host_permissions": ["https://*.example.com/"]permissions: en el array van los nombres de las APIs a activar, comostorage,scripting,activeTab; declara solo las que realmente useshost_permissions: enumera con match pattern las páginas web con las que se puede interactuar
Deberías ver: refresca la extensión y la carga es correcta. Un nombre de permiso mal escrito no impide la carga, pero en la página de extensiones aparecerá el botón rojo Errors — por ejemplo, escribir activeTab como activetab produce el aviso Permission 'activetab' is unknown or URL pattern is malformed.. El procedimiento completo de depuración está en C5.
Paso 6: verifica con la carga local y revisa punto por punto antes de publicar
Por qué: si los campos están bien escritos o no, solo lo deciden Chrome y la tienda. Pasa primero una ronda en local y revisa otra vez antes de publicar: así te ahorras la reedición más cara.
Procedimiento:
- Vuelve a
chrome://extensionsy pulsa el icono de refrescar en la tarjeta de la extensión (el método de carga en tres pasos se explicó en la lección anterior) - Si la carga falla, aparecerá un cuadro de diálogo de error — corrige el manifest según el mensaje y vuelve a refrescar
- Al preparar la publicación, revisa punto por punto:
| Punto de revisión | Criterio |
|---|---|
name / description | ≤75 / ≤132 caracteres, sin erratas — los metadatos del manifest no se pueden cambiar tras subirlos; si detectas una errata, la única opción es corregir el archivo, subir el número de versión y volver a empaquetar |
version | mayor que la versión ya subida; para la primera versión conviene poner un valor bajo como 0.0.0.1, dejando margen para incrementos futuros |
| Comentarios | No incluyas ningún comentario en el JSON, de lo contrario la subida devolverá Cannot parse the manifest |
| Empaquetado | En la raíz del archivo zip debe estar directamente manifest.json, sin una carpeta intermedia |
Deberías ver: la carga local no muestra diálogos de error ni Errors en rojo; al descomprimir el zip publicado, manifest.json aparece en la primera capa. El flujo completo de registro, envío a revisión y aprobación está en C6.
📋 Tabla de consulta rápida de campos de MV3
💡 Cómo usar esta tabla
Hazte primero dos preguntas: ¿a qué capa pertenece este campo (obligatorio de la plataforma / obligatorio de la tienda / opcional)? ¿A qué grupo pertenece la función que necesito (interfaz / permisos / red / distribución)? Localiza la fila, escríbelo siguiendo la tabla, verifica las restricciones y vuelve al paso correspondiente de la página para ver la explicación ampliada. Los campos y restricciones de esta tabla están recopilados de la documentación oficial Manifest reference de Chrome.
Obligatorios de la plataforma (3 en total)
| Campo | Restricción | Función |
|---|---|---|
manifest_version | Entero, único valor admitido 3 | Versión del formato del manifest |
name | ≤75 caracteres | Nombre mostrado en la tienda, el diálogo de instalación y chrome://extensions |
version | 1-4 enteros separados por puntos, cada segmento 0-65536 | Número de versión; al subir una nueva versión debe ser mayor que la anterior |
Obligatorios para publicar en la tienda (2 en total)
| Campo | Restricción | Función |
|---|---|---|
description | ≤132 caracteres | Descripción en la tienda y en la página de gestión de extensiones |
icons | Uno o más iconos | Icono que representa la extensión |
Opcionales de uso frecuente (conoce primero estos 5)
| Campo | Puntos clave de escritura | Función |
|---|---|---|
action | default_popup apunta a la página del popup, default_icon especifica el icono | Apariencia y comportamiento del icono en la barra de herramientas |
background | {"service_worker": "service-worker.js"} | Especifica el service worker que actúa como controlador de eventos |
content_scripts | matches obligatorio + arrays de js / css | JS/CSS que se inyecta automáticamente al abrir páginas web coincidentes |
permissions | Array de nombres de API, por ejemplo ["storage"] | Habilita APIs específicas de extensiones |
host_permissions | Array de match patterns | Declara las páginas web con las que se puede interactuar y solicita autorización durante la instalación |
Otros campos opcionales (agrupados por uso)
Interfaz e interacción
| Campo | Función |
|---|---|
commands | Define los atajos de teclado dentro de la extensión |
options_page | Especifica options.html como página de configuración de la extensión |
options_ui | Permite al usuario modificar las opciones de la extensión dentro de la página de gestión de extensiones |
side_panel | Especifica la página HTML que se muestra en el panel lateral |
omnibox | Registra una palabra clave en la barra de direcciones de Chrome |
chrome_url_overrides | Anula las páginas predeterminadas de Chrome |
devtools_page | Define páginas que usan la API de DevTools |
Permisos y seguridad
| Campo | Función |
|---|---|
optional_permissions | Declara permisos de API opcionales |
optional_host_permissions | Declara permisos de host opcionales |
content_security_policy | Restringe los recursos (scripts, estilos, etc.) que la extensión puede cargar |
externally_connectable | Especifica qué páginas web y extensiones pueden conectarse a tu extensión |
web_accessible_resources | Define archivos de la extensión accesibles desde páginas web u otras extensiones |
sandbox | Define páginas en sandbox que no pueden usar directamente las APIs de extensiones |
incognito | Comportamiento en modo incógnito, valores spanning / split / not_allowed |
key | Especifica el ID de la extensión para fines de desarrollo |
Red y datos
| Campo | Función |
|---|---|
declarative_net_request | Reglas estáticas de solicitudes de red declarativas; permite interceptar y modificar solicitudes de red |
oauth2 | Configura OAuth 2.0(client_id y scopes) |
storage | Declara un esquema JSON para el área de almacenamiento administrado |
tts_engine | Registra la extensión como motor de texto a voz |
mime_types_handler | Registra la extensión como manejador de un tipo MIME (por ejemplo application/pdf) |
requirements | Enumera las tecnologías necesarias para usar el plugin |
Versión y distribución
| Campo | Función |
|---|---|
version_name | Alias de versión legible para humanos (por ejemplo "1.0 beta"); si no se escribe, se muestra version |
minimum_chrome_version | Versión mínima de Chrome para poder instalar el plugin; en versiones anteriores se muestra como incompatible, no se puede instalar ni se actualiza automáticamente |
homepage_url | URL de la página principal del plugin; si no se escribe, el valor predeterminado es la página de la tienda |
update_url | Dirección de la página de actualización cuando se distribuye de forma autoalojada (sin publicar en la tienda) |
import | Permite importar recursos hacia el plugin |
export | Permite exportar recursos desde el plugin |
Internacionalización y presentación
| Campo | Función |
|---|---|
default_locale | Idioma predeterminado de plugins multilingües (por ejemplo en); obligatorio para plugins localizados, y no se puede usar en plugins no localizados |
short_name | Nombre corto, ≤12 caracteres; si no se escribe, se trunca name para mostrarlo |
Ajustes de Chrome
| Campo | Función |
|---|---|
chrome_settings_overrides | Anula algunos ajustes de Chrome |
cross_origin_embedder_policy | Configura el encabezado de solicitud Cross-Origin-Embedder-Policy |
cross_origin_opener_policy | Configura el encabezado de solicitud Cross-Origin-Opener-Policy |
Exclusivos de ChromeOS (4 en total)
| Campo | Función |
|---|---|
file_browser_handlers | Accede a las API relacionadas con el explorador de archivos de ChromeOS |
file_handlers | Especifica los tipos de archivo que maneja el plugin de ChromeOS |
file_system_provider_capabilities | Permite que el plugin cree un sistema de archivos utilizable en ChromeOS |
input_components | Usa la API del editor de métodos de entrada (IME) |
Punto de control ✅
- manifest.json está en el directorio raíz del plugin y el JSON no contiene ningún comentario
manifest_versiones 3;name≤75 caracteres;versiones 1-4 segmentos de enteros separados por puntos- Si vas a publicarlo en la tienda:
description≤132 caracteres, y cada ruta deiconsexiste realmente - El
matchesdecontent_scriptsestá escrito y cumple la sintaxis de match pattern permissionssolo declara las API que realmente se usan, sin errores ortográficos
Recordatorio de errores comunes
❌ Escribir comentarios en manifest.json
{
"manifest_version": 3, // MV3 写死
"name": "My Extension"
}Motivo: JSON no admite comentarios, y al subirlo a la tienda da directamente el error Cannot parse the manifest. Forma correcta: elimina todos los comentarios antes de subir; si quieres dejar explicaciones, escríbelas en el README o en documentación aparte.
❌ Copiar tutoriales antiguos y escribir manifest_version como 2
Motivo: gran cantidad de tutoriales en internet todavía usan la sintaxis de la era MV2, mientras que en MV3 el único valor admitido para manifest_version es 3, así que copiar la forma antigua es trabajo en vano. Forma correcta: para plugins nuevos, siempre "manifest_version": 3; si dudas de algún campo, vuelve a compararlo con la tabla de consulta rápida de esta página.
❌ Escribir version sin cuidado y que rechacen la subida de la nueva versión
"version": "1.0.0.0.0" // ❌ 五段,超了
"version": "0.0.0.1" // ✅ 初版设低值,以后只往上加Motivo: version debe ser 1-4 segmentos de enteros separados por puntos, cada uno entre 0-65536; además, la tienda exige que cada número de versión nuevo subido sea mayor que el anterior. Forma correcta: para la versión inicial pon un valor bajo como 0.0.0.1, e incrementa solo uno en cada publicación; así siempre tendrás margen.
❌ Descubrir una errata en name solo después de subirlo
Motivo: tras subir a la tienda, los metadatos del manifest no se pueden modificar en el panel del desarrollador; no es un tema de permisos, es así por regla. Forma correcta: revisa name y description letra por letra antes de subir; si de verdad hay un error, la única salida es modificar el manifest, aumentar version, volver a empaquetar y subir de nuevo.
🔧 Trucos avanzados (opcional)
- Vincular el esquema oficial de manifest al editor: asocia el esquema de manifest (json.schemastore.org/chrome-manifest) en tu editor de código; los campos mal escritos y los obligatorios que falten se marcan en rojo al instante, sin esperar a que Chrome rechace la carga para descubrirlo
version_nameyversion, cada uno con su función:versiones el número de versión mecánico que Chrome usa para comparar;version_name(por ejemplo"1.0 beta") es el alias legible para humanos que se muestra en la página de gestión de extensiones. Si quieres «un nombre de versión bonito + un número de versión estrictamente creciente», escribe ambosshort_nameal rescate: cuando el nombre es demasiado largo y falta espacio de visualización,short_name(≤12 caracteres) entra en juego; si no se escribe, Chrome truncanamepara mostrarlo
Resumen de la lección
✅ En esta lección has logrado:
- La estructura por capas de manifest.json: 3 campos obligatorios de la plataforma, 2 obligatorios de la tienda y 41 opcionales (incluidos 4 exclusivos de ChromeOS)
- Partiendo del ejemplo mínimo, construir paso a paso la sintaxis completa de action, background, content_scripts y permissions
- Las reglas de formato de version y la disciplina de «solo incrementar», más las dos reglas de oro: JSON sin comentarios y directorio raíz
- Lista de verificación antes de publicar: los metadatos no se pueden modificar tras subirlos, corregir una errata = publicar una nueva versión
Repaso de los campos de configuración clave:
| Campo | Valor recomendado / restricción | Descripción |
|---|---|---|
manifest_version | 3 | Único valor admitido |
name | ≤75 caracteres | Nombre del complemento que se muestra en tres lugares |
version | 0.0.0.1 como punto de partida, solo se incrementa | 1-4 segmentos de enteros separados por puntos, cada segmento 0-65536 |
description | ≤132 caracteres | Obligatorio para la tienda |
icons | 48 / 128 dos niveles como punto de partida | Obligatorio para la tienda, la ruta debe existir |
action.default_popup | hello.html | Página emergente que aparece al hacer clic en el icono |
background.service_worker | service-worker.js | Script central de eventos |
content_scripts[].matches | match pattern, obligatorio | Determina en qué páginas se inyecta |
permissions | Enumerar solo las API utilizadas | como ["storage"] |
host_permissions | Array de match patterns | Solicita autorización en la instalación |
Avance de la próxima lección
Con los campos declarados, la próxima lección C4 Content Script y Service Worker: el cerebro y las manos del complemento explica a fondo los mecanismos detrás de estos dos campos del manifest.
Aprenderás:
- La definición oficial de content script y service worker, y qué puede hacer cada uno
- El «mundo aislado»: por qué tu script y las variables de la página web no se ven entre sí
- Cómo elegir entre declaración estática, declaración dinámica e inyección programática
- El temperamento del service worker, que se inicia bajo demanda y se detiene al quedar inactivo, y cuándo usar cada uno