Gathering detailed insights and metrics for unplugin-injector-version-html
Gathering detailed insights and metrics for unplugin-injector-version-html
Installations
npm install unplugin-injector-version-htmlDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS, ESM
Node Version
20.10.0
NPM Version
10.2.3
Releases
Unable to fetch releases
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
Maintainers
1
Package Meta Information
Latest Version
1.0.18
Package Id
unplugin-injector-version-html@1.0.18
Unpacked Size
254.54 kB
Size
41.81 kB
File Count
15
NPM Version
10.2.3
Node Version
20.10.0
Published on
May 13, 2025
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dev Dependencies
5
unplugin-injector-version-html
unplugin-injector-version-html 是一个用于 Webpack 和 Vite 的插件，可以在构建过程中将版本号动态注入到 HTML 文件的 <head> 部分。
功能特性
- 支持 Webpack 和 Vite：兼容主流构建工具。
- 动态注入版本号：在构建时将版本号插入到 HTML 文件中。
- 易于配置：支持自定义版本号和其他选项。
- 类型安全：使用 TypeScript 开发，提供完整的类型声明。
- 版本检测：提供前端版本检测功能，可配置轮询。
安装
通过 npm 安装：
1npm install unplugin-injector-version-html --save-dev
或者使用 pnpm：
1pnpm add unplugin-injector-version-html --save-dev
使用方法
在 Webpack 中使用
-
配置 Webpack 插件：
在你的
webpack.config.js中引入并使用插件：1const InjectorVersionPlugin = require("unplugin-injector-version-html/webpack"); 2 3module.exports = { 4 plugins: [ 5 new InjectorVersionPlugin({ 6 injectorFilename: "index.html", // 要注入的 HTML 文件名 7 version: "1.0.0", // 自定义版本号，不提供则从 package.json 获取 8 injectVersionJson: true, // 是否在输出目录生成 version.json 文件 9 environment: "production", // 插件生效的环境，可选 'development', 'production', 'all' 10 }), 11 ], 12}; -
运行构建：
1npm run build构建完成后，
index.html文件的<head>部分会包含类似以下内容：1<meta name="version" content="1.0.0.1673246598765" />如果
injectVersionJson设置为true(默认)，则在构建输出的根目录会生成一个version.json文件：1{ "version": "1.0.0.1673246598765" }
在 Vite 中使用
-
配置 Vite 插件：
在你的
vite.config.js或vite.config.ts中引入并使用插件：1// vite.config.ts 2import { defineConfig } from "vite"; 3import InjectorVersionPlugin from "unplugin-injector-version-html/vite"; 4 5export default defineConfig({ 6 plugins: [ 7 InjectorVersionPlugin({ 8 // injectorFilename: "index.html", // 在 Vite 中，这通常是默认的 HTML 文件 9 version: "1.0.0", // 自定义版本号，不提供则从 package.json 获取 10 injectVersionJson: true, // 是否在输出目录生成 version.json 文件 11 environment: "production", // 插件生效的环境，可选 'development', 'production', 'all' 12 }), 13 ], 14}); -
运行构建：
1npm run build 2# 或者 3# vite build构建完成后，你的主 HTML 文件（通常是
index.html）的<head>部分会包含注入的版本号元标签。如果
injectVersionJson设置为true(默认)，则在构建输出的根目录 (通常是dist) 会生成一个version.json文件。
Webpack 插件配置选项
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
injectorFilename | string | index.html | 要注入版本号的 HTML 文件名 |
version | string | 从 package.json 获取 | 要注入的版本号。如果未提供，则尝试从项目的 package.json 中读取。 |
injectVersionJson | boolean | true | 是否在构建输出的根目录生成 version.json 文件。 |
environment | 'development' | 'production' | 'all' | production | 插件运行的环境。只有当 process.env.NODE_ENV 与此匹配时插件才会执行（all 表示始终执行）。 |
Vite 插件配置选项
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
injectorFilename | string | index.html | 目标 HTML 文件名。在 Vite 中，transformIndexHtml 钩子通常作用于项目的主 HTML 文件。 |
version | string | 从 package.json 获取 | 要注入的版本号。如果未提供，则尝试从项目的 package.json 中读取。 |
injectVersionJson | boolean | true | 是否在构建输出的根目录生成 version.json 文件。 |
environment | 'development' | 'production' | 'all' | production | 插件运行的环境。只有当 Vite 的模式 (mode) 或 process.env.NODE_ENV 与此匹配时插件才会执行（all 表示始终执行）。 |
版本检测功能
除了注入版本号，本插件还提供了一个在前端检测应用是否有新版本的功能。通过 checkAppVersion 函数实现。
使用方法
1import { checkAppVersion } from "unplugin-injector-version-html"; 2 3// 基本用法 4checkAppVersion({ 5 apiUrl: "https://your-api.com/version", // 您的版本检查接口 6 onResult: (result) => { 7 if (result.hasNewVersion) { 8 console.log( 9 `发现新版本: ${result.latestVersion}，当前版本: ${result.currentVersion}` 10 ); 11 // 根据 result.updateUrl 进行提示或操作 12 if (result.updateUrl) { 13 // 例如：显示一个更新按钮，点击跳转到 result.updateUrl 14 } 15 } 16 }, 17 onError: (err) => { 18 console.error("检查更新失败:", err); 19 }, 20}) 21 .then((result) => { 22 // .then 仅在非轮询模式下有意义 23 if (result && result.hasNewVersion) { 24 console.log("非轮询模式：发现新版本"); 25 } 26 }) 27 .catch((err) => { 28 // .catch 仅在非轮询模式下有意义 29 console.error("非轮询模式：检查更新失败", err); 30 }); 31 32// 高级用法：启用轮询 33const versionCheckerControls = checkAppVersion({ 34 apiUrl: "https://your-api.com/version", 35 currentVersion: "1.0.0", // 可选，默认从 meta[name="version"] 标签获取 36 polling: true, // 启用轮询 37 pollingInterval: 300000, // 轮询间隔，单位毫秒 (例如：5分钟) 38 environment: "production", // 只在生产环境进行版本检查 39 debug: true, // 开启调试日志 40 onResult: (result) => { 41 if (result.hasNewVersion) { 42 alert( 43 `有新版本可用: ${result.latestVersion}。请刷新页面或访问更新链接。` 44 ); 45 // 如果API返回了更新链接 46 if (result.updateUrl) { 47 // 可以提供更新链接，例如： 48 // showUpdateButton(result.updateUrl); 49 } 50 // 如果启用了轮询，并且发现了新版本，轮询会自动停止（除非在开发环境禁用了更新提示） 51 } else { 52 console.log("当前已是最新版本。"); 53 } 54 }, 55 onError: (error) => { 56 console.warn("版本检查失败:", error.message); 57 }, 58 // 自定义版本比较逻辑 (可选) 59 compareVersions: (current, latest) => { 60 // 示例：简单比较，实际项目中可能需要更复杂的比较逻辑 61 return latest !== current; 62 }, 63}); 64 65// 如果启用了轮询，可以控制检查器 66if ( 67 versionCheckerControls && 68 typeof versionCheckerControls !== "function" && 69 "start" in versionCheckerControls 70) { 71 versionCheckerControls.start(); // 调用 start() 来启动轮询 72 // versionCheckerControls.stop(); // 你也可以在需要时调用 stop() 来停止轮询 73 // versionCheckerControls.checkNow(); // 或者调用 checkNow() 手动触发一次检查 74 console.log("轮询状态:", versionCheckerControls.isPolling); 75}
版本检测配置选项 (CheckVersionOptions)
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
apiUrl | string | 必填 | 远程版本接口 URL，应返回包含 version (string) 和可选 updateUrl (string) 的 JSON 对象。 |
currentVersion | string | 从 <meta name="version"> 获取，否则 "0.0.0" | 当前应用的版本号。 |
compareVersions | (current: string, latest: string) => boolean | 内置比较函数 | 自定义版本比较逻辑。返回 true 表示有新版本。 |
onResult | (result: VersionCheckResult) => void | undefined | 检测到结果（无论是否有新版本）时的回调函数。 |
onError | (error: Error) => void | undefined | 检测过程中发生错误时的回调函数。 |
polling | boolean | false | 是否启用轮询检查。 |
pollingInterval | number | 开发环境: 60000 (1 分钟), 生产环境: 300000 (5 分钟) | 轮询间隔时间（毫秒）。 |
maxRetries | number | 0 (无限制) | 轮询检查失败时的最大重试次数。 |
environment | 'development' | 'production' | 根据 process.env.NODE_ENV 判断 | 版本检查运行的环境。 |
debug | boolean | 开发环境: true, 生产环境: false | 是否在控制台输出调试日志。 |
disableDevUpdates | boolean | false | 是否在开发环境中禁用新版本提示（即使检测到新版本，hasNewVersion 也会被置为 false）。 |
项目结构
unplugin-injector-version-html
├── src
│ ├── index.ts # 版本检测功能入口
│ ├── webpack.ts # Webpack 插件实现
│ ├── vite.ts # Vite 插件实现
│ ├── types.ts # Webpack 和 Vite 插件共享的类型定义
│ ├── core/
│ │ ├── createInjectorVersion.ts # 注入版本号的核心逻辑
│ │ ├── versionChecker.ts # 版本检测功能实现和类型定义
│ │ └── index.ts # core 模块入口
│ └── shared/
│ ├── getPackageVersion.ts # 获取 package.json 版本工具
│ ├── utils.ts # 共享工具函数
│ └── index.ts # shared 模块入口
├── dist # 打包输出目录
├── tsup.config.ts # tsup 打包配置
├── package.json # 项目配置文件
└── README.md # 项目文档 (中文)
└── README-en.md # 项目文档 (英文)
开发与构建
-
克隆项目：
1git clone <repository-url> 2cd unplugin-injector-version-html -
安装依赖：
1pnpm install -
运行打包：
1npm run build -
发布到 npm：
1npm publish --access public
许可证
本项目基于 MIT 许可证开源。
No vulnerabilities found.
No security vulnerabilities found.