umi-plugin-reload

在 Umi 构建产物中注入部署版本标识，并在浏览器中轮询比对线上页面；发现新版本时提示用户刷新。支持 Umi 2 / 3 / 4 与 monorepo（通过 packageJsonDir 指定 package.json 目录）。

安装

pnpm add umi-plugin-reload
# 或 npm / yarn

要求：peerDependencies 为 umi >= 2.13 < 5。

发布前请在插件仓库根目录执行 pnpm run build，确保存在 dist/index.js（npm 包若已包含 dist 则无需本地构建）。

Umi 4 / 3：配置方式

Umi 4 / 3 的 plugins 项只能是字符串路径，插件选项写在顶层 reload（与 api.describe({ key: 'reload' }) 一致）。

// .umirc.ts
import { defineConfig } from 'umi';

export default defineConfig({
  plugins: ['umi-plugin-reload'],
  reload: {
    mode: 'any',
    checkInterval: 60_000,
    checkUrl: '',
    version: process.env.DEPLOY_VERSION,
    usePackageVersion: false,
    packageJsonDir: '',
    enableInDev: false,
  },
});

本地调试插件源码时，可将 plugins 写成 require.resolve('path/to/dist/index.js')。

Umi 2：配置方式（重要）

Umi 2 会校验 .umirc.js 顶层 key，不能写未注册的 reload，否则会报错（例如："reload" 并非约定的配置项）。

请只通过 plugins 的元组第二项传入选项（会作为插件第二个参数 importOpts 合并进配置）：

// .umirc.js
const path = require('path');

const plugin = path.join(__dirname, 'node_modules', 'umi-plugin-reload', 'dist', 'index.js');
// 或使用 require.resolve('umi-plugin-reload/dist/index.js')，以实际包结构为准

const reload = {
  enableInDev: true,
  mode: 'major',
  version: '1.0.0',
  checkInterval: 60_000,
  checkUrl: '/version.json',
};

module.exports = {
  plugins: [[plugin, reload]],
};

配置项说明（reload / 元组第二项）

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | mode | 'any' \| 'major' | 'any' | any：远端版本字符串与当前页不一致即提示；major：仅主版本号变化时提示（如 1.x → 2.x），解析不到主版本时回退为整串比较。 | | checkInterval | number | 60000 | 轮询间隔（毫秒），最小 5000。 | | checkUrl | string | '' | 拉取「线上最新 HTML」的 URL，响应中需包含与构建时一致的 window.__DEPLOY_VERSION__ = "..."。为空则用当前页 URL（去掉 hash）。 | | version | string | — | 构建时写入页面的版本；优先级最高。 | | usePackageVersion | boolean | false | 在未配置 version 且无相关环境变量时，读取 packageJsonDir 下 package.json 的 version。 | | packageJsonDir | string | — | monorepo 时使用：含 version 的 package.json 所在目录；支持绝对路径，或相对 Umi 项目 cwd 的相对路径。 | | enableInDev | boolean | false | 为 true 时在 umi dev 也注入轮询；生产构建默认始终注入（由 NODE_ENV / api.env 判断）。 |

配置合并顺序（插件内部）

插件会把以下来源合并（后者覆盖前者）：

1. Umi 2：plugins: [[插件, opts]] 中的 opts
2. api.config.reload（部分场景）
3. api.userConfig.reload（Umi 3 / 4 的 .umirc 顶层 reload）

构建版本号如何生成（version 未手写时）

按顺序取第一个有效值：

1. 环境变量：DEPLOY_VERSION、APP_VERSION、VERCEL_GIT_COMMIT_SHA、CF_PAGES_COMMIT_SHA、CI_COMMIT_SHA、GITHUB_SHA、COMMIT_REF
2. usePackageVersion: true 时读取 packageJsonDir（默认项目 cwd）下的 package.json → version
3. 在 Umi 项目 cwd 执行 git rev-parse --short HEAD
4. 失败则回退为 Date.now()

建议在 CI 里设置 DEPLOY_VERSION 或 APP_VERSION（如语义化版本或构建号），与发版流程一致。

工作原理简述

1. 构建时在 HTML 中注入：window.__DEPLOY_VERSION__ = "<版本>"。
2. 页面内联脚本按 checkInterval 对 checkUrl（或当前页）发起 fetch（cache: 'no-store'，credentials: 'same-origin'），用正则从 HTML 中解析 __DEPLOY_VERSION__。
3. 与当前页上的版本比较；满足 mode 规则则展示提示，用户可刷新。

注意： 若入口 HTML 被 CDN / 浏览器强缓存，可能长期拿到旧版本字符串；建议对入口 HTML 使用较短缓存或单独提供轻量 checkUrl。

Node.js 与 Umi 2 / 3（Webpack 4）

Umi 2、3 依赖的 Webpack 4 在 Node 17+ 上可能触发 OpenSSL 报错，可在脚本中增加：

NODE_OPTIONS=--openssl-legacy-provider umi dev

本仓库内 examples/test-app-umi2、examples/test-app-umi3 的 package.json 已按此写法配置。

本仓库示例工程

| 目录 | Umi | 本地端口（示例内配置） | |------|-----|------------------------| | examples/test-app | 4.x | 8000 | | examples/test-app-umi3 | 3.x | 8001 | | examples/test-app-umi2 | 2.x | 8002 |

在仓库根目录：

pnpm install
pnpm example:dev        # Umi 4
pnpm example:umi3:dev   # Umi 3
pnpm example:umi2:dev   # Umi 2

各示例通过 public/version-mock.html 模拟线上更高版本，用于验证轮询与提示。

发布到 npm

1. 登录（仅首次或换机器）：npm login（或 npm adduser），按提示使用 npm 账号与一次性密码/2FA。

2. 包名：package.json 的 name 为 umi-plugin-reload。若已被占用，需改为作用域名如 @你的用户名/umi-plugin-reload，并在安装侧同步改包名。

3. 版本号：每次发布前递增 version（如 pnpm version patch / minor / major）。

4. 构建：prepublishOnly 已配置为 pnpm run build，执行 npm publish 或 pnpm publish 前会自动构建；本地也可先 pnpm run build 再检查 dist/（含 index.d.ts）。

5. 发布（公开包）：

   npm publish --access public

   作用域包且首次：npm publish --access public。

6. 预览包内容（不上传）：pnpm pack，或 npm publish --dry-run。

LICENSE

MIT