【前端】手把手教你用TypeScript写一个简单的eslint插件并发布到npm

一、背景与问题

在现代前端开发中，代码质量保障是团队协作的核心环节。ESLint作为最流行的JavaScript代码检查工具，其插件机制为开发者提供了高度可定制的规则体系。但传统的ESLint规则多为JavaScript写成，缺乏类型安全和IDE的智能提示。本文将深入解析如何用TypeScript实现一个完整的ESLint插件，并发布到npm仓库。

关键问题包括：

1. 如何通过AST遍历实现规则校验
2. 如何结合TypeScript类型系统增强规则定义
3. 如何处理复杂的规则逻辑和修复建议
4. 如何在CI/CD流程中集成插件

二、基本原理

ESLint插件的核心原理是通过AST（抽象语法树）遍历机制实现代码校验。每个规则都包含三个核心部分：

1. 规则定义：通过create函数定义规则逻辑
2. AST遍历：通过RuleContext对象访问AST节点
3. 警告生成：通过context.report()方法生成错误信息

TypeScript带来的优势：

• 强类型校验防止运行时错误
• IDE智能提示提升开发效率
• 更清晰的接口定义

三、环境准备

# 安装依赖
npm init -y
npm install eslint @typescript-eslint/eslint-plugin --save-dev
npm install typescript @types/eslint --save-dev

配置tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2015",
    "module": "ESNext",
    "strict": true,
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src"]
}

四、核心实现

1. 规则定义结构

// src/rules/no-unused-vars.ts
import { Rule } from 'eslint';
import { TSESTree } from '@typescript-eslint/types';

export default class NoUnusedVarsRule implements Rule.RuleModule {
  public meta = {
    type: 'suggestion',
    docs: { recommended: false },
    schema: []
  };

  public create(context: Rule.RuleContext) {
    return {
      'VariableDeclaration': (node: TSESTree.VariableDeclaration) => {
        const variables = node.declarations.map(d => d.id.name);
        const usedVariables = new Set<string>();
        
        // 遍历AST查找使用变量的位置
        context.walk((node: TSESTree.Node) => {
          if (node.type === 'Identifier') {
            usedVariables.add(node.name);
          }
        });
        
        // 检查未使用的变量
        for (const name of variables) {
          if (!usedVariables.has(name)) {
            context.report({
              node,
              message: `未使用的变量: ${name}`,
              fix: (fixer) => {
                return fixer.removeRange([
                  node.start,
                  node.end
                ]);
              }
            });
          }
        }
      }
    };
  }
}

关键点解释：

• 使用TSESTree类型获得TypeScript AST的完整类型
• 通过walk方法遍历AST
• fix函数提供修复建议
• 使用Set优化查找效率

2. 插件结构

// src/index.ts
import { rules } from './rules';

export default {
  rules: {
    'no-unused-vars': rules.NoUnusedVarsRule
  }
};

3. 构建脚本

{
  "scripts": {
    "build": "tsc",
    "publish": "npm publish"
  }
}

五、完整案例

创建一个检查未使用变量的插件，支持修复建议：

// src/rules/no-unused-vars.ts
import { Rule } from 'eslint';
import { TSESTree } from '@typescript-eslint/types';

export default class NoUnusedVarsRule implements Rule.RuleModule {
  public meta = {
    type: 'suggestion',
    docs: { recommended: false },
    schema: []
  };

  public create(context: Rule.RuleContext) {
    return {
      'VariableDeclaration': (node: TSESTree.VariableDeclaration) => {
        const variables = node.declarations.map(d => d.id.name);
        const usedVariables = new Set<string>();
        
        // 遍历AST查找使用变量的位置
        context.walk((node: TSESTree.Node) => {
          if (node.type === 'Identifier') {
            usedVariables.add(node.name);
          }
        });
        
        // 检查未使用的变量
        for (const name of variables) {
          if (!usedVariables.has(name)) {
            context.report({
              node,
              message: `未使用的变量: ${name}`,
              fix: (fixer) => {
                return fixer.removeRange([
                  node.start,
                  node.end
                ]);
              }
            });
          }
        }
      }
    };
  }
}

六、源码解析

1. AST遍历机制

context.walk((node: TSESTree.Node) => {
  if (node.type === 'Identifier') {
    usedVariables.add(node.name);
  }
});

• walk方法会递归遍历AST所有节点
• 通过node.type判断节点类型
• Identifier类型表示变量名

2. 修复建议实现

fix: (fixer) => {
  return fixer.removeRange([
    node.start,
    node.end
  ]);
}

• fixer对象提供AST修改能力
• removeRange方法删除指定范围的代码
• 注意处理注释和换行符

七、进阶使用

1. 环境变量支持

const config = {
  env: {
    es2021: true
  },
  rules: {
    'no-unused-vars': 'error'
  }
};

2. 与Prettier集成

{
  "eslintConfig": {
    "extends": [
      "eslint:recommended",
      "plugin:@typescript-eslint/recommended"
    ],
    "rules": {
      "no-unused-vars": "error"
    }
  }
}

3. 增强规则类型

export interface CustomRuleContext extends Rule.RuleContext {
  myCustomProperty: string;
}

八、性能与工程实践

1. 性能优化

• 避免在create函数中执行耗时操作
• 使用context.getScope()获取作用域信息
• 对大型AST使用RuleContext的getAncestors方法

2. 安全风险

• 避免使用eval等危险函数
• 限制规则对AST的修改范围
• 对用户输入进行严格校验

3. 异常处理

try {
  // 可能抛出异常的代码
} catch (error) {
  context.report({
    node: null,
    message: '规则执行异常',
    severity: 'error'
  });
}

九、常见问题与踩坑

1. 规则不生效的常见原因

• 未在配置文件中正确引用插件
• 文件扩展名不匹配（如.ts文件未正确解析）
• eslint-disable注释覆盖了规则

2. AST遍历错误

// 错误示例
context.walk((node: any) => {
  // 错误地假设node是Identifier类型
});

3. 修复建议失败

// 错误示例
fix: (fixer) => {
  return fixer.replaceText(node, '');
}

十、最佳实践

1. 使用TypeScript类型定义增强规则可维护性
2. 对复杂规则进行单元测试
3. 在CI/CD中集成规则检查
4. 使用@typescript-eslint/parser处理TypeScript文件
5. 对修复建议进行严格校验

十一、总结

通过本文的深度解析，我们掌握了如何用TypeScript构建一个完整的ESLint插件。这种方案适合需要严格代码规范的中大型项目，特别是在TypeScript项目中能发挥最大价值。但需注意：

• 不适合简单的语法检查
• 不适合需要频繁修改规则的项目
• 不适合对性能要求极高的场景

在实际开发中，建议结合eslint-config-airbnb等成熟配置，形成完整的代码规范体系。同时，通过npm发布插件，可以形成团队内部的代码质量保障体系，提升团队协作效率。