egg-tools

English | 中文

一个 Egg.js 插件，提供无缝编辑器集成的开发工具。支持从浏览器直接跳转到你喜欢的代码编辑器，并精确定位到指定行列。

为什么选择 egg-tools？

在开发 Egg.js 应用时，特别是使用 Vue DevTools 或调试前端组件时，你经常需要快速从浏览器跳转到编辑器中的源代码。这个插件解决了与 koa-webpack 的兼容性问题，并提供了强大的编辑器集成解决方案。

核心优势：

• 🚀 一键导航 从浏览器到源代码
• 🎯 精确定位 支持行号和列号定位
• 🔧 多编辑器支持 (VS Code, WebStorm, Sublime Text 等)
• 🛡️ 安全优先 路径验证和输入校验
• ⚡ 高性能 响应时间小于 100ms
• 🔌 易于集成 遵循 Egg.js 插件标准

系统要求

• Node.js >= 8.0.0
• Egg.js >= 2.0.0

安装

$ npm i egg-tools --save

使用方法

1. 启用插件

// config/plugin.js
exports.eggTools = {
  enable: !!process.env.local, // 仅在本地开发环境启用
  package: "egg-tools"
};

2. 配置插件（可选）

// config/config.default.js
exports.openEditor = {
  // 指定编辑器（可选，不指定则自动检测）
  specifiedEditor: "code", // VS Code

  // 源代码根目录（默认：process.cwd()）
  srcRoot: path.join(process.cwd(), "../client"),

  // 错误回调函数（可选）
  onErrorCallback: (fileName, errorMsg) => {
    console.error(`无法打开文件 ${fileName}: ${errorMsg}`);
  },

  // API 端点路径（默认：'/__open-in-editor'）
  match: "/__open-in-editor"
};

3. 从浏览器打开文件

插件启用后，你可以通过发送 HTTP 请求到端点来打开文件：

# 基本文件打开
GET /__open-in-editor?file=src/components/App.vue

# 打开文件到指定行
GET /__open-in-editor?file=src/utils/helper.js:42

# 打开文件到指定行和列
GET /__open-in-editor?file=src/main.js:13:24

# 支持 file:// URI
GET /__open-in-editor?file=file:///absolute/path/to/file.js:10:5

# 相对路径（相对于 srcRoot 解析）
GET /__open-in-editor?file=components/Header.vue:25

4. 与前端工具集成

Vue DevTools 集成

// 在你的 Vue 应用中
function openInEditor(file, line, column) {
  const url = `/__open-in-editor?file=${file}:${line}:${column}`;
  fetch(url).then(() => console.log("编辑器已打开"));
}

// 在 Vue 组件中使用
export default {
  methods: {
    handleError(error) {
      // 打开错误发生的文件
      openInEditor(error.fileName, error.lineNumber, error.columnNumber);
    }
  }
};

React 错误边界集成

class ErrorBoundary extends React.Component {
  handleOpenInEditor = (fileName, lineNumber) => {
    fetch(`/__open-in-editor?file=${fileName}:${lineNumber}`);
  };

  render() {
    if (this.state.hasError) {
      return (
        <div>
          <h2>出现了错误。</h2>
          <button
            onClick={() => this.handleOpenInEditor(this.state.errorFile, this.state.errorLine)}
          >
            在编辑器中打开
          </button>
        </div>
      );
    }
    return this.props.children;
  }
}

错误堆栈跟踪集成

// 全局错误处理器
window.addEventListener("error", event => {
  const { filename, lineno, colno } = event;
  if (filename && lineno) {
    // 自动打开错误文件
    fetch(`/__open-in-editor?file=${filename}:${lineno}:${colno}`);
  }
});

// Promise 错误处理
window.addEventListener("unhandledrejection", event => {
  const stack = event.reason.stack;
  if (stack) {
    // 解析堆栈信息并打开相关文件
    const match = stack.match(/at.*\((.+):(\d+):(\d+)\)/);
    if (match) {
      const [, file, line, column] = match;
      fetch(`/__open-in-editor?file=${file}:${line}:${column}`);
    }
  }
});

支持的编辑器

插件会自动检测正在运行的编辑器，或者你可以指定一个：

