winjs-plugin-wconsole

🚀 Web控制台调试插件 - 为 WinJS 应用提供强大的移动端调试和监控解决方案。

✨ 特性

📱 移动端友好 - 专为移动端调试设计，适配各种屏幕尺寸
🛠️ 多工具支持 - 集成 vConsole、PageSpy、Eruda 三大调试工具
🎯 按需启用 - 根据需求选择性启用调试工具
🔧 高度可配置 - 支持丰富的配置选项和自定义设置
🌐 CDN 支持 - 支持本地文件和 CDN 加载
⚡ 异步加载 - 不阻塞主线程，提升加载性能
🔄 环境隔离 - 仅在开发环境自动启用，生产环境自动关闭
🎨 界面美化 - 针对移动端优化的 UI 样式

🎯 应用场景

移动端H5调试 - 在移动设备上调试H5应用
远程调试 - 远程监控和调试移动端应用
性能监控 - 实时监控页面性能和网络请求
错误追踪 - 捕获和分析JavaScript错误
开发调试 - 开发过程中的实时调试和测试

📦 安装

# npm
npm install @winner-fed/plugin-wconsole -D

# yarn
yarn add @winner-fed/plugin-wconsole -D

# pnpm
pnpm add @winner-fed/plugin-wconsole -D

🚀 快速开始

1. 配置插件

在 .winrc.ts 中启用插件：

// .winrc.ts
import { defineConfig } from '@winner-fed/winjs';

export default defineConfig({
  plugins: ['@winner-fed/plugin-wconsole'],
  wconsole: {
    // 启用 vConsole
    vconsole: {},
  },
  appConfig: {
    development: {
      // 开启调试工具
      IS_OPEN_VCONSOLE: true,
    },
  },
});

2. 在移动端访问

在移动端浏览器中访问你的应用，会自动显示调试工具：

vConsole: 屏幕右下角的悬浮按钮
PageSpy: 页面监控工具
Eruda: 移动端开发者工具

🛠️ 支持的调试工具

vConsole

轻量级、可拓展的移动端调试工具，提供类似开发者工具的功能。

特点：

📝 日志面板 - 查看 console 输出
🌐 网络面板 - 监控 Ajax/Fetch 请求
📊 元素面板 - 查看 DOM 结构
💾 存储面板 - 查看 localStorage/sessionStorage
⚙️ 系统面板 - 查看设备信息

PageSpy

页面监控和远程调试工具，支持多端同步调试。

特点：

🔍 实时监控 - 实时查看页面状态
📱 多端同步 - 支持多设备同时调试
📊 性能分析 - 页面性能监控
🎯 错误追踪 - 自动捕获异常信息

Eruda

现代化的移动端开发者工具，功能强大且易于使用。

特点：

🎨 现代化界面 - 美观的用户界面
🔧 丰富功能 - 完整的调试功能集
📱 移动优化 - 专为移动端设计
🎯 高性能 - 轻量级且高效

⚙️ 配置选项

vConsole 配置

export default defineConfig({
  wconsole: {
    vconsole: {
      // 自定义 CDN 地址
      url: 'https://cdnjs.cloudflare.com/ajax/libs/vConsole/3.14.7/vconsole.min.js',
      // 默认激活的面板
      defaultPlugins: ['system', 'network', 'element', 'storage'],
      // 禁用日志滚动
      disableLogScrolling: false,
      // 主题设置
      theme: 'light',
      // 初始化回调
      onReady: function() {
        console.log('vConsole is ready!');
      }
    }
  }
});

PageSpy 配置

export default defineConfig({
  wconsole: {
    pagespy: {
      // 自定义服务器地址
      url: 'http://localhost:6752/page-spy/index.min.js',
      // PageSpy 配置选项
      options: {
        // 项目名称
        project: 'my-project',
        // 标题
        title: 'My Application',
        // 客户端信息
        clientOrigin: 'https://example.com'
      }
    }
  }
});

Eruda 配置

export default defineConfig({
  wconsole: {
    eruda: {
      // 自定义 CDN 地址
      url: 'https://cdnjs.cloudflare.com/ajax/libs/eruda/3.0.1/eruda.min.js',
      // 挂载容器
      container: document.body,
      // 启用的工具
      tool: ['console', 'elements', 'network', 'resources', 'info', 'snippets'],
      // 自动缩放
      autoScale: true,
      // 使用 Shadow DOM
      useShadowDom: true,
      // 默认配置
      defaults: {
        displaySize: 50,
        theme: 'Material Design'
      }
    }
  }
});

📝 使用示例

基础调试配置

