docs: record web-admin force-refresh design for stale open tabs.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
181bb808f2
commit
c527af0b1d
2 files changed
+703
No files matched your search
@@ -0,0 +1,561 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>web-admin · 发版后提示刷新 Demo</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
|
||||
<style>
|
||||
:root {
|
||||
--primary: #10b981;
|
||||
--primary-dark: #059669;
|
||||
--primary-bg: #ecfdf5;
|
||||
--text: #1e293b;
|
||||
--text-muted: #64748b;
|
||||
--border: #d9e8e2;
|
||||
--bg-page: #fefefe;
|
||||
--surface: #ffffff;
|
||||
--table-head: #f7faf8;
|
||||
--row-alt: #f1f5f9;
|
||||
--shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
|
||||
--radius: 10px;
|
||||
--warn: #d97706;
|
||||
--warn-bg: #fffbeb;
|
||||
--mask: rgba(15, 23, 42, 0.35);
|
||||
}
|
||||
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
|
||||
body {
|
||||
font-family: Inter, -apple-system, sans-serif;
|
||||
font-size: 14px;
|
||||
line-height: 1.5;
|
||||
color: var(--text);
|
||||
background: #0f172a;
|
||||
min-height: 100vh;
|
||||
padding: 28px 20px 48px;
|
||||
}
|
||||
|
||||
.page-head {
|
||||
max-width: 1100px;
|
||||
margin: 0 auto 20px;
|
||||
text-align: center;
|
||||
color: #fff;
|
||||
}
|
||||
.page-head h1 { font-size: 20px; font-weight: 600; margin-bottom: 8px; }
|
||||
.page-head p {
|
||||
color: #94a3b8;
|
||||
font-size: 13px;
|
||||
max-width: 640px;
|
||||
margin: 0 auto;
|
||||
}
|
||||
|
||||
.controls {
|
||||
max-width: 1100px;
|
||||
margin: 0 auto 16px;
|
||||
display: flex;
|
||||
flex-wrap: wrap;
|
||||
gap: 8px;
|
||||
justify-content: center;
|
||||
}
|
||||
.controls button {
|
||||
appearance: none;
|
||||
border: 1px solid #334155;
|
||||
background: #1e293b;
|
||||
color: #e2e8f0;
|
||||
border-radius: 8px;
|
||||
padding: 8px 14px;
|
||||
font-size: 13px;
|
||||
font-family: inherit;
|
||||
cursor: pointer;
|
||||
transition: border-color .15s, background .15s;
|
||||
}
|
||||
.controls button:hover { border-color: var(--primary); }
|
||||
.controls button.is-active {
|
||||
background: var(--primary-bg);
|
||||
border-color: var(--primary);
|
||||
color: var(--primary-dark);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.stage-wrap {
|
||||
max-width: 1100px;
|
||||
margin: 0 auto;
|
||||
border-radius: 14px;
|
||||
overflow: hidden;
|
||||
box-shadow: 0 24px 64px rgba(0, 0, 0, 0.45);
|
||||
border: 1px solid #334155;
|
||||
background: var(--bg-page);
|
||||
position: relative;
|
||||
min-height: 560px;
|
||||
}
|
||||
|
||||
/* —— 仿管理端壳 —— */
|
||||
.shell { display: flex; min-height: 560px; }
|
||||
.sidebar {
|
||||
width: 200px;
|
||||
flex-shrink: 0;
|
||||
background: var(--surface);
|
||||
border-right: 1px solid var(--border);
|
||||
padding: 20px 14px;
|
||||
}
|
||||
.brand {
|
||||
font-weight: 700;
|
||||
font-size: 15px;
|
||||
color: var(--primary-dark);
|
||||
margin-bottom: 20px;
|
||||
padding: 0 6px;
|
||||
}
|
||||
.nav-item {
|
||||
padding: 9px 10px;
|
||||
border-radius: 8px;
|
||||
color: var(--text-muted);
|
||||
font-size: 13px;
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
.nav-item.is-active {
|
||||
background: var(--primary-bg);
|
||||
color: var(--primary-dark);
|
||||
font-weight: 600;
|
||||
}
|
||||
.main { flex: 1; display: flex; flex-direction: column; min-width: 0; }
|
||||
.topbar {
|
||||
height: 52px;
|
||||
border-bottom: 1px solid var(--border);
|
||||
background: var(--surface);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
padding: 0 20px;
|
||||
font-size: 13px;
|
||||
color: var(--text-muted);
|
||||
}
|
||||
.topbar .user { color: var(--text); font-weight: 500; }
|
||||
.content { padding: 20px; flex: 1; }
|
||||
.panel {
|
||||
background: var(--surface);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: var(--radius);
|
||||
box-shadow: var(--shadow);
|
||||
overflow: hidden;
|
||||
}
|
||||
.panel-top {
|
||||
padding: 14px 16px;
|
||||
border-bottom: 1px solid var(--border);
|
||||
background: var(--table-head);
|
||||
}
|
||||
.panel-top h2 {
|
||||
font-size: 15px;
|
||||
font-weight: 600;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
}
|
||||
.panel-top h2::before {
|
||||
content: "";
|
||||
width: 3px;
|
||||
height: 14px;
|
||||
border-radius: 2px;
|
||||
background: var(--primary);
|
||||
}
|
||||
.toolbar {
|
||||
padding: 10px 16px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 10px;
|
||||
border-bottom: 1px solid var(--border);
|
||||
font-size: 13px;
|
||||
color: var(--text-muted);
|
||||
}
|
||||
.btn {
|
||||
appearance: none;
|
||||
border: 1px solid var(--border);
|
||||
background: var(--surface);
|
||||
color: var(--text);
|
||||
border-radius: 8px;
|
||||
height: 32px;
|
||||
padding: 0 12px;
|
||||
font-size: 13px;
|
||||
font-family: inherit;
|
||||
cursor: pointer;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
}
|
||||
.btn-main {
|
||||
background: var(--primary);
|
||||
border-color: var(--primary);
|
||||
color: #fff;
|
||||
font-weight: 500;
|
||||
}
|
||||
.btn-main:hover { background: var(--primary-dark); }
|
||||
table { width: 100%; border-collapse: collapse; font-size: 13px; }
|
||||
th, td { padding: 10px 14px; text-align: left; border-bottom: 1px solid var(--border); }
|
||||
th { background: var(--table-head); color: var(--text-muted); font-weight: 500; }
|
||||
tr:nth-child(even) td { background: var(--row-alt); }
|
||||
.tag {
|
||||
display: inline-block;
|
||||
padding: 2px 8px;
|
||||
border-radius: 4px;
|
||||
font-size: 12px;
|
||||
background: #059669;
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
.version-chip {
|
||||
font-size: 11px;
|
||||
color: var(--text-muted);
|
||||
background: var(--row-alt);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 999px;
|
||||
padding: 2px 8px;
|
||||
}
|
||||
|
||||
/* —— A:强制弹窗 —— */
|
||||
.overlay {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
background: var(--mask);
|
||||
display: none;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
z-index: 40;
|
||||
backdrop-filter: none;
|
||||
}
|
||||
.overlay.is-on { display: flex; }
|
||||
.dialog {
|
||||
width: 420px;
|
||||
max-width: calc(100% - 40px);
|
||||
background: var(--surface);
|
||||
border-radius: var(--radius);
|
||||
box-shadow: 0 20px 48px rgba(15, 23, 42, 0.18);
|
||||
overflow: hidden;
|
||||
animation: pop .2s ease-out;
|
||||
}
|
||||
@keyframes pop {
|
||||
from { opacity: 0; transform: translateY(8px) scale(0.98); }
|
||||
to { opacity: 1; transform: none; }
|
||||
}
|
||||
.dialog-body { padding: 24px 24px 8px; }
|
||||
.dialog-icon {
|
||||
width: 44px;
|
||||
height: 44px;
|
||||
border-radius: 12px;
|
||||
background: var(--primary-bg);
|
||||
color: var(--primary-dark);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
font-size: 22px;
|
||||
margin-bottom: 14px;
|
||||
}
|
||||
.dialog-body h3 { font-size: 16px; font-weight: 600; margin-bottom: 8px; }
|
||||
.dialog-body p { color: var(--text-muted); font-size: 13px; margin-bottom: 6px; }
|
||||
.dialog-meta {
|
||||
margin-top: 12px;
|
||||
padding: 10px 12px;
|
||||
background: var(--table-head);
|
||||
border-radius: 8px;
|
||||
font-size: 12px;
|
||||
color: var(--text-muted);
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
gap: 12px;
|
||||
}
|
||||
.dialog-meta strong { color: var(--text); font-weight: 600; }
|
||||
.dialog-footer {
|
||||
padding: 16px 24px 20px;
|
||||
display: flex;
|
||||
justify-content: flex-end;
|
||||
gap: 10px;
|
||||
}
|
||||
|
||||
/* —— B:顶部横幅 —— */
|
||||
.banner {
|
||||
display: none;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
padding: 10px 16px;
|
||||
background: var(--warn-bg);
|
||||
border-bottom: 1px solid rgba(217, 119, 6, 0.25);
|
||||
color: #92400e;
|
||||
font-size: 13px;
|
||||
z-index: 30;
|
||||
}
|
||||
.banner.is-on { display: flex; }
|
||||
.banner .dot {
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
border-radius: 50%;
|
||||
background: var(--warn);
|
||||
flex-shrink: 0;
|
||||
animation: pulse 1.4s ease-in-out infinite;
|
||||
}
|
||||
@keyframes pulse {
|
||||
0%, 100% { opacity: 1; }
|
||||
50% { opacity: 0.35; }
|
||||
}
|
||||
.banner .msg { flex: 1; min-width: 0; }
|
||||
.banner .msg strong { color: #b45309; }
|
||||
.banner .actions { display: flex; gap: 8px; flex-shrink: 0; }
|
||||
.btn-warn {
|
||||
background: var(--warn);
|
||||
border-color: var(--warn);
|
||||
color: #fff;
|
||||
height: 28px;
|
||||
padding: 0 10px;
|
||||
font-size: 12px;
|
||||
}
|
||||
.btn-ghost {
|
||||
background: transparent;
|
||||
border-color: rgba(217, 119, 6, 0.35);
|
||||
color: #92400e;
|
||||
height: 28px;
|
||||
padding: 0 10px;
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
/* —— C:右下角通知 —— */
|
||||
.toast {
|
||||
position: absolute;
|
||||
right: 20px;
|
||||
bottom: 20px;
|
||||
width: 360px;
|
||||
max-width: calc(100% - 40px);
|
||||
background: var(--surface);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: var(--radius);
|
||||
box-shadow: 0 12px 32px rgba(15, 23, 42, 0.12);
|
||||
padding: 14px 16px;
|
||||
display: none;
|
||||
z-index: 35;
|
||||
animation: slideUp .22s ease-out;
|
||||
}
|
||||
.toast.is-on { display: block; }
|
||||
@keyframes slideUp {
|
||||
from { opacity: 0; transform: translateY(12px); }
|
||||
to { opacity: 1; transform: none; }
|
||||
}
|
||||
.toast-top {
|
||||
display: flex;
|
||||
align-items: flex-start;
|
||||
gap: 10px;
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
.toast-icon {
|
||||
width: 32px;
|
||||
height: 32px;
|
||||
border-radius: 8px;
|
||||
background: var(--primary-bg);
|
||||
color: var(--primary-dark);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
flex-shrink: 0;
|
||||
font-size: 16px;
|
||||
}
|
||||
.toast h4 { font-size: 14px; font-weight: 600; }
|
||||
.toast p { font-size: 12px; color: var(--text-muted); margin-top: 2px; }
|
||||
.toast-actions {
|
||||
display: flex;
|
||||
justify-content: flex-end;
|
||||
gap: 8px;
|
||||
}
|
||||
.toast .btn { height: 28px; font-size: 12px; padding: 0 10px; }
|
||||
|
||||
.legend {
|
||||
max-width: 1100px;
|
||||
margin: 18px auto 0;
|
||||
color: #94a3b8;
|
||||
font-size: 12px;
|
||||
line-height: 1.7;
|
||||
text-align: center;
|
||||
}
|
||||
.legend code {
|
||||
background: #1e293b;
|
||||
color: #cbd5e1;
|
||||
padding: 1px 6px;
|
||||
border-radius: 4px;
|
||||
font-size: 11px;
|
||||
}
|
||||
|
||||
@media (max-width: 800px) {
|
||||
.sidebar { display: none; }
|
||||
.banner { flex-wrap: wrap; }
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="page-head">
|
||||
<h1>web-admin · 发版后「请刷新」交互 Demo</h1>
|
||||
<p>
|
||||
模拟客户长时间不关标签页、仍跑旧前端的场景。下面三种提示样式可切换对比;
|
||||
Token 对齐 Fresh Mint(<code style="color:#a7f3d0">#10b981</code>)。
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<div class="controls" role="tablist" aria-label="提示样式">
|
||||
<button type="button" class="is-active" data-mode="force" aria-pressed="true">A · 强制弹窗(推荐)</button>
|
||||
<button type="button" data-mode="banner" aria-pressed="false">B · 顶部横幅(可稍后)</button>
|
||||
<button type="button" data-mode="toast" aria-pressed="false">C · 右下角通知</button>
|
||||
<button type="button" data-mode="none" aria-pressed="false">隐藏提示</button>
|
||||
</div>
|
||||
|
||||
<div class="stage-wrap" id="stage">
|
||||
<!-- B: banner sits above shell content -->
|
||||
<div class="banner" id="banner" role="status">
|
||||
<span class="dot" aria-hidden="true"></span>
|
||||
<div class="msg">
|
||||
<strong>系统已更新</strong>
|
||||
— 检测到新版本 <strong>3.0.3</strong>(当前页面仍为 3.0.2),请刷新以使用最新功能。
|
||||
</div>
|
||||
<div class="actions">
|
||||
<button type="button" class="btn btn-ghost" data-action="later">稍后</button>
|
||||
<button type="button" class="btn btn-warn" data-action="reload">立即刷新</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="shell">
|
||||
<aside class="sidebar">
|
||||
<div class="brand">山峡化工 · 门户</div>
|
||||
<div class="nav-item is-active">订单列表</div>
|
||||
<div class="nav-item">商品管理</div>
|
||||
<div class="nav-item">单位管理</div>
|
||||
<div class="nav-item">系统用户</div>
|
||||
</aside>
|
||||
<div class="main">
|
||||
<header class="topbar">
|
||||
<span>工作台 / 订单列表</span>
|
||||
<span>
|
||||
<span class="version-chip" title="页面内嵌版本">页面 v3.0.2</span>
|
||||
|
||||
<span class="user">张三</span>
|
||||
</span>
|
||||
</header>
|
||||
<div class="content">
|
||||
<div class="panel">
|
||||
<div class="panel-top"><h2>订单列表</h2></div>
|
||||
<div class="toolbar">
|
||||
<span>已选 0 项</span>
|
||||
<button type="button" class="btn btn-main">新增订单</button>
|
||||
<button type="button" class="btn">导出</button>
|
||||
</div>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>订单号</th>
|
||||
<th>客户</th>
|
||||
<th>状态</th>
|
||||
<th>金额</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>SO20261016001</td>
|
||||
<td>华中物流</td>
|
||||
<td><span class="tag">配送中</span></td>
|
||||
<td>¥12,800</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SO20261016002</td>
|
||||
<td>海河化工</td>
|
||||
<td><span class="tag">已完成</span></td>
|
||||
<td>¥6,420</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SO20261015088</td>
|
||||
<td>金桥供应链</td>
|
||||
<td><span class="tag">待发货</span></td>
|
||||
<td>¥9,150</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- A: force modal -->
|
||||
<div class="overlay is-on" id="overlay" role="dialog" aria-modal="true" aria-labelledby="dlg-title">
|
||||
<div class="dialog">
|
||||
<div class="dialog-body">
|
||||
<div class="dialog-icon" aria-hidden="true">↻</div>
|
||||
<h3 id="dlg-title">发现新版本</h3>
|
||||
<p>系统已发布更新,当前页面仍在使用旧功能。请刷新后继续操作,避免数据与界面不一致。</p>
|
||||
<div class="dialog-meta">
|
||||
<span>当前:<strong>v3.0.2</strong></span>
|
||||
<span>最新:<strong>v3.0.3</strong></span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="dialog-footer">
|
||||
<!-- 强制模式:无「取消 / 稍后」 -->
|
||||
<button type="button" class="btn btn-main" data-action="reload">立即刷新</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- C: corner toast -->
|
||||
<div class="toast" id="toast" role="status">
|
||||
<div class="toast-top">
|
||||
<div class="toast-icon" aria-hidden="true">↻</div>
|
||||
<div>
|
||||
<h4>有可用更新</h4>
|
||||
<p>新版本 v3.0.3 已上线,刷新即可使用最新功能。</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="toast-actions">
|
||||
<button type="button" class="btn" data-action="later">稍后</button>
|
||||
<button type="button" class="btn btn-main" data-action="reload">立即刷新</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p class="legend">
|
||||
<strong style="color:#e2e8f0">对比要点</strong>:
|
||||
A 强制弹窗不可稍后(与小程序强制更新一致,适合破坏性发版);
|
||||
B 顶部横幅不打断当前填表,适合非紧急;
|
||||
C 右下角最轻,容易被忽略。
|
||||
检测侧通常对比本地 <code>__APP_VERSION__</code> / 构建产物 hash 与服务器上的 <code>version.json</code>。
|
||||
</p>
|
||||
|
||||
<script>
|
||||
(function () {
|
||||
var overlay = document.getElementById('overlay')
|
||||
var banner = document.getElementById('banner')
|
||||
var toast = document.getElementById('toast')
|
||||
var buttons = document.querySelectorAll('.controls button[data-mode]')
|
||||
|
||||
function setMode(mode) {
|
||||
overlay.classList.toggle('is-on', mode === 'force')
|
||||
banner.classList.toggle('is-on', mode === 'banner')
|
||||
toast.classList.toggle('is-on', mode === 'toast')
|
||||
buttons.forEach(function (btn) {
|
||||
var on = btn.getAttribute('data-mode') === mode
|
||||
btn.classList.toggle('is-active', on)
|
||||
btn.setAttribute('aria-pressed', on ? 'true' : 'false')
|
||||
})
|
||||
}
|
||||
|
||||
buttons.forEach(function (btn) {
|
||||
btn.addEventListener('click', function () {
|
||||
setMode(btn.getAttribute('data-mode'))
|
||||
})
|
||||
})
|
||||
|
||||
document.getElementById('stage').addEventListener('click', function (e) {
|
||||
var t = e.target
|
||||
if (!(t instanceof HTMLElement)) return
|
||||
var action = t.getAttribute('data-action')
|
||||
if (action === 'reload') {
|
||||
alert('Demo:实际实现会执行 location.reload()(或带 cache-bust 的硬刷新)')
|
||||
}
|
||||
if (action === 'later') {
|
||||
setMode('none')
|
||||
}
|
||||
})
|
||||
})()
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,142 @@
|
||||
# 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`。
|
||||
Reference in new issue
Block a user