从“版本号打架”到 30 秒内提醒用户刷新：一个微前端团队的实践
鹏北海约 6 分钟（💰TRAE SOLO实战赛火热进行中，速戳上图了解详情🔍）
1. 背景与痛点
我们团队维护着一个微前端子应用集群，每个子应用都需要同时服务 dev / test / release / online 多套环境。分支策略（master / release / test / dev / hotfix / feature_x.x.x）加上 Jenkins 自动化，让“一天多次发布”成为常态。但真正影响交付效率的并不是发布次数，而是一个顽固的问题：「测试同学常年停留在旧版本页面」。
1.1 真实场景
测试在早上打开 dev 页面，下午我们发布了新的组件样式； 他们继续在旧页面里回归，反馈的问题我们一眼看出“这是老版本”； 群里喊“刷新一下”并不靠谱，于是“无效缺陷 + 反复沟通”成了常态。
更严重的一次事故，是我们在版本检查逻辑里同时使用了 webpack DefinePlugin 与自定义插件，各自调用了一次 getAppVersion()。结果前端控制台打印的是 0.8.3-release-202511210828，而 version.json 里是 0.8.3-release-202511210829。两边只差 1 秒钟，却让线上用户始终被提示刷新，形象地被团队称为“版本号打架”。
1.2 我们的诉求
用户在 30 秒内感知版本更新； 弹窗里能看到“当前版本 / 最新版本 / 环境”； 支持“立即刷新 / 稍后再说”，不给用户造成中断； 方案需兼容现有微前端架构与 CI/CD 流程，不依赖后端改造。
2. 方案探索与取舍
在动手前，我们列出几种可行方式：
综合团队资源与落地速度，我们选择了 「纯前端轮询 + 静态版本文件」 的做法，并明确两个原则：
「版本号唯一，可追溯」： 基础版本号-环境-时间戳；「发布零侵入」：Jenkins 仍旧运行 npm run build-xxx，无需新增步骤。
3. 技术方案总览
「构建阶段生成 version.json」：在 vue.config.js中提前计算版本号，既注入到前端（process.env.APP_VERSION），也写入输出目录的version.json；「前端轮询比对」：应用启动后每 30 秒请求一次 version.json，禁用缓存并携带时间戳，比较版本号；「交互提示」：复用 Ant Design Vue 的 Modal.confirm，展示当前/最新版本与环境；「缓存策略」：Nginx 对 HTML/ version.json禁止缓存，对 JS/CSS/图片继续长缓存；「CI/CD 配合」：所有环境沿用既有脚本，只是构建产物目录多了一份实时的 version.json。
4. 关键落地细节
4.1 版本号只生成一次（Build-time Deterministic Versioning）
vue.config.js 抽象 buildEnvName、buildVersion，并在 DefinePlugin 与生成 version.json 时复用：
const buildEnvName = getEnvName();const buildVersion = getAppVersion();module.exports = {configureWebpack: {plugins: [new webpack.DefinePlugin({"process.env.APP_VERSION": JSON.stringify(buildVersion),"process.env.APP_ENV": JSON.stringify(buildEnvName),}),],},chainWebpack(config) {config.plugin("generate-version-json").use({apply(compiler) {compiler.hooks.done.tap("GenerateVersionJsonPlugin", () => {fs.writeFileSync(path.resolve(__dirname, "edu/version.json"),JSON.stringify({version: buildVersion,env: buildEnvName,timestamp: new Date().toISOString(),publicPath: "/child/edu",},null,2));});},});},};
这样即使构建过程持续 5～10 分钟，注入的版本号和静态文件里的版本仍保持一致。这其实是把“构建产物视为不可变工件”的原则落地——保证任何使用该工件的入口看到的元数据都是同一个快照。
4.2 版本检查器（Runtime Polling & Cache Busting）
class VersionChecker {currentVersion = process.env.APP_VERSION;publicPath = "/child/edu";checkInterval = 30 * 1000;init() {console.log(`📌 当前前端版本：${this.currentVersion}（${process.env.APP_ENV}）`);this.startChecking();document.addEventListener("visibilitychange", () => {if (document.visibilityState === "visible" && !this.hasNotified) {this.checkForUpdate();}});}async checkForUpdate() {const url = `${this.publicPath}/version.json?t=${Date.now()}`;const response = await fetch(url, { cache: "no-store" });if (!response.ok) return;const latestInfo = await response.json();if (latestInfo.version !== this.currentVersion && !this.hasNotified) {this.hasNotified = true;this.stopChecking();this.showUpdateModal(latestInfo.version, latestInfo.env);}}}
这里有两个容易被忽略的细节：
fetch显式加cache: "no-store"，再叠加时间戳参数，防止 CDN / 浏览器任何一层干预；visibilitychange监听，保证窗口重新激活时立即比对，避免用户在后台等了很久才看到弹窗。
入口 main.ts 在应用 mount 之后调用 versionChecker.init()，即可把整个检测链路串起来。
4.3 Nginx 缓存策略（Precise Cache Partition）
location / {if ($request_filename ~* .html$) {add_header Cache-Control "no-store, no-cache, must-revalidate";}}location /child/edu {if ($request_filename ~* .html$) {add_header Cache-Control "no-store, no-cache, must-revalidate";}}location ~* /child/edu/version.json$ {add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate";add_header Pragma "no-cache";add_header Expires "0";add_header Surrogate-Control "no-store";}
这一层的思路是把资源分成两类：需要实时性（HTML、version.json）就 no-store，其余走长缓存。再配合 try_files 兜底 history 路由，微前端子应用的独立部署不会互相影响。
4.4 CI/CD 配置（Zero-touch Pipeline）
npm run build-develop | /child/edu | ||
npm run build-testing | /child/edu | ||
npm run build-release | /child/edu | ||
npm run build-production | /child/edu |
所有命令都带 cross-env NODE_OPTIONS=--openssl-legacy-provider，以兼容不同系统的 OpenSSL 版本。更重要的是，这套方案没有“要求运维多做一步”——构建产物天然携带 version.json，任何环境拿到包即可上线。
5. 测试与验证
我们定义了一个完整的回归流程，确保方案不会给测试和上线带来额外负担：
「首次访问」：打开 dev 环境页面，确认控制台打印版本号，Network 里能看到
version.json且响应头无缓存；「触发新版本」：调整任意文案，重新发布，保持旧页面不刷新；
「轮询验证」：30 秒内弹出提示框，展示当前/最新版本和环境；
「交互路径」：
点击“立即刷新”：页面强制 reload，新版本生效； 点击“稍后刷新”：记录取消动作并重新开启轮询；
「边界场景」：切 tab / 清缓存 / 新设备访问 / 短时间连续发布，均能正确感知最新版本。
6. 注意事项与常见问题
version.json | ||
cross-env | ||
vue.config.js 顶部缓存 buildVersion 并全局复用 |
7. 落地成效
旧页面用户在 30 秒内收到提醒，测试效率显著提升； “幽灵弹窗”彻底消失，版本对比逻辑稳定； 方案只触碰前端与 Nginx 配置，发布流程无需改造； 文档化后，其他子应用无需重复思考，直接复用。
8. 展望
下一步我们计划：
「封装通用 SDK」：抽象版本生成、轮询、弹窗逻辑，支持 Vue CLI / Vite； 「可视化版本面板」：在主应用汇总所有环境的版本和发布时间； 「差异化策略」：针对高优先级版本强制刷新，普通版本允许用户自行选择。
这次实践让我再次意识到：真正的坑往往藏在看似“微不足道”的细节里。当我们把问题和思考写成文档、沉淀成模板，团队就能以更小的代价获得更稳定的交付。如果你也在推进微前端版本同步，欢迎交流、互相借鉴。