@gangdai/vconsole-trigger

一个轻量级的 vConsole 触发器库，用于生产环境调试，支持多种激活方式。


特性

- 🚀 零依赖：仅 peer dependency 为 vconsole
- 📦 轻量级：打包后体积小，按需加载 vConsole
- 🎯 多种触发方式：URL参数、sessionStorage、手势、快捷键、API
- 🔧 高度可配置：支持自定义触发参数、热区、快捷键等
- 💪 TypeScript 支持：完整的类型定义
- 📱 移动端友好：支持触摸手势触发
- 🌐 通用格式：同时支持 CommonJS 和 ESM

安装

``bash


使用 pnpm

pnpm add @gangdai/vconsole-trigger vconsole

使用 npm

npm install @gangdai/vconsole-trigger vconsole

使用 yarn

yarn add @gangdai/vconsole-trigger vconsole
`

快速开始

$3

`typescript
import { initVConsoleTrigger } from '@gangdai/vconsole-trigger';

// 使用默认配置初始化
initVConsoleTrigger();
`

$3

`typescript
import { initVConsoleTrigger } from '@gangdai/vconsole-trigger';

initVConsoleTrigger({
queryKeys: ['debug', 'vconsole'],
storageKey: 'MY_APP_VCONSOLE',
theme: 'light',
globalApiName: 'MyDebugConsole',
enableShortcut: true,
enableGesture: true,
});
`

$3

`typescript
import { VConsoleTrigger } from '@gangdai/vconsole-trigger';

const trigger = new VConsoleTrigger({
theme: 'dark',
});

// 初始化
trigger.init();

// 手动打开
await trigger.open();

// 手动关闭
trigger.close();
`

触发方式

$3

在访问地址后追加 ?debug_vconsole 或 ?vconsole（值可为空、1、true、yes、on）：

`
https://example.com/?debug_vconsole
https://example.com/?vconsole=1
https://example.com/#vconsole=true
`

$3

一旦通过任意方式打开 vConsole，会向 sessionStorage 写入标记，刷新页面后仍会自动拉起。

$3

在触摸屏设备上，在 2 秒内于「屏幕左侧 35% × 底部 25%」区域连点 5 次即可触发。

$3

在可用键盘环境中按下 Ctrl/Cmd + Alt + V。

$3

通过全局 API 手动控制：

`typescript
// 打开 vConsole
await window.VConsoleDebug.open();

// 关闭 vConsole
window.VConsoleDebug.close();
`

配置选项

`typescript
interface VConsoleTriggerOptions {
/**
* URL查询参数键名列表
* @default ['debug_vconsole', 'vconsole']
*/
queryKeys?: string[];

/**
* sessionStorage存储键名
* @default 'VCONSOLE_ENABLED'
*/
storageKey?: string;

/**
* 多点触控时间窗口（毫秒）
* @default 2000
*/
tapWindowMs?: number;

/**
* 触发所需的点击次数
* @default 5
*/
tapTargetCount?: number;

/**
* 热区宽度比例（相对于屏幕宽度）
* @default 0.35
*/
hotzoneWidthRatio?: number;

/**
* 热区高度比例（相对于屏幕高度，从底部开始）
* @default 0.75
*/
hotzoneHeightRatio?: number;

/**
* vConsole主题
* @default 'dark'
*/
theme?: 'dark' | 'light';

/**
* 全局API对象名称
* @default 'VConsoleDebug'
*/
globalApiName?: string;

/**
* 是否启用键盘快捷键（Ctrl/Cmd + Alt + V）
* @default true
*/
enableShortcut?: boolean;

/**
* 是否启用触摸手势
* @default true
*/
enableGesture?: boolean;
}
`

API

$3

创建并初始化 vConsole 触发器的便捷函数。

$3

vConsole 触发器类。

#### 方法

- init(): void - 初始化触发器
- open(): Promise - 手动打开 vConsole
- close(): void - 手动关闭 vConsole

使用场景

$3

`typescript
// main.tsx 或 index.tsx
import { initVConsoleTrigger } from '@gangdai/vconsole-trigger';

// 在应用启动时初始化
initVConsoleTrigger();

ReactDOM.createRoot(document.getElementById('root')!).render();
`

$3

`typescript
// main.ts
import { initVConsoleTrigger } from '@gangdai/vconsole-trigger';

// 在应用启动时初始化
initVConsoleTrigger();

createApp(App).mount('#app');
`

$3

`html

`

关闭 & 清理

- 使用全局 API：window.VConsoleDebug.close()`
- 或从浏览器 DevTools > Application > Session Storage 中删除对应的存储键
- 或刷新后不再带调试参数

浏览器兼容性

- 现代浏览器（Chrome、Firefox、Safari、Edge）
- 移动端浏览器（iOS Safari、Chrome Mobile、Android WebView）
- 支持 ES2020+ 特性

许可证

MIT © Gang Dai

相关链接

- vConsole - 腾讯开源的移动端调试工具
- GitHub Repository
- Issues