Як написати файл manifest.json для Manifest V3

Коротка відповідь

Маніфест Manifest V3 оголошує ідентичність, точки входу та можливості розширення. Обов’язкові ключі платформи — manifest_version, name і version; ключі функцій мають відповідати реальній поведінці. Вікно панелі не потребує воркера, а воркер сам по собі не надає доступу до сайтів.

Сприймайте маніфест як перевірюваний контракт встановленого пакета. Ключ із worker.js означає, що файл має існувати в корені пакета. Шаблон хоста означає, що продукт має причину взаємодіяти з такими сайтами. Копіювання великого стартового маніфесту створює відсутні файли й запити дозволів, які функція може взагалі не використовувати.

Практичні кроки реалізації

Спершу задайте ідентичність

Використовуйте правильний JSON і числову версію з крапками, наприклад 1.0.0. Не додавайте prerelease-суфікс у version; людиночитна назва належить version_name. Дотримуйтеся обмеження довжини опису та додайте справжні іконки пакета перед публікацією.

Назвіть поверхню та точку входу

action.default_popup відкриває HTML-сторінку розширення. background.service_worker називає єдиний файл воркера; додайте type: "module", якщо він використовує модульні імпорти. options_ui.page налаштовує сторінку параметрів. Жодне поле не має посилатися на вихідний TypeScript або локальний сервер розробки.

Розрізняйте три оголошення доступу

permissions вмикає названі API, наприклад storage або scripting. host_permissions надає доступ до оголошених джерел сайтів для відповідних операцій. content_scripts.matches визначає місце впровадження оголошеного контентного скрипту. Вони пов’язані, але не взаємозамінні: host-дозвіл сам не запускає скрипт, а storage не надає доступу до DOM.

Виберіть автоматичний доступ чи виклик користувачем

Для разового дослідження сторінки activeTab разом із scripting часто відповідає взаємодії. Для автоматичного доповнення одного сайту оголосіть контентний скрипт із вузьким шаблоном. Необов’язкові host-дозволи можуть відкласти доступ до увімкнення відповідної функції користувачем. Файлові URL і захищені сторінки браузера потребують окремої уваги; широкий шаблон не обходить обмеження браузера.

Перевірте вихідний маніфест

Завантажте вихідну папку й за повідомленням Chrome знайдіть помилки JSON, непідтримувані значення та відсутні шляхи. Перевірте також корінь ZIP: додаткова зовнішня папка може помістити manifest.json нижче очікуваного кореня. Зберігайте пояснення кожної можливості в документації репозиторію замість недопустимих JSON-коментарів.

Приклад реалізації

Це вікно дослідження, яке запускає користувач, зі збереженими вподобаннями. Приберіть storage та options_ui, якщо параметрів немає; приберіть background, якщо немає подій воркера. Усі названі файли мають бути в пакеті.

{
  "manifest_version": 3,
  "name": "Focused page inspector",
  "description": "Inspect the current page when requested.",
  "version": "1.0.0",
  "action": { "default_popup": "popup.html" },
  "background": { "service_worker": "worker.js", "type": "module" },
  "options_ui": { "page": "options.html", "open_in_tab": true },
  "permissions": ["activeTab", "scripting", "storage"],
  "icons": { "16": "icons/16.png", "48": "icons/48.png", "128": "icons/128.png" }
}

Автоматичний скрипт має інше оголошення. Воно охоплює HTTPS-сторінки конкретного хоста та піддоменів; document_idle підходить DOM-завданню, якому не треба перехоплювати початковий розбір документа. Не додавайте це до попереднього прикладу без потреби в автоматичній поведінці.

{
  "content_scripts": [{
    "matches": ["https://*.example.com/*"],
    "js": ["content.js"],
    "run_at": "document_idle"
  }]
}

Компроміси та альтернативи

Генерація маніфесту допомагає правильно посилатися на хешовані ресурси, але результат має бути читабельним і перевіреним. Відокремте конфігурації розробки й випуску, якщо потреби різні; порівняйте дозволи перед випуском, щоб виявити випадкове розширення доступу.

Використовуйте minimum_chrome_version, коли обов’язковий API потребує мінімальної версії браузера. Вибирайте її за документацією API, а не версією своєї машини. Зайве високе значення виключає користувачів; відсутність потрібного обмеження допускає непідтримувані встановлення. Font Picker ілюструє вузьке призначення, але його сторінка не доводить, що кожному інспектору потрібні дозволи прикладу.

Поширені помилки

• Залишати JSON-коментарі чи завершальні коми у файлі.
• Використовувати background.scripts із Manifest V2 замість service_worker.
• Оголошувати tabs або всі хости без відповідної потреби доступу до даних.
• Очікувати, що web_accessible_resources вмикає впровадження скриптів; поле відкриває вибрані ресурси визначеним вебджерелам.
• Припускати роботу локалізованих підстановок без default_locale та відповідних файлів повідомлень.

Контрольний список випуску

• ☐ Маніфест розбирається як JSON, кожен шлях існує в остаточному корені.
• ☐ Кожен дозвіл і шаблон хоста має конкретне пояснення функцією.
• ☐ Конфігурація модульного воркера відповідає зібраному JavaScript.
• ☐ Версія й мінімальна сумісність відповідають документованим форматам.
• ☐ Опис Store, іконки й повідомлення про приватність відповідають поведінці пакета.
• ☐ Завантажений ZIP збігається з артефактом, який перевіряли.

Поширені запитання

Чи запускає натискання вікна також action.onClicked?

Ні. Якщо вікно налаштоване, кнопка відкриває його. Розмістіть взаємодію у вікні або виберіть кнопку без вікна.

Чи замінюють необов’язкові дозволи пояснення доступу?

Ні. Вони відкладають запит, але також потребують мети й відновлення після відмови.

Що перевіряти після зміни маніфесту?

Перезавантажте розширення, перегляньте помилки встановлення та перевірте змінену можливість. JSON-парсер доводить синтаксис, а не відповідність дозволів потрібній операції.

Первинні джерела

• Формат маніфесту
• Оголошення дозволів
• Шаблони URL
• Формат версії розширення

Пов’язані посібники та приклади

• Тематичний розділ
• Як створити розширення Chrome з Manifest V3
• Структура проєкту розширення Chrome, що масштабується
• Як працюють сервісні воркери розширень Chrome
• Дослідження сторінок у Font Picker