@cdf-rd-fe/publish-notification-plugin

业务背景：用户长时间停留在旧页面、后台发版后仍继续操作，导致功能异常或数据不一致。

业务能力： 1、运行时对比「当前页版本」与「线上最新版本」。用户无需改业务逻辑，接入后即可感知发版。

​ 2、仅在窗口在前台、Tab 可见、且（微前端下）当前激活应用时检查。后台 Tab、未打开的子应用不打扰用户。

​ 3、静态脚本/样式加载失败时也会触发检查，便于发现「发版后旧 chunk 已失效」这类情况。

Web 版本更新提醒工具包：Runtime API + 薄构建辅助（只生成 version.json，不注入 HTML / 脚本）。本版以 Vite 为主。

安装

pnpm add @cdf-rd-fe/publish-notification-plugin

单体应用（Vite 双零配置）

// vite.config.ts
import { defineConfig } from 'vite'
import { vitePluginVersion } from '@cdf-rd-fe/publish-notification-plugin/vite'

export default defineConfig({
  plugins: [vitePluginVersion()],
})

// main.ts
import { createUpdateNotice } from '@cdf-rd-fe/publish-notification-plugin'

createUpdateNotice()

微前端（qiankun）

每个子应用各自接入 vitePluginVersion() + createUpdateNotice；Host 同步 setActiveApp。

// vite.config.ts
import { defineConfig } from 'vite'
import { vitePluginVersion } from '@cdf-rd-fe/publish-notification-plugin/vite'

export default defineConfig({
  plugins: [vitePluginVersion()],
})

// 主应用： host/main.ts
import { createUpdateNotice, getUpdateNotice } from '@cdf-rd-fe/publish-notification-plugin'

createUpdateNotice({
  microApp: { enabled: true, appId: 'host' },
  // 主应用纯壳(可选)：disableNotification: true,
})

registerMicroApps(apps, {
  beforeMount: [
    (app) => {
      // 激活子应用(插件只检查激活子应用是否有版本，不检查其他子应用)
      getUpdateNotice()?.setActiveApp(app.name)
      return Promise.resolve()
    },
  ],
})

// 子应用：order/main.ts
createUpdateNotice({
  microApp: { enabled: true, appId: 'order-center' },
})

事后切换语言 / 主题

import { getUpdateNotice } from '@cdf-rd-fe/publish-notification-plugin'

// 切换语言
getUpdateNotice()?.setLocale('en_US')
// 切换主题 （Antd 4.x + 5.x +6.x 主题会自动适配，不需要额外配置，可以不用写下面这行）
getUpdateNotice()?.setTheme('dark')

UpdateNoticeOptions

createUpdateNotice(options?) 的运行时配置。

