IHOR.DEVБАЗА_ЗНАНЬ
МЕНЮ

~/blog / Публікація / chrome-extension-versioning-and-user-migrations.md

// посібник · 3 хв читання

Версіонування розширень Chrome і міграції користувачів

Розрізняйте версію пакета й схеми; мігруйте параметри повторно безпечно, зберігайте вибір користувача й перевіряйте старі дані.

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

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

Використовуйте onInstalled як тригер, але не єдиний захист читання старих даних. Перезавантаження розпакованого пакета теж викликає оновлення, а користувачі можуть пропускати релізи. Читачі мають розуміти всі підтримувані версії або очікувати спільного завершення міграції.

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

  1. Задокументуйте стару й нову схеми, типові значення справді відсутніх полів і поведінку невідомої версії. Не вважайте пошкоджені дані новим встановленням мовчки.
  2. Реалізуйте чисте перетворення й перевірте старі, вже мігровані, відсутні та непідтримувані майбутні дані. Повторний запуск не має дублювати записи чи стирати вибір.
  3. За можливості записуйте перетворений об’єкт і версію схеми разом. Централізуйте відповідальність: два активні автори можуть змагатися навіть з await кожного виклику.
  4. Узгодьте читачів із міграцією. Спершу реєструйте слухачі воркера, потім очікуйте промісу міграції в обробниках. Не залишайте проміжку асинхронної ініціалізації без слухача.
  5. Збережіть відновлення. Експортуйте чи резервуйте важливі записи перед руйнівним перетворенням і визначте поведінку старого пакета з новими даними. Відкат пакета не відкочує сховище автоматично.

Для запусків на зразок LocaleStress формат звіту й сумісність порівняння важливі окремо від версії розширення. Збережіть ідентичність та пояснюйте неможливість порівняння замість вигаданих результатів із неповних старих полів. Це приклад дизайну, а не твердження про міграції продукту.

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

Приклад перетворює старий параметр виділення у версійований запис. Майбутні версії відхиляються без перезапису. Окремо визначте поведінку пошкоджених значень, що не є об’єктами.

export function migrateSettings(input) {
  if (input === undefined) return { schemaVersion: 2, highlights: true };
  if (typeof input !== "object" || input === null) throw new Error("Invalid settings");
  if (input.schemaVersion === 2) {
    if (typeof input.highlights !== "boolean") throw new Error("Invalid highlights");
    return { schemaVersion: 2, highlights: input.highlights };
  }
  if (input.schemaVersion !== undefined && input.schemaVersion !== 1) {
    throw new Error("Unsupported settings schema");
  }
  const legacy = input.showHighlights;
  return { schemaVersion: 2, highlights: typeof legacy === "boolean" ? legacy : true };
}

Записуйте лише власний ключ settings та свідомо видаляйте старі поля після підтвердження нового запису. Чиста функція не доводить фактичного встановленого оновлення: потрібні старі збережені дані й новий пакет.

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

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

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

  • Скидати параметри на кожній події onInstalled.
  • Прирівнювати версію пакета до схеми кожного запису.
  • Записувати новий маркер схеми до перетворених даних.
  • Вважати відкат автоматичним відновленням сховища.

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

  • Підтримувані схеми й майбутня поведінка визначені явно.
  • Чисті приклади охоплюють пропущені версії та повторну міграцію.
  • Читачі очікують відповідальної міграції.
  • Записи зберігають вибір і можливість відновлення.
  • Реальний сценарій оновлення перевіряє пакет релізу.

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

Чи version може мати prerelease-суфікс?

Використовуйте документований числовий формат із крапками для version; людиночитні назви належать version_name.

Чи мігрувати лише за нових зображень?

Лише якщо змінюється контракт збережених даних. Розрізняйте номер релізу та перетворення даних.

Яка вирішальна перевірка?

Завантажте репрезентативні старі дані, оновіть точним новим артефактом і підтвердьте збережений вибір та нову поведінку без відкритого налагодження воркера.

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

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

Ігор Харчишин

Незалежний full-stack інженер продуктів, який пише посібники з реалізації розширень браузера та сучасних вебпродуктів на основі першоджерел.

Потрібно реалізувати це у вашому продукті?

Інструменти браузера з чіткою метою, обґрунтованими дозволами та підтримуваною архітектурою Manifest V3.