perms-system-web/src/components/VersionChecker.md

版本检测组件 (VersionChecker)

功能说明

VersionChecker 是一个自动版本检测组件，用于检测应用是否有新版本可用，并在检测到新版本时提示用户更新。

主要特性

• ✅ 自动检测：应用启动时自动开始版本检测
• ✅ 定时检查：可配置检查间隔（默认 1 分钟）
• ✅ 智能提示：检测到新版本时显示友好的更新提示
• ✅ 防重复：可配置通知冷却时间，避免频繁提示
• ✅ 页面感知：页面隐藏时暂停检查，显示时恢复检查
• ✅ 资源清理：页面卸载时自动清理定时器
• ✅ 错误处理：网络错误时不会影响应用正常运行

使用方法

基本使用

import VersionChecker from '@/components/VersionChecker';

const App = () => {
  const currentBuildTime = process.env.REACT_APP_BUILD_TIME;

  return (
    <div>
      {/* 你的应用内容 */}
      <VersionChecker currentBuildTime={currentBuildTime} />
    </div>
  );
};

高级配置

<VersionChecker
  currentBuildTime={process.env.REACT_APP_BUILD_TIME}
  checkInterval={30 * 1000} // 30秒检查一次
  notificationCooldown={10 * 60 * 1000} // 10分钟内不重复提示
/>

参数说明

参数	类型	必填	默认值	说明
currentBuildTime	string \| number	✅	-	当前应用的构建时间戳
checkInterval	number	❌	60000	检查间隔（毫秒）
notificationCooldown	number	❌	300000	通知冷却时间（毫秒）

工作原理

1. 版本信息获取：通过 fetch('/version.json') 获取远程版本信息
2. 版本比较：比较远程 buildTimestamp 与本地 REACT_APP_BUILD_TIME
3. 更新提示：当远程时间戳大于本地时间戳时，显示更新通知
4. 用户操作：用户可选择立即更新或稍后提醒

版本信息格式

组件期望的 version.json 文件格式：

{
  "productId": "go-pmp",
  "version": "1.0.0 build:ABC123（UTC+8 北京时间: 2024-01-15 14:30:25）",
  "buildTime": "2024-01-15 14:30:25",
  "buildTimestamp": 1705302625,
  "environment": "prod"
}

通知样式

更新通知使用 Ant Design 的 notification 组件，包含：

• 标题：发现新版本
• 描述：检测到新版本 v{version}，建议刷新页面获取最新功能
• 操作按钮：
  • 立即更新：刷新页面
  • 稍后提醒：关闭通知

环境变量要求

确保在构建时设置了 REACT_APP_BUILD_TIME 环境变量：

# 构建时设置
REACT_APP_BUILD_TIME=1705302625 npm run build

注意事项

1. 网络环境：需要能够访问 /version.json 文件
2. 缓存控制：请求时添加时间戳参数避免缓存
3. 错误处理：网络错误不会影响应用正常运行
4. 性能考虑：检查频率不宜过高，建议 1 分钟以上
5. 用户体验：通知冷却时间建议设置合理，避免频繁打扰

调试

在浏览器控制台中可以看到详细的日志信息：

版本检查已启动，检查间隔: 60秒
获取到版本信息: {productId: "go-pmp", version: "1.0.0", ...}
版本检查 - 远程构建时间: 1705302625
版本检查 - 本地构建时间: 1705300000
检测到新版本可用

故障排除

1. 版本检测不工作

• 检查 REACT_APP_BUILD_TIME 环境变量是否正确设置
• 检查 /version.json 文件是否可以正常访问
• 查看浏览器控制台是否有错误信息

2. 频繁提示更新

• 调整 notificationCooldown 参数
• 检查版本信息中的 buildTimestamp 是否正确

3. 检测不到新版本

• 确认远程 version.json 文件已更新
• 检查 buildTimestamp 字段是否存在且为数字类型