// .winrc.ts
export default defineConfig({
  plugins: ['@winner-fed/plugin-wconsole'],
  wconsole: {
    // 启用 vConsole
    vconsole: {
      defaultPlugins: ['system', 'network', 'element'],
      theme: 'dark'
    }
  },
  appConfig: {
    development: {
      IS_OPEN_VCONSOLE: true,
    },
    production: {
      IS_OPEN_VCONSOLE: false, // 生产环境关闭
    }
  }
});

多工具混合使用

// .winrc.ts
export default defineConfig({
  plugins: ['@winner-fed/plugin-wconsole'],
  wconsole: {
    // 主要调试工具
    vconsole: {
      defaultPlugins: ['system', 'network'],
      theme: 'light'
    },
    // 性能监控
    pagespy: {
      options: {
        project: 'mobile-app',
        title: 'Mobile Application Debug'
      }
    }
  },
  appConfig: {
    development: {
      IS_OPEN_VCONSOLE: true,
    }
  }
});

使用本地文件

// .winrc.ts
export default defineConfig({
  plugins: ['@winner-fed/plugin-wconsole'],
  wconsole: {
    vconsole: {
      // 使用本地文件
      url: './vconsole.min.js'
    }
  },
  appConfig: {
    development: {
      IS_OPEN_VCONSOLE: true,
    }
  }
});

高级配置

// .winrc.ts
export default defineConfig({
  plugins: ['@winner-fed/plugin-wconsole'],
  wconsole: {
    vconsole: {
      url: 'https://cdnjs.cloudflare.com/ajax/libs/vConsole/3.14.7/vconsole.min.js',
      defaultPlugins: ['system', 'network', 'element', 'storage'],
      disableLogScrolling: false,
      theme: 'light',
      onReady: function() {
        console.log('vConsole 初始化完成');
        // 添加自定义面板
        const customPlugin = new VConsole.VConsolePlugin('custom', 'Custom');
        vConsole.addPlugin(customPlugin);
      }
    },
    eruda: {
      tool: ['console', 'elements', 'network'],
      autoScale: true,
      useShadowDom: true,
      defaults: {
        displaySize: 80,
        theme: 'Monokai Pro'
      }
    }
  },
  appConfig: {
    development: {
      IS_OPEN_VCONSOLE: true,
    }
  }
});

📱 移动端适配

安全区域适配

插件自动处理移动端安全区域，确保调试工具不被遮挡：

/* 自动添加的样式 */
.vc-switch {
  right: 0px;
  bottom: calc(env(safe-area-inset-bottom) + 1.2rem) !important;
}

响应式设计

小屏设备：自动调整工具栏大小
横屏模式：优化横屏显示效果
高DPI屏幕：支持高分辨率屏幕显示

🔧 API 参考

全局配置

interface WConsoleConfig {
  vconsole?: VConsoleConfig;
  pagespy?: PageSpyConfig;
  eruda?: ErudaConfig;
}

interface VConsoleConfig {
  url?: string;
  defaultPlugins?: string[];
  onReady?: () => void;
  disableLogScrolling?: boolean;
  theme?: 'light' | 'dark';
}

interface PageSpyConfig {
  url?: string;
  options?: {
    project?: string;
    title?: string;
    clientOrigin?: string;
    [key: string]: any;
  };
}

interface ErudaConfig {
  url?: string;
  container?: string;
  tool?: string[];
  autoScale?: boolean;
  useShadowDom?: boolean;
  defaults?: {
    displaySize?: number;
    theme?: string;
    [key: string]: any;
  };
}

运行时访问

// 在浏览器中访问调试工具实例
declare global {
  interface Window {
    vConsole?: any;
    $pageSpy?: any;
    eruda?: any;
  }
}

// 使用示例
if (window.vConsole) {
  console.log('vConsole 版本:', window.vConsole.version);
}

🎯 最佳实践

1. 环境配置

// 不同环境使用不同配置
export default defineConfig({
  wconsole: {
    vconsole: {
      url: process.env.NODE_ENV === 'development' 
        ? './vconsole.min.js'  // 开发环境使用本地文件
        : 'https://cdnjs.cloudflare.com/ajax/libs/vConsole/3.14.7/vconsole.min.js'
    }
  },
  appConfig: {
    development: {
      IS_OPEN_VCONSOLE: true,
    },
    testing: {
      IS_OPEN_VCONSOLE: true,
    },
    production: {
      IS_OPEN_VCONSOLE: false,
    }
  }
});

2. 性能优化

// 按需加载，避免影响生产环境
export default defineConfig({
  wconsole: {
    vconsole: {
      // 使用压缩版本
      url: 'https://cdnjs.cloudflare.com/ajax/libs/vConsole/3.14.7/vconsole.min.js',
      // 仅启用必要的面板
      defaultPlugins: ['system', 'network'],
      // 禁用日志滚动以提升性能
      disableLogScrolling: true
    }
  }
});

