Skip to content

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:

GrupoCamposQué pasa si faltan
Obligatorios de la plataforma (3)manifest_version, name, versionChrome rechaza la carga directamente y muestra un diálogo de error
Obligatorios para publicar en la tienda (2)description, iconsFunciona 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:

json
{
  "manifest_version": 3,
  "name": "My First Extension",
  "version": "1.0.0"
}

Las restricciones de cada uno de los tres campos:

CampoRestricciónExplicación
manifest_versionsolo admite 3MV3 es la única forma actual; el 2 de los tutoriales antiguos no lo copies
namemáximo 75 caracteresse muestra en la tienda, en el cuadro de diálogo de instalación y en la página chrome://extensions
version1-4 enteros separados por puntos, cada uno entre 0-65536como 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):

json
{
  "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 extensiones
  • icons: 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):

json
"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_popup especifica la página que se abre al pulsar el icono, default_icon especifica la imagen del icono
  • background: el archivo JS al que apunta service_worker es 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:

json
"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 ejemplo https://*.nytimes.com/*); todo content script de ejecución automática debe especificar un match pattern
  • js / 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:

json
"permissions": ["storage"],
"host_permissions": ["https://*.example.com/"]
  • permissions: en el array van los nombres de las APIs a activar, como storage, scripting, activeTab; declara solo las que realmente uses
  • host_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:

  1. Vuelve a chrome://extensions y 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)
  2. Si la carga falla, aparecerá un cuadro de diálogo de error — corrige el manifest según el mensaje y vuelve a refrescar
  3. Al preparar la publicación, revisa punto por punto:
Punto de revisiónCriterio
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
versionmayor 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
ComentariosNo incluyas ningún comentario en el JSON, de lo contrario la subida devolverá Cannot parse the manifest
EmpaquetadoEn 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) ​

CampoRestricciónFunción
manifest_versionEntero, único valor admitido 3Versión del formato del manifest
name≤75 caracteresNombre mostrado en la tienda, el diálogo de instalación y chrome://extensions
version1-4 enteros separados por puntos, cada segmento 0-65536Nú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) ​

CampoRestricciónFunción
description≤132 caracteresDescripción en la tienda y en la página de gestión de extensiones
iconsUno o más iconosIcono que representa la extensión

Opcionales de uso frecuente (conoce primero estos 5) ​

CampoPuntos clave de escrituraFunción
actiondefault_popup apunta a la página del popup, default_icon especifica el iconoApariencia 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_scriptsmatches obligatorio + arrays de js / cssJS/CSS que se inyecta automáticamente al abrir páginas web coincidentes
permissionsArray de nombres de API, por ejemplo ["storage"]Habilita APIs específicas de extensiones
host_permissionsArray de match patternsDeclara 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

CampoFunción
commandsDefine los atajos de teclado dentro de la extensión
options_pageEspecifica options.html como página de configuración de la extensión
options_uiPermite al usuario modificar las opciones de la extensión dentro de la página de gestión de extensiones
side_panelEspecifica la página HTML que se muestra en el panel lateral
omniboxRegistra una palabra clave en la barra de direcciones de Chrome
chrome_url_overridesAnula las páginas predeterminadas de Chrome
devtools_pageDefine páginas que usan la API de DevTools

Permisos y seguridad

CampoFunción
optional_permissionsDeclara permisos de API opcionales
optional_host_permissionsDeclara permisos de host opcionales
content_security_policyRestringe los recursos (scripts, estilos, etc.) que la extensión puede cargar
externally_connectableEspecifica qué páginas web y extensiones pueden conectarse a tu extensión
web_accessible_resourcesDefine archivos de la extensión accesibles desde páginas web u otras extensiones
sandboxDefine páginas en sandbox que no pueden usar directamente las APIs de extensiones
incognitoComportamiento en modo incógnito, valores spanning / split / not_allowed
keyEspecifica el ID de la extensión para fines de desarrollo

Red y datos

CampoFunción
declarative_net_requestReglas estáticas de solicitudes de red declarativas; permite interceptar y modificar solicitudes de red
oauth2Configura OAuth 2.0(client_id y scopes)
storageDeclara un esquema JSON para el área de almacenamiento administrado
tts_engineRegistra la extensión como motor de texto a voz
mime_types_handlerRegistra la extensión como manejador de un tipo MIME (por ejemplo application/pdf)
requirementsEnumera las tecnologías necesarias para usar el plugin

Versión y distribución

CampoFunción
version_nameAlias de versión legible para humanos (por ejemplo "1.0 beta"); si no se escribe, se muestra version
minimum_chrome_versionVersió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_urlURL de la página principal del plugin; si no se escribe, el valor predeterminado es la página de la tienda
update_urlDirección de la página de actualización cuando se distribuye de forma autoalojada (sin publicar en la tienda)
importPermite importar recursos hacia el plugin
exportPermite exportar recursos desde el plugin

Internacionalización y presentación

CampoFunción
default_localeIdioma predeterminado de plugins multilingües (por ejemplo en); obligatorio para plugins localizados, y no se puede usar en plugins no localizados
short_nameNombre corto, ≤12 caracteres; si no se escribe, se trunca name para mostrarlo

Ajustes de Chrome

CampoFunción
chrome_settings_overridesAnula algunos ajustes de Chrome
cross_origin_embedder_policyConfigura el encabezado de solicitud Cross-Origin-Embedder-Policy
cross_origin_opener_policyConfigura el encabezado de solicitud Cross-Origin-Opener-Policy

Exclusivos de ChromeOS (4 en total)

CampoFunción
file_browser_handlersAccede a las API relacionadas con el explorador de archivos de ChromeOS
file_handlersEspecifica los tipos de archivo que maneja el plugin de ChromeOS
file_system_provider_capabilitiesPermite que el plugin cree un sistema de archivos utilizable en ChromeOS
input_componentsUsa 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_version es 3; name ≤75 caracteres; version es 1-4 segmentos de enteros separados por puntos
  • Si vas a publicarlo en la tienda: description ≤132 caracteres, y cada ruta de icons existe realmente
  • El matches de content_scripts está escrito y cumple la sintaxis de match pattern
  • permissions solo declara las API que realmente se usan, sin errores ortográficos

Recordatorio de errores comunes ​

❌ Escribir comentarios en manifest.json ​

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 ​

json
"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_name y version, cada uno con su función: version es 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 ambos
  • short_name al 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 trunca name para 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:

CampoValor recomendado / restricciónDescripción
manifest_version3Único valor admitido
name≤75 caracteresNombre del complemento que se muestra en tres lugares
version0.0.0.1 como punto de partida, solo se incrementa1-4 segmentos de enteros separados por puntos, cada segmento 0-65536
description≤132 caracteresObligatorio para la tienda
icons48 / 128 dos niveles como punto de partidaObligatorio para la tienda, la ruta debe existir
action.default_popuphello.htmlPágina emergente que aparece al hacer clic en el icono
background.service_workerservice-worker.jsScript central de eventos
content_scripts[].matchesmatch pattern, obligatorioDetermina en qué páginas se inyecta
permissionsEnumerar solo las API utilizadascomo ["storage"]
host_permissionsArray de match patternsSolicita 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
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.