code-inspector 源码浅析

前言

code-inspector 是一个源代码定位插件，它可以通过点击页面上的 DOM 元素，自动启动 IDE 并将光标定位到对应 DOM 元素的源代码位置。

去年，一位同事曾向我推荐过这个插件，不过当时我已经非常熟悉项目目录结构了，所以没有觉得特别需要它。最近，社区的朋友又提起了code-inspector，正好我对其背后的实现机制感到好奇，遂深入研究了一番它的源码设计。

源码浅析

code-inspector 插件的实现过程中涉及到了大量的兼容适配，涵盖了跨平台、跨框架、跨编辑器等诸多方面。如果要一一细致分析，既不切实际也浪费时间，因此本文仅重点分析其核心机制。

实现原理

严格来讲 code-inspector 的实现原理和思路并不复杂，难点在于他考虑到了各种环境的兼容性。

我们本篇采用 vue + vite 环境进行讲解。

整体流程如下：

• 首先 code-inspector 作为一个 vite / webpack 插件，在打包器收集依赖代码后，会将代码传递给插件，此时 code-inspector 可以拿到源码和文件路径。
• 获得源码之后，插件使用 AST 解析库处理这些源码，将 DOM 元素的相关信息（如：文件路径、行号、列号）注入到每个 DOM 元素中。
• 向客户端注入带有监听事件的 web component，用户通过触发这些事件来发起源码定位请求。
• 利用 Node.js 启动一个 HTTP 服务，接收从浏览器端发送的请求。
• 服务端收到请求后，通过 child_process.spawn 启动和控制 IDE，打开相应文件并定位到指定代码行。

目录设计

整个项目采用 monorepo 架构，源码都放在 packages 目录下

• code-inspector-plugin 主要承担插件统一入口的作用，同时判断了是否是开发环境。
• vite-plugin 与 webpack-plugin 主要实现了不同打包器的插件开发和适配。
• core 是整个插件的核心逻辑，包含客户端逻辑和服务端逻辑。

.
├── LICENSE
├── README.md
├── assets ------------------------------- logo 文件
├── demos -------------------------------- 各个框架的 demo
├── docs --------------------------------- 文档目录
├── package.json 
├── packages ----------------------------- 源码实现
│   ├── code-inspector-plugin ------------ 插件入口
│   ├── core ----------------------------- 核心包： 服务端与客户端逻辑
│   ├── vite-plugin ---------------------- vite 插件
│   └── webpack-plugin ------------------- webpack 插件
└── pnpm-workspace.yaml

源码逻辑梳理

code-inspector-plugin 逻辑比较简单，只是判断了一下是否是环境和根据用户传入 bundler 类型调用不同的插件包，这里不再展开讲了，直接进行 vite-plugin 包的讲解。

以下是精简之后的 vite 插件代代码：

export function ViteCodeInspectorPlugin(options?: Options) {  
  const record: RecordInfo = {  
    port: 0,  
    entry: '',  
    nextJsEntry: '',  
    ssrEntry: '',  
  };  
  return {  
    name: PluginName,  
	// ... 省略 apply 逻辑
    async resolveId(id) {  
      // 返回客户端注入的虚拟模块 id
      if (id === ViteVirtualModule_Client) {  
        return `\0${ViteVirtualModule_Client}`;  
      }  
      return null;  
    },  
    load(id) {
	  // 注入虚拟模块中的客户端代码
      if (id === `\0${ViteVirtualModule_Client}`) {  
        return getClientInjectCode(record.port, options);  
      }  
      return null;  
    },  
    async transform(code, id) {  
      if (id.match('node_modules')) {  
        return code;  
      }  
  
      // start server and inject client code to entry file  
      code = await getCodeWithWebComponent(options, id, code, record);  
  
      // ... 省略 jsx 与 svelte 等逻辑
  
      // vue  
      const isVue =  
        filePath.endsWith('.vue') &&  
        params.get('type') !== 'style' &&  
        params.get('raw') === null;  
      if (isVue) {  
        return transformCode({ content: code, filePath, fileType: 'vue' });  
      }  
    
      return code;  
    },  
  };  
}

虚拟模块

code-inspector 利用 vite 插件的虚拟模块添加了客户端的逻辑：load 函数 与 resolveId 部分

resolveId 钩子会在解析入口文件 和 遇到尚未加载解析的 id 时都会被调用，当遇到尚未加载的 id 时会调用 load 钩子。

load 钩子会返回一个虚拟模块代码，包含了整个客户端的逻辑。

transform 钩子每当解析到一个依赖文件时触发，同时中可以对源码进行修改，所以在这个阶段可以注入 import 虚拟模块的逻辑，当遇到没有加载模块时会触发 resolveId 钩子完成整个注入逻辑。

注入客户端代码

注入逻辑在 transform 中的 getCodeWithWebComponent 函数中。

export async function getCodeWithWebComponent(  
  options: CodeOptions,  
  file: string,  
  code: string,  
  record: RecordInfo  
) {  
  // start server  
  await startServer(options, record);  
  //....省略其他逻辑
  recordNormalEntry(record, file);  
  //....省略其他逻辑
  
  // 注入 web component 组件代码  
  if (  
    (isJsTypeFile(file) &&  
      [record.entry, record.nextJsEntry, record.ssrEntry].includes(  
        getFilenameWithoutExt(file)  
      )) ||  
    file === AstroToolbarFile  
  ) {  
    if (options.bundler === 'vite') {  
      code = `import '${ViteVirtualModule_Client}';\n${code}`;  
    } else {  
      const clientCode = getClientInjectCode(record.port, {  
        ...(options || {}),  
      });  
      code = `${code}\n${clientCode}`;  
    }  
  }  
  return code;  
}

