143 lines
5.8 KiB
Markdown
143 lines
5.8 KiB
Markdown
# web-admin 发版后强制刷新
|
||
|
||
> 日期：2026-10-16
|
||
> 适用范围：`web-admin` 生产构建与运行时
|
||
> 交互参考：`docs/superpowers/demos/2026-10-16-web-admin-version-refresh-demo.html`（方案 A · 强制弹窗）
|
||
> 决策：静态 `version.json` + 强制弹窗，确认后刷新页面
|
||
|
||
---
|
||
|
||
## 1. 目标与已确认决策
|
||
|
||
### 1.1 目标
|
||
|
||
1. 管理端发版后，仍停留在旧标签页的用户能得知已有新版本。
|
||
2. 用户只能通过「立即刷新」进入新包，不能关掉提示继续用旧功能。
|
||
3. 不依赖后端接口；随静态资源部署即生效。
|
||
|
||
### 1.2 决策摘要
|
||
|
||
| 项 | 约定 |
|
||
|----|------|
|
||
| 方案 | **A**：Vite 构建写出 `dist/version.json`，前端比对 `buildId` |
|
||
| 交互 | 强制弹窗，无「稍后 / 取消 / 关闭」；确认后 `location.reload()` |
|
||
| 未保存表单 | 不另做二次确认，直接弹刷新提示 |
|
||
| 展示版本 | 现有 `VITE_VERSION`（注入 `__APP_VERSION__`） |
|
||
| 比对指纹 | `buildId` = 短 git hash + 构建时间戳（注入 `__APP_BUILD_ID__`） |
|
||
| 轮询 | 生产环境启动后立即查一次，之后每 **10 分钟** |
|
||
| 回前台 | `document.visibilityState === 'visible'` 时立刻再查；距上次请求不足 **30 秒**则跳过 |
|
||
| 开发环境 | `pnpm dev` 不检查 |
|
||
|
||
### 1.3 非目标
|
||
|
||
- 后端版本接口、按发版类型切换「可稍后」
|
||
- 小程序更新（已有 `miniprogram/utils/mpUpdate.js`）
|
||
- 未保存表单的草稿保护或刷新前二次确认
|
||
- 修改 `VITE_VERSION` 的人工发版流程（展示号可不变，`buildId` 每次构建都会变）
|
||
|
||
---
|
||
|
||
## 2. 背景
|
||
|
||
`web-admin` 是 Vite 打包的 SPA（hash 路由）。用户长时间不关标签页时，内存里仍是旧的 JS。现有 `__APP_VERSION__`（来自 `VITE_VERSION`，当前 `3.0.2`）只用于本地存储键隔离（`web-admin/src/utils/storage/storage-config.ts`），发版后不会提示刷新。若发版时忘记改 `VITE_VERSION`，仅比对该字段还会漏报。因此展示用版本号，是否更新用每次构建都变化的 `buildId`。
|
||
|
||
---
|
||
|
||
## 3. 构建产物
|
||
|
||
### 3.1 `dist/version.json`
|
||
|
||
构建结束时写入，与 `index.html` 同目录（受 `VITE_BASE_URL` 影响时，文件仍在 `outDir` 根上，由静态服务器按 base 提供）：
|
||
|
||
```json
|
||
{
|
||
"version": "3.0.2",
|
||
"buildId": "a1b2c3d-1730000000000"
|
||
}
|
||
```
|
||
|
||
| 字段 | 来源 | 用途 |
|
||
|------|------|------|
|
||
| `version` | `VITE_VERSION` | 弹窗展示 |
|
||
| `buildId` | `git rev-parse --short HEAD`，失败时用 `nogit`；再拼接 `-` + 构建时刻毫秒时间戳 | 是否为新包的唯一比对键 |
|
||
|
||
同一 commit 再次 `pnpm build`，时间戳不同，`buildId` 必须变化。
|
||
|
||
### 3.2 包内常量
|
||
|
||
在现有 `define.__APP_VERSION__` 旁增加 `__APP_BUILD_ID__`，值与当次 `version.json` 的 `buildId` 相同。类型声明写在 `web-admin/src/env.d.ts`。
|
||
|
||
### 3.3 插件位置
|
||
|
||
在 `web-admin/vite.config.ts` 的 `plugins` 中增加一个仅 `apply: 'build'` 的插件：`closeBundle`（或等价的构建结束钩子）写文件，并在 `config` 阶段把 `buildId` 配进 `define`。开发服务器不写该文件、不注入会触发检查的生产逻辑。
|
||
|
||
---
|
||
|
||
## 4. 运行时
|
||
|
||
### 4.1 模块
|
||
|
||
新增 `web-admin/src/utils/check-app-update.ts`，由 `web-admin/src/main.ts` 在 `app.mount` 之后调用 `startAppUpdateCheck()`。
|
||
|
||
职责：
|
||
|
||
1. `import.meta.env.PROD` 为假时直接返回。
|
||
2. 请求 `${import.meta.env.BASE_URL}version.json?t=${Date.now()}`，`cache: 'no-store'`。
|
||
3. 解析 JSON。`buildId` 为非空字符串且与 `__APP_BUILD_ID__` 不同时弹窗。
|
||
4. 弹窗已打开或已经弹过则不再弹。弹出时清除定时器并移除 `visibilitychange` 监听，不再继续检查。
|
||
|
||
### 4.2 调度
|
||
|
||
- 启动后立即检查一次。
|
||
- `setInterval` 10 分钟。
|
||
- `visibilitychange`：变为 `visible` 时检查；若距上次**发起请求**不足 30 秒则跳过。
|
||
- 页面卸载时移除监听并清除定时器。
|
||
|
||
### 4.3 弹窗
|
||
|
||
使用 Element Plus `ElMessageBox.alert`（自动导入，不手写 import）：
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| 标题 | 发现新版本 |
|
||
| 正文 | 系统已发布更新，当前页面仍在使用旧功能。请刷新后继续操作。 |
|
||
| 版本行 | 远端 `version` 为非空字符串时追加：`当前 v{__APP_VERSION__} / 最新 v{远端 version}` |
|
||
| 确认按钮 | 立即刷新 |
|
||
| `showClose` | `false` |
|
||
| `closeOnClickModal` | `false` |
|
||
| `closeOnPressEscape` | `false` |
|
||
| `showCancelButton` | `false` |
|
||
|
||
用户点击「立即刷新」后执行一次 `location.reload()`（模块内标志位保证只触发一次）。遮罩无背景模糊，与现有弹窗一致。
|
||
|
||
多个标签页各自检查、各自弹窗。
|
||
|
||
---
|
||
|
||
## 5. 失败处理
|
||
|
||
| 情况 | 行为 |
|
||
|------|------|
|
||
| 网络失败、非 2xx、JSON 无法解析、缺少 `buildId` | 不提示，保留定时器，下一轮再试 |
|
||
| `buildId` 相同 | 不提示 |
|
||
| `buildId` 不同 | 弹一次窗并停止后续检查 |
|
||
| 远端无 `version` | 仍按 `buildId` 弹窗，正文不带版本行 |
|
||
|
||
---
|
||
|
||
## 6. 部署注意
|
||
|
||
前端请求已绕过 HTTP 缓存。静态服务器仍应为 `index.html` 与 `version.json` 设置短缓存或 `no-cache`。二者若被长期强缓存，用户点刷新后仍可能拿到旧的 `index.html`。带 hash 的 JS/CSS 可继续长期缓存。
|
||
|
||
本设计不新增 Nginx 配置文件；上线时由现有发布方式保证这两份入口文件可被重新验证。
|
||
|
||
---
|
||
|
||
## 7. 验证
|
||
|
||
1. 连续构建两次，两次 `dist/version.json` 的 `buildId` 不同。
|
||
2. 用第一版打开页面，再换成第二版静态资源：等待轮询，或切走标签页超过 30 秒后再切回，出现不可关闭的「发现新版本」。
|
||
3. 点击「立即刷新」后加载第二版，不再弹窗。
|
||
4. 删除或无法访问 `version.json` 时，业务页面仍可操作，控制台不把该失败当成未捕获异常打断应用。
|
||
5. `pnpm dev` 不请求 `version.json`。
|