| 编辑器 | 标识符 | 平台支持 | | ---------------- | --------------- | --------------------- | | VS Code | code | Windows, macOS, Linux | | VS Code Insiders | code-insiders | Windows, macOS, Linux | | VSCodium | codium | Windows, macOS, Linux | | Cursor | cursor | Windows, macOS, Linux | | WebStorm | webstorm | Windows, macOS, Linux | | PhpStorm | phpstorm | Windows, macOS, Linux | | PyCharm | pycharm | Windows, macOS, Linux | | IntelliJ IDEA | idea | Windows, macOS, Linux | | Atom | atom | Windows, macOS, Linux | | Sublime Text | sublime | Windows, macOS, Linux | | Vim | vim | macOS, Linux | | Emacs | emacs | Linux |

环境变量

你可以使用环境变量控制编辑器选择：

# 强制使用特定编辑器
export LAUNCH_EDITOR=code

# 使用自定义启动脚本
export LAUNCH_EDITOR=/path/to/my-editor-launcher.sh

# 后备编辑器
export EDITOR=vim
export VISUAL=code

API 响应格式

插件返回结构化的 JSON 响应：

成功响应 (200)

{
  "success": true,
  "message": "编辑器启动请求发送成功",
  "file": "/path/to/file.js:42:15",
  "editor": "code"
}

错误响应 (400/500)

{
  "error": "Bad Request",
  "message": "缺少必需的查询参数 'file'。",
  "usage": "/__open-in-editor?file=path/to/file.js:line:column"
}

安全特性

• 路径验证：防止目录遍历攻击
• 输入校验：验证所有查询参数
• 安全错误消息：不暴露内部系统信息
• CORS 保护：开发环境中仅接受同源请求

配置参考

查看 config/config.default.js 了解详细的配置选项，包含 JSDoc 文档和示例。

开发

# 安装依赖
npm install

# 运行代码检查
npm run lint

# 运行测试
npm test

# 生成覆盖率报告
npm run cov

# 检查包文件
npm run pkgfiles

测试

插件包含全面的测试覆盖：

• 中间件功能的单元测试
• 请求-响应流程的集成测试
• 边界情况和错误条件测试
• 跨平台兼容性测试

# 运行所有测试
npm test

# 运行测试并生成覆盖率
npm run cov

故障排除

常见问题

1. 编辑器无法打开

   • 确保编辑器已安装并在 PATH 中
   • 尝试设置 LAUNCH_EDITOR 环境变量
   • 检查控制台日志中的错误消息

2. 文件未找到错误

   • 验证 srcRoot 配置是否正确
   • 确保文件路径相对于 srcRoot
   • 检查文件权限

3. 插件未加载

   • 确认插件在 config/plugin.js 中已启用
   • 确保处于开发环境
   • 检查 Egg.js 应用日志

调试模式

通过设置环境变量启用调试日志：

DEBUG=egg-tools:* npm run dev

高级用法

自定义编辑器启动脚本

创建自定义启动脚本来处理特殊需求：

#!/bin/bash
# my-editor-launcher.sh

filename=$1
line=$2
column=$3

# 自定义逻辑，例如预处理文件路径
processed_file=$(echo $filename | sed 's/^src\///')

# 启动你的编辑器
my-editor --goto "$processed_file:$line:$column"

然后设置环境变量：

export LAUNCH_EDITOR=/path/to/my-editor-launcher.sh

与构建工具集成

Webpack 集成

// webpack.config.js
const path = require("path");

module.exports = {
  // ... 其他配置
  devServer: {
    setupMiddlewares: (middlewares, devServer) => {
      // 添加自定义中间件来处理编辑器请求
      devServer.app.get("/__open-in-editor", (req, res) => {
        const { file } = req.query;
        if (file) {
          // 转发到 Egg.js 应用
          fetch(`http://localhost:7001/__open-in-editor?file=${file}`)
            .then(() => res.json({ success: true }))
            .catch(err => res.status(500).json({ error: err.message }));
        } else {
          res.status(400).json({ error: "Missing file parameter" });
        }
      });
      return middlewares;
    }
  }
};

Vite 集成

// vite.config.js
export default {
  server: {
    proxy: {
      "/__open-in-editor": {
        target: "http://localhost:7001",
        changeOrigin: true
      }
    }
  }
};

贡献

1. Fork 仓库
2. 创建你的特性分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

请确保你的代码遵循 ESLint 配置并包含适当的测试。

许可证

MIT

问题与支持

请在 GitHub Issues 上提出问题、错误报告或功能请求。