From c9f78ef25ff6d8a8daca18c032f1cf0d1507640b Mon Sep 17 00:00:00 2001
From: dekun <dekun@local>
Date: Fri, 5 Jun 2026 17:47:57 +0800
Subject: [PATCH] Fix PWA install by registering service worker in theme

VitePress did not auto-inject SW registration; manual registerSW enables true app install on HTTPS.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .vitepress/pwa.mts        |  3 ++-
 .vitepress/theme/index.ts |  6 ++++++
 DEPLOY.md                 | 23 +++++++++++++++++++++++
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/.vitepress/pwa.mts b/.vitepress/pwa.mts
index ed61b62..2f8d99a 100644
--- a/.vitepress/pwa.mts
+++ b/.vitepress/pwa.mts
@@ -3,7 +3,7 @@ import { VitePWA } from 'vite-plugin-pwa'
 export function createPwaPlugin() {
   return VitePWA({
     registerType: 'autoUpdate',
-    injectRegister: 'auto',
+    injectRegister: null,
     manifestFilename: 'site.webmanifest',
     includeAssets: [
       'favicon.ico',
@@ -14,6 +14,7 @@ export function createPwaPlugin() {
       'icon-512.png',
     ],
     manifest: {
+      id: '/',
       name: '道德经 · 传统文化典籍',
       short_name: '道德经',
       description: '传统文化典籍资料库',
diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts
index b26fca8..89fbdfd 100644
--- a/.vitepress/theme/index.ts
+++ b/.vitepress/theme/index.ts
@@ -2,6 +2,12 @@ import DefaultTheme from 'vitepress/theme'
 import { h } from 'vue'
 import InstallApp from './InstallApp.vue'
 
+if (typeof window !== 'undefined') {
+  import('virtual:pwa-register').then(({ registerSW }) => {
+    registerSW({ immediate: true })
+  })
+}
+
 export default {
   extends: DefaultTheme,
   Layout: () => {
diff --git a/DEPLOY.md b/DEPLOY.md
index 64e5c88..6a0436e 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -367,6 +367,29 @@ ss -tlnp | grep 12100
 - **对外访问必须使用 HTTPS**（云服务器反代层配置 SSL）
 - 内网 `http://192.168.x.x:12100` 仅适合调试，Android 通常不会弹出「安装应用」
 
+### 只能「创建快捷方式」，没有「安装应用」？
+
+常见两个原因：
+
+**1. 用了 HTTP 内网地址（如 `http://192.168.x.x:12100`）**
+
+| 访问方式 | 浏览器行为 |
+|----------|------------|
+| HTTP 内网 IP | 只能「创建快捷方式」，**不能**真正安装 PWA |
+| **HTTPS 域名** | 可「安装应用 / 添加到主屏幕」 |
+
+**2. Service Worker 未注册（已在最新代码修复）**
+
+更新后按 F12 → **Application（应用）** → **Service Workers**，应看到 `/sw.js` 状态为 **activated**。
+
+若仍是红色报错，执行：
+
+```bash
+git pull && npm install && npm run build && npm run start
+```
+
+然后 **Ctrl+Shift+R** 强刷，或删除旧快捷方式后重装。
+
 ### 电脑（Chrome / Edge）
 
 1. 用 HTTPS 域名打开站点并登录