| 字段 | 类型 | 默认 | 说明 | | --------------------- | ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | versionBase | string | 自动推导 | version.json URL 前缀，最终请求 {versionBase}update-notice/version.json。优先级：显式 versionBase → Vite import.meta.env.BASE_URL → ''。非根路径 / CDN 部署时建议显式配置 | | check | CheckConfig | 见下表 | 版本检查触发策略 | | microApp | MicroAppConfig | — | 微前端场景配置 | | themeAdapter | ThemeAdapterConfig | { type: 'antd' } | 默认 UI 主题适配 | | placement | ```typescript 'topLeft' | 'topRight' | 'bottomLeft' | | forcedUpdate | boolean | false | true 时强制更新：无「稍后」按钮，有遮罩不可操作 | | locale | LocaleConfig | — | 按语言覆盖内置通知文案；整站当前语言由 setLocale 控制，内置默认 zh_CN en_US | | disableNotification | boolean | false | true 时完全关闭该应用的检查 / 默认 UI / 消息通知web_update_notice，纯壳 Host 常用。与 hiddenDefaultNotice 互斥，不得同时为 true | | hiddenDefaultNotice | boolean | false | true 时关闭默认 UI，仍检查并派发 web_update_notice，供业务自定义 UI。与 disableNotification 互斥，不得同时为 true |

通知模式三选一：默认 UI（两者均不开启）/ 仅 disableNotification / 仅 hiddenDefaultNotice。

check

| 字段 | 类型 | 默认 | 说明 | | ----------------- | --------- | ---------------- | ------------------------------ | | interval | number | 10 * 60 * 1000 | 轮询间隔（毫秒）；<= 0 不轮询 | | onWindowActive | boolean | true | 窗口重新获得焦点时检查 | | onTabVisible | boolean | true | 标签页从隐藏变为可见时检查 | | onResourceError | boolean | true | 静态资源加载失败时检查（用于发现发版后旧 chunk 失效） |

microApp

| 字段 | 类型 | 默认 | 说明 | | --------- | --------- | --- | ------------------------------------------- | | enabled | boolean | — | 是否启用微前端口径；为 true 时需配合 Host setActiveApp | | appId | string | — | 当前应用 ID；仅当该 ID 为 active app 时才会检查 / 通知 |

themeAdapter

| 字段 | 类型 | 默认 | 说明 | | -------------- | ------- | -------------------------------- | -------- | | type | 'antd' | 'cssVariable' | 'antd' | | primaryColor | string | { light: string; dark: string } | — |

locale

按语言覆盖文案，键为 'zh_CN' | 'en_US'，值为部分字段：

| 字段 | 说明 | | ------------------- | ---------- | | title | 通知标题 | | description | 可选更新时的说明文案 | | buttonText | 「立即刷新」按钮文案 | | dismissButtonText | 「稍后」按钮文案 | | forcedDescription | 强制更新正文 |

createUpdateNotice({
  // 非根目录部署或者部署在cdn服务上
  versionBase: '/admin/',
  // 自定义版本检查时间，5min中检查一次版本
  check: { interval: 5 * 60 * 1000 },
  // 弹窗位置 
  placement: 'bottomRight',
  // 是否强制更新
  forcedUpdate: false,
  // 自定义主题色
  themeAdapter: {
    type: "cssVariable",
    // 不写 primaryColor：通知主色走默认 CSS / 业务侧 --update-* 覆盖
    // primaryColor: '#dddccc',
    primaryColor: {
      light: "#dddccc",
      dark: "#eeeeff",
    },
  },
  //自定义文案
  locale: {
    zh_CN: { 
        title: '发现新版本',
        description:'检测到新版本啦', 
        buttonText: '立即刷新', 
        dismissButtonText:'忽略',
        forcedDescription:'检测到新版本啦，请刷新页面'
    },
    en_US: { 
        title: 'Update available', 
        description:'A new version has been detected', 
        buttonText: 'Refresh' 
        dismissButtonText: 'Later', 
        forcedDescription:'A new version has been detected; please refresh the page.' 
},
  },
})

VersionPluginOptions

构建侧配置，传给 vitePluginVersion(options?) / defaultPluginVersion(options?)。只生成 {outDir}/update-notice/version.json，不注入 HTML / 脚本。Runtime 不配置这些字段。

| 字段 | 类型 | 默认 | 说明 | | ------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | versionType | 'timestamp' | 'gitcommit' | 'version' | | outDir | string | 见下 | 产物根目录，最终写出 {outDir}/update-notice/version.json。vitePluginVersion 未配置时读 Vite build.outDir；defaultPluginVersion 未配置时为 'dist' |

versionType

| 值 | 说明 | | ----------- | ------------------------------------------------------------- | | timestamp | 构建时间戳（Date.now()），默认推荐 | | gitcommit | 短 Git Commit（git rev-parse --short HEAD）；获取失败时降级为 timestamp | | version | 当前 package.json 的 version；获取失败时降级为 timestamp |

// vite.config.ts
vitePluginVersion({
  versionType: 'gitcommit',
  // outDir 一般可省略，自动用 Vite build.outDir
})

// 其他构建工具
await defaultPluginVersion({
  versionType: 'version',
  outDir: 'build',
})

本地示例

pnpm install
pnpm build
pnpm dev:vite   # Host http://localhost:7100 · 单体 http://localhost:7103

更多示例见 docs/examples.md。