这个方法同时调用了 startServer 启用了 code-inspector 的后端接口服务

recordNormalEntry 会判断是否是入口文件，判断逻辑也很简单，直接通过判断是否是 js 文件和 record.entry 是否为空，当满足条件时将 record.entry 设置为这个文件名。

同样，底下的注入 web component 逻辑也是一样，判断是否是入口文件，当是入口文件时在文件头部加入 import '${ViteVirtualModule_Client}';\n${code} 使 vite 会加载虚拟模块完成 web component 的注入。

注入元素属性

transformCode 方法根据不同的框架进行了调用，我们这里直接看 transformVue 方法。

通过 @vue/compiler-dom 的 parse 方法将 vue 源码解析成 ast , 同时使用 transform 方法遍历所有 html 元素（包括 vue 组件 tag）, 然后使用 MagicString 对源码进行修改：往元素上添加一个包含 文件路径、行号、列号等信息的属性。

import { parse, transform } from '@vue/compiler-dom';
//....省略其他导入

export function transformVue(content: string, filePath: string) {  
  const s = new MagicString(content);  
  
  const ast = parse(content, {  
    comments: true,  
  });  
  
  transform(ast, {  
    nodeTransforms: [  
      ((node: TemplateChildNode) => {  
        console.log(node)  
        if (  
          !node.loc.source.includes(PathName) &&  
          node.type === VueElementType &&  
          escapeTags.indexOf(node.tag.toLowerCase()) === -1  
        ) {  
          // 向 dom 上添加一个带有 filepath/row/column 的属性  
          const insertPosition = node.loc.start.offset + node.tag.length + 1;  
          const { line, column } = node.loc.start;  
          const addition = ` ${PathName}="${filePath}:${line}:${column}:${  
            node.tag  
          }"${node.props.length ? ' ' : ''}`;  
  
          s.prependLeft(insertPosition, addition);  
        }  
      }) as NodeTransform,  
    ],  
  });  
  
  return s.toString();  
}

启用服务

startServer 调用了 createServer 方法，同时判断了是否已经创建过了服务，避免重复创建。

export function createServer(callback: (port: number) => any, options?: CodeOptions) {  
  const server = http.createServer((req: any, res: any) => {  
    // 收到请求唤醒vscode  
    const params = new URLSearchParams(req.url.slice(1));  
    const file = decodeURIComponent(params.get('file') as string);  
    const line = Number(params.get('line'));  
    const column = Number(params.get('column'));  
    res.writeHead(200, {  
      'Access-Control-Allow-Origin': '*',  
      'Access-Control-Allow-Methods': '*',  
      'Access-Control-Allow-Headers': '*',  
      'Access-Control-Allow-Private-Network': 'true',  
    });  
    res.end('ok');  
    // 调用 hooks    
    options?.hooks?.afterInspectRequest?.(options, { file, line, column });  
    // 打开 IDE    
    launchEditor(file, line, column, options?.editor, options?.openIn, options?.pathFormat);  
      
  });

上面 createServer 逻辑比较简单，通过 http.createServer 创建了一个服务，同时监听当前端口请求，当遇到请求时调用 lunchEditor 打开编辑器。

打开编辑器

这里就不看源码了，打开编辑器主要使用 nodejs 的 child_process.spawn 调用编辑器，同时根据编辑器的要求传入参数。

以下是 macOS 下打开 webstrom 并定位到指定位置的示例代码：

import child_process from 'child_process';

const webstormPath = '/Applications/WebStorm.app/Contents/MacOS/webstorm'
const line = '3'
const column = '10'
const filePath = '/Users/ziyang/.npmrc'

child_process.spawn(webstormPath, ['--line', line, '--column', column, filePath]);

需要注意的是，不同的平台（win, mac）路径和调用方式是不一样的，其次不同的编辑器参数也不一样，所以 code-inspector 做了很多兼容工作。

客户端逻辑

客户端主要是通过 lit 库实现了一个 web component，代码量比较大，我们就不细看了，这里主要看一个请求逻辑。

// 请求本地服务端，打开vscode  
trackCode = () => {  
  if (this.locate) {  
    const file = encodeURIComponent(this.element.path);  
    const url = `http://localhost:${this.port}/?file=${file}&line=${this.element.line}&column=${this.element.column}`;  
    // 通过img方式发送请求，防止类似企业微信侧边栏等内置浏览器拦截逻辑  
    const img = document.createElement('img');  
    img.src = url;  
  }  
  if (this.copy) {  
    const path = formatOpenPath(  
      this.element.path,  
      String(this.element.line),  
      String(this.element.column),  
      this.copy  
    );  
    this.copyToClipboard(path[0]);  
  }  
};

这里没有使用 xhr 或者 fetch 的方式请求，而是直接通过 img.src 的方式进行请求。

结语

通过学习 code-inspector 的源码，收获还是很多的。在这个过程中，我还特意研究了 pnpm 的 monorepo 配置、vite 插件开发流程、magic-string 库的使用等多个方面的技术。

当我准备本文时，发现原作者已在掘金发布了一篇功能介绍和原理解析的文章，里面的内容更加细致，是非常好的学习参考资料，链接放在文末。

相关连接

• 原作者介绍+原理解析：juejin.cn/post/732600...
• code-inspector 官网： inspector.fe-dev.cn/