inject-vc-vite-plugin
v1.2.2
Published
vconsole vite plugin
Readme
inject-vc-vite-plugin
一个用于 Vite 项目的调试辅助插件。
它会在指定环境下自动注入 vConsole，并在页面控制台输出当前构建的关键信息，方便移动端调试、测试环境排查和版本确认。
特性
- 在指定环境下注入
vConsole - 使用包内置的
vconsole.min.js，不依赖 CDN - 在浏览器控制台输出环境、版本号、构建时间
- 支持自动输出当前 Git commit short hash
- 配置简单，适合 H5、多环境部署和频繁发版场景
适用场景
- 需要在移动端快速打开调试面板
- 测试环境较多，想确认当前页面对应的构建版本
- 线上存在缓存，想快速判断页面是否已经更新
- 希望在不改业务代码的前提下补充统一调试信息
安装
npm install inject-vc-vite-plugin -D或：
yarn add inject-vc-vite-plugin -D或：
pnpm add inject-vc-vite-plugin -D快速开始
在 vite.config.ts 中注册插件：
import { defineConfig } from 'vite';
import injectVcVitePlugin from 'inject-vc-vite-plugin';
export default defineConfig({
plugins: [
injectVcVitePlugin({
injectEnv: ['development', 'staging'],
style:
'color: white; background: #1677ff; font-size: 12px; padding: 2px 4px; border-radius: 2px;'
})
]
});默认行为
如果不传配置，插件默认行为如下：
injectEnv：['development', 'beta']style：color: white; background: #f0a746; font-size: 12px; padding: 2px 3px; border-radius: 2px;
默认情况下，插件会：
- 在
development和beta环境下注入vConsole - 在页面加载后向控制台输出当前环境、版本号、构建时间
- 如果当前目录是一个 Git 仓库，则额外输出当前 commit short hash
配置项
injectEnv
类型：string[]
说明：指定哪些 Vite mode 需要注入 vConsole。
示例：
injectVcVitePlugin({
injectEnv: ['development', 'test', 'staging']
});style
类型：string
说明：自定义控制台日志的 CSS 样式字符串。
示例：
injectVcVitePlugin({
style: 'color: #fff; background: #222; padding: 2px 6px; border-radius: 3px;'
});控制台输出示例
插件会插入类似下面的日志：
console.log('%c 🚀 当前环境：staging ', '...');
console.log('%c 🚩 当前版本：1.1.15 ', '...');
console.log('%c ⏰ 更新时间：2026-07-23 17:00:00 ', '...');
console.log('%c 🔑 提交哈希：a1b2c3d ', '...');其中：
- 版本号来自当前执行 Vite 命令目录下的
package.json - 提交哈希优先读取
CI_COMMIT_SHORT_SHA - 如果没有
CI_COMMIT_SHORT_SHA，则回退到git rev-parse --short HEAD
输出效果
控制台中会看到类似以下信息：
实现说明
vConsole通过包内置脚本直接注入到 HTML 中- 插件通过
transformIndexHtml在构建时插入脚本 - 调试信息会被插入到
<body>之前
这意味着它更适合标准 Vite HTML 入口项目。
注意事项
- 插件依赖 Vite 的
mode判断当前环境 - 如果项目不是标准的 HTML 入口结构，需要自行确认
transformIndexHtml是否会生效 - 由于内置了
vconsole.min.js，最终插件产物体积会比纯逻辑插件更大 - 如果当前目录没有 Git 信息，插件会跳过 commit hash 输出
开发
npm run build清理产物：
npm run clean