feat: chrome. implement offscreen document to keep service worker alive

Tokisaki-Galaxy · Tokisaki-Galaxy · commit 712cbab03c13 · 2026-01-05T09:46:57.000+08:00
diff --git a/src/background/main.ts b/src/background/main.ts
@@ -77,29 +77,34 @@ setBaseUrl(client.baseURL)
   .then(() => console.info('Started successfully'))
 
 /**
- * Keep the service worker alive to prevent Chrome's 5-minute inactivity termination
- * This is a workaround for Chrome's behavior of terminating inactive service workers
- * https://stackoverflow.com/questions/66618136
+ * Keep the service worker alive using Offscreen API to prevent Chrome's termination.
  */
-if (import.meta.env.VITE_TARGET_BROWSER === 'chrome') {
-  function setupKeepAlive(): void {
-    console.debug(
-      'Setting up keep-alive ping to prevent service worker termination',
-    )
+async function setupOffscreen() {
+  const _chrome = (globalThis as any).chrome
+  if (typeof _chrome === 'undefined' || !_chrome.offscreen) return
 
-    setInterval(
-      () => {
-        console.debug('Keep-alive ping')
-        // Force some minimal activity
-        browser.alarms
-          .get(config.heartbeat.alarmName)
-          .then(() => console.debug('Keep-alive ping completed'))
-          .catch((err) => console.error('Keep-alive ping failed:', err))
-      },
-      4 * 60 * 1000,
-    ) // 4 minutes (less than Chrome's ~5 minute timeout)
-  }
+  if (await _chrome.offscreen.hasDocument()) return
 
-  // Start the keep-alive mechanism
-  setupKeepAlive()
+  try {
+    await _chrome.offscreen.createDocument({
+      url: 'src/offscreen.html',
+      reasons: ['BLOBS'],
+      justification: 'Keep service worker alive for heartbeat packets',
+    })
+  } catch (e) {
+    console.error('Failed to create offscreen document:', e)
+  }
 }
+
+browser.runtime.onMessage.addListener((message: any) => {
+  if (message.type === 'KEEP_ALIVE') {
+    return Promise.resolve({ status: 'ok' })
+  }
+  return undefined
+})
+
+// Initialize on startup and installation
+browser.runtime.onStartup.addListener(setupOffscreen)
+browser.runtime.onInstalled.addListener(setupOffscreen)
+
+setupOffscreen()
diff --git a/src/manifest.json b/src/manifest.json
@@ -48,6 +48,7 @@
         "alarms",
         "notifications",
         "activeTab",
+        "offscreen",
         "storage"
     ],
     "{{safari}}.permissions": [
diff --git a/src/offscreen.html b/src/offscreen.html
@@ -0,0 +1,9 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+  </head>
+  <body>
+    <script type="module" src="./offscreen.ts"></script>
+  </body>
+</html>
diff --git a/src/offscreen.ts b/src/offscreen.ts
@@ -0,0 +1,11 @@
+import browser from 'webextension-polyfill'
+
+// 每隔 20 秒向 background 发送一次消息，确保 Service Worker 不被杀死
+function keepAlive() {
+  browser.runtime.sendMessage({ type: 'KEEP_ALIVE' }).catch(() => {
+    // Expected during reload
+  })
+}
+
+setInterval(keepAlive, 20 * 1000)
+keepAlive()
diff --git a/vite.config.ts b/vite.config.ts
@@ -20,7 +20,11 @@ export default defineConfig({
   plugins: [
     webExtension({
       manifest: generateManifest,
-      additionalInputs: ['src/consent/index.html', 'src/consent/main.ts'],
+      additionalInputs: [
+        'src/consent/index.html',
+        'src/consent/main.ts',
+        'src/offscreen.html',
+      ],
       browser: process.env.VITE_TARGET_BROWSER,
     }),
   ],