3. 团队协作

// 为团队成员提供统一的调试配置
export default defineConfig({
  wconsole: {
    vconsole: {
      onReady: function() {
        console.log('=== 调试工具已启动 ===');
        console.log('当前环境:', process.env.NODE_ENV);
        console.log('API地址:', window.LOCAL_CONFIG.API_HOME);
        console.log('版本信息:', window.vConsole.version);
      }
    },
    pagespy: {
      options: {
        project: '项目名称',
        title: '开发调试'
      }
    }
  }
});

🔍 常见问题

Q: 为什么调试工具没有显示？

A: 请检查以下几点：

确保在 appConfig 中设置了 IS_OPEN_VCONSOLE: true
确认当前环境是开发环境
检查网络是否能访问CDN地址
查看浏览器控制台是否有错误信息

Q: 如何在生产环境中临时启用调试工具？

A: 可以通过URL参数或localStorage控制：

// 在代码中动态控制
if (location.search.includes('debug=true') || localStorage.getItem('debug') === 'true') {
  window.LOCAL_CONFIG.IS_OPEN_VCONSOLE = true;
}

Q: 调试工具加载失败怎么办？

A: 建议使用本地文件作为备用方案：

export default defineConfig({
  wconsole: {
    vconsole: {
      // 主要地址
      url: 'https://cdnjs.cloudflare.com/ajax/libs/vConsole/3.14.7/vconsole.min.js',
      // 可以下载到public目录作为备用
      // url: './vconsole.min.js'
    }
  }
});

Q: 如何自定义调试工具的样式？

A: 可以通过CSS覆盖默认样式：

/* 自定义 vConsole 样式 */
.vc-switch {
  background-color: #007aff !important;
  border-radius: 50% !important;
}

.vc-panel {
  font-size: 12px !important;
}

Q: 多个调试工具是否会冲突？

A: 通常不会冲突，但建议根据实际需求选择合适的工具：

vConsole: 轻量级，适合日常调试
PageSpy: 适合远程监控
Eruda: 功能丰富，适合深度调试

📋 调试工具对比

特性	vConsole	PageSpy	Eruda
文件大小	小 (~200KB)	中 (~500KB)	大 (~1MB)
功能完整度	基础	高级	完整
远程调试	❌	✅	❌
性能监控	基础	高级	完整
自定义扩展	✅	✅	✅
移动端适配	✅	✅	✅
学习成本	低	中	高

🛠️ 开发调试

启用调试模式

// 在开发环境中启用详细日志
export default defineConfig({
  wconsole: {
    vconsole: {
      onReady: function() {
        // 启用详细日志
        window.vConsole.setOption('maxLogNumber', 5000);
        console.log('vConsole 调试模式已启用');
      }
    }
  }
});

自定义插件

// 创建自定义 vConsole 插件
export default defineConfig({
  wconsole: {
    vconsole: {
      onReady: function() {
        // 自定义插件
        const myPlugin = new VConsole.VConsolePlugin('my_plugin', 'My Plugin');
        
        myPlugin.on('init', function() {
          console.log('Custom plugin initialized');
        });
        
        myPlugin.on('renderTab', function(callback) {
          const html = '<div>Custom content</div>';
          callback(html);
        });
        
        window.vConsole.addPlugin(myPlugin);
      }
    }
  }
});

📄 许可证

MIT.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
.vscode		.vscode
playground		playground
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
renovate.json		renovate.json
rslib.config.ts		rslib.config.ts
tsconfig.json		tsconfig.json

License

winjs-dev/winjs-plugin-wconsole

Folders and files

Latest commit

History

Repository files navigation

winjs-plugin-wconsole

✨ 特性

🎯 应用场景

📦 安装

🚀 快速开始

1. 配置插件

2. 在移动端访问

🛠️ 支持的调试工具

vConsole

PageSpy

Eruda

⚙️ 配置选项

vConsole 配置

PageSpy 配置

Eruda 配置

📝 使用示例

基础调试配置

多工具混合使用

使用本地文件

高级配置

📱 移动端适配

安全区域适配

响应式设计

🔧 API 参考

全局配置

运行时访问

🎯 最佳实践

1. 环境配置

2. 性能优化

3. 团队协作

🔍 常见问题

Q: 为什么调试工具没有显示？

Q: 如何在生产环境中临时启用调试工具？

Q: 调试工具加载失败怎么办？

Q: 如何自定义调试工具的样式？

Q: 多个调试工具是否会冲突？

📋 调试工具对比

🛠️ 开发调试

启用调试模式

自定义插件

📄 许可证

🔗 相关链接

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages