README.zh-CN.md

Open Editor

English | 简体中文

🔍 项目简介

OpenEditor 是一款专为现代 Web 开发打造的前端调试工具。通过深度集成构建工具链，该工具实现了「浏览器元素 ↔ 源代码」的双向精准映射，不仅支持开发者直接在 React/Vue 组件树中定位源码位置，还能自动唤醒本地 IDE 打开对应文件。这一创新方案可帮助开发者节省超过 90% 的源码定位时间，显著提升调试效率。

▶▶▶ 立即体验 (Vite+React 示例)

🚀 核心功能

框架支持

• React 生态：深度适配 Create React App/Next.js 等现代脚手架
• Vue 生态：完整支持 Vue CLI/Nuxt.js/Vite 等开发方案
• 构建工具：全面兼容 Webpack 4+/Vite 2+/Rollup 2+ 体系

集成能力

• 🚫 零侵入设计（无需项目端导入 SDK 或配置）

调试能力

• 🕵️ 多层级组件树追溯（支持跨 iframe 通信场景）
• ⌨️ 快捷键驱动工作流（⌥⌘O 启动调试器，ESC 退出检查模式）
• 📱 移动端远程调试支持（需与桌面端同局域网）
• 🔍 智能编辑器探测（自动识别 VS Code/WebStorm 等本地 IDE）

环境支持

• 专属模式：开发环境独占功能（生产环境自动禁用）
• 运行时要求：
  • Node.js 14+ 运行环境（推荐 LTS 版本）
  • 现代浏览器要求（需满足以下任意最新稳定版）：
    • Google Chrome ≥ 89（2021/03 发布）
    • Mozilla Firefox ≥ 85（2021/01 发布）
    • Microsoft Edge ≥ 90（2021/04 发布）
    • Apple Safari ≥ 14（2020/09 发布）

🛠️ 快速入门

前置条件

React 项目

# 验证 Babel 插件配置
npm list @babel/plugin-transform-react-jsx-source

若使用自定义 Babel 配置，请确保启用该插件

Vue 项目

# 安装必要依赖
npm install unplugin-vue-source -D

缺少该插件将导致行列定位失效

集成示例

本示例采用 Vite+React 框架进行演示，其他技术栈仅需调整对应配置项即可，核心使用逻辑保持完全一致。

工具集成

1.安装插件

npm i @open-editor/vite -D

2.添加配置

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import OpenEditor from '@open-editor/vite';

export default defineConfig({
  plugins: [
    react(),
    OpenEditor({
      // options
    }),
  ],
});

3.启动开发环境

npm run dev

调试流程

1. 激活检查器

• 快捷键操作：
  • macOS: Option + Command + O
  • Windows: Alt + Ctrl + O
• 鼠标操作：
  • 点击浏览器工具栏的切换按钮

切换按钮示意图

2. 元素审查

• 悬停预览：
  • 鼠标悬停组件显示源码定位（支持文件行列号）
• 精准定位：
  • 单击元素直接跳转编辑器（自动定位行列）
  • 深度审查模式：
    • macOS: 按 Command + 点击元素展开组件树
    • Windows: 按 Ctrl + 点击元素展开组件树
    • 长按元素300毫秒展开组件树

悬停预览示意图

组件树预览示意图

3. 退出检查器

• 快捷键操作：
  • 通用: Esc
  • macOS: 再次按 Option + Command + O
  • Windows: 再次按 Alt + Ctrl + O
• 鼠标操作：
  • 点击切换按钮关闭审查模式
  • 右键点击页面空白区域

⚙️ 高级功能

全局事件

// 自定义激活检查器逻辑
window.addEventListener('enableinspector', (e) => {
  e.preventDefault(); // 阻断默认行为
});

// 自定义退出检查器逻辑
window.addEventListener('exitinspector', (e) => {
  e.preventDefault(); // 阻断默认行为
});

// 自定义编辑器启动逻辑
window.addEventListener('openeditor', (e) => {
  const url = e.detail;
  url.hostname = 'localhost'; // 修正域名
  fetch(url);
  e.preventDefault(); // 阻断默认行为
});

🖼 生态系统

官方插件集

说明文档	NPM 版本	下载量
@open-editor/rollup
@open-editor/vite
@open-editor/webpack

在线演练场

源代码	在线试玩
rollup/react15
rollup/vue2
vite/react
vite/vue
vite/nuxt
webpack/react
webpack/nextjs
webpack/vue

特别致谢

本项目的实现深受以下优秀开源项目的启发和帮助：

• react-dev-inspector - React 组件调试利器
• vite-plugin-vue-inspector - Vue 组件调试解决方案
• launch-editor - 编辑器快速定位核心实现