TypeScript ESLint 集成实践指南

┌─────────────────────────────────────────────────────────────┐
│                    代码质量保障体系                          │
├─────────────────────────┬───────────────────────────────────┤
│      TypeScript         │            ESLint                 │
├─────────────────────────┼───────────────────────────────────┤
│  ✓ 类型检查             │  ✓ 代码风格检查                   │
│  ✓ 编译错误             │  ✓ 最佳实践建议                   │
│  ✓ 类型推导             │  ✓ 潜在错误识别                   │
│  ✓ 语法转换             │  ✓ 自动修复能力                   │
└─────────────────────────┴───────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    ESLint 工具链架构                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │   Parser    │───▶│    Rules    │───▶│   Report    │    │
│  │  解析器     │    │   规则集    │    │   报告      │    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
│         │                  │                  │            │
│         ▼                  ▼                  ▼            │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│  │   AST       │    │  Plugins    │    │   Fix       │    │
│  │  语法树     │    │   插件      │    │   自动修复  │    │
│  └─────────────┘    └─────────────┘    └─────────────┘    │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   辅助工具                           │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │  Prettier  │  Husky  │  Lint-Staged  │  Editor     │   │
│  │  格式化    │  钩子   │  暂存检查     │  编辑器集成  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

源代码 → 解析器(AST) → 规则检查 → 问题报告 → 自动修复(可选)

# npm
npm init @eslint/config

# 或使用 npx
npx eslint --init

? How would you like to use ESLint?
  ❯ To check syntax only
    To check syntax and find problems
    To check syntax, find problems, and enforce code style

? What type of modules does your project use?
  ❯ JavaScript modules (import/export)
    CommonJS (require/exports)
    None of these

? Which framework does your project use?
  ❯ React
    Vue.js
    None of these

? Does your project use TypeScript? › Yes

? Where does your code run?
  ◉ Browser
  ◯ Node

- eslint                    # ESLint 核心
- @typescript-eslint/parser # TypeScript 解析器
- @typescript-eslint/eslint-plugin # TypeScript 规则插件
- eslint-plugin-react       # React 相关规则（如果选择了 React）

# npm
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# yarn
yarn add --dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# pnpm
pnpm add --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
    project: "./tsconfig.json"
  },
  plugins: ["@typescript-eslint"],
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ],
  rules: {}
}

# 依赖目录
node_modules/

# 构建产物
dist/
build/
out/

# 配置文件
*.config.js
*.json

# 其他文件
*.html
*.css
*.svg

{
  "scripts": {
    "lint": "eslint src --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint src --ext .js,.jsx,.ts,.tsx --fix",
    "lint:ci": "eslint src --ext .js,.jsx,.ts,.tsx --max-warnings 0"
  }
}

# 仅检查
npm run lint

# 检查并自动修复
npm run lint:fix

# CI 环境严格检查（任何警告都视为错误）
npm run lint:ci

module.exports = {
  parser: "@typescript-eslint/parser",

  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module",
    project: "./tsconfig.json",
    tsconfigRootDir: __dirname
  }
}

module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking",
    "prettier"
  ]
}

rules: {
  'rule-name': 'off' | 'warn' | 'error' | [level, options]
}

module.exports = {
  rules: {
    "no-console": "warn",

    "@typescript-eslint/explicit-function-return-type": [
      "error",
      {
        allowExpressions: true,
        allowTypedFunctionExpressions: true
      }
    ],

    indent: "off",
    "@typescript-eslint/indent": ["error", 2],

    quotes: "off",
    "@typescript-eslint/quotes": ["error", "single"],

    semi: "off",
    "@typescript-eslint/semi": ["error", "always"]
  }
}

module.exports = {
  plugins: ["@typescript-eslint", "react", "import"]
}

module.exports = {
  env: {
    browser: true,
    node: true,
    es2021: true,
    jest: true,
    mocha: true
  }
}

module.exports = {
  overrides: [
    {
      files: ["**/*.test.ts", "**/*.spec.ts"],
      env: {
        jest: true
      },
      rules: {
        "@typescript-eslint/no-explicit-any": "off"
      }
    },
    {
      files: ["*.config.js", "*.config.ts"],
      rules: {
        "@typescript-eslint/no-var-requires": "off"
      }
    }
  ]
}

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:import/recommended",
    "plugin:import/typescript",
    "prettier"
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
    ecmaFeatures: {
      jsx: true
    },
    project: "./tsconfig.json"
  },
  plugins: ["react", "react-hooks", "@typescript-eslint", "import"],
  settings: {
    react: {
      version: "detect"
    },
    "import/resolver": {
      typescript: {}
    }
  },
  rules: {
    "react/react-in-jsx-scope": "off",
    "react/prop-types": "off",
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn",

    "@typescript-eslint/explicit-module-boundary-types": "off",
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-unused-vars": [
      "error",
      { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }
    ],

    "import/order": [
      "error",
      {
        groups: ["builtin", "external", "internal", "parent", "sibling", "index"],
        "newlines-between": "always",
        alphabetize: { order: "asc" }
      }
    ]
  }
}

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    "eslint:recommended",
    "plugin:vue/vue3-recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  parser: "vue-eslint-parser",
  parserOptions: {
    parser: "@typescript-eslint/parser",
    ecmaVersion: "latest",
    sourceType: "module"
  },
  plugins: ["vue", "@typescript-eslint"],
  rules: {
    "vue/multi-word-component-names": "off",
    "vue/no-v-html": "warn",

    "@typescript-eslint/no-explicit-any": "warn"
  }
}

# npm
npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier

# yarn
yarn add --dev prettier eslint-config-prettier eslint-plugin-prettier

# pnpm
pnpm add --save-dev prettier eslint-config-prettier eslint-plugin-prettier

module.exports = {
  printWidth: 80,
  tabWidth: 2,
  semi: true,
  singleQuote: true,
  quoteProps: "as-needed",
  jsxSingleQuote: false,
  trailingComma: "es5",
  bracketSpacing: true,
  bracketSameLine: false,
  endOfLine: "lf"
}

module.exports = {
  extends: ["plugin:react/recommended", "plugin:@typescript-eslint/recommended", "prettier"]
}

build
dist
out
node_modules

{
  "scripts": {
    "eslint": "eslint src/** --no-error-on-unmatched-pattern --ext .js,.jsx,.ts,.tsx --cache",
    "eslint:fix": "npm run eslint -- --fix",
    "prettier": "prettier --check .",
    "prettier:fix": "prettier --write .",
    "lint": "npm run eslint && npm run prettier",
    "lint:fix": "npm run eslint:fix && npm run prettier:fix"
  }
}

# npm
npx husky-init && npm install

# yarn
npx husky-init && yarn

# pnpm
pnpm dlx husky-init && pnpm install

npx husky add .husky/pre-commit 'npx lint-staged'

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

npm install --save-dev lint-staged
yarn add --save-dev lint-staged
pnpm install --save-dev lint-staged

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --cache --fix", "prettier --write --list-different"],
    "*.{json,md,html,css,scss,sass,less,styl}": ["prettier --write --list-different"]
  }
}

┌─────────────────────────────────────────────────────────────┐
│                    Git Hooks 工作流程                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  git commit                                                 │
│      │                                                      │
│      ▼                                                      │
│  ┌─────────────┐                                           │
│  │ pre-commit  │                                           │
│  │   钩子触发   │                                           │
│  └──────┬──────┘                                           │
│         │                                                   │
│         ▼                                                   │
│  ┌─────────────┐                                           │
│  │ lint-staged │                                           │
│  │  检查暂存区  │                                           │
│  └──────┬──────┘                                           │
│         │                                                   │
│         ▼                                                   │
│  ┌─────────────────────────────────────────┐               │
│  │           对暂存文件执行检查              │               │
│  ├─────────────────────────────────────────┤               │
│  │  *.ts/*.tsx → ESLint → Prettier         │               │
│  │  *.css/*.json → Prettier                │               │
│  └──────────────────┬──────────────────────┘               │
│                     │                                       │
│         ┌───────────┴───────────┐                          │
│         ▼                       ▼                          │
│  ┌─────────────┐         ┌─────────────┐                  │
│  │   检查通过   │         │   检查失败   │                  │
│  └──────┬──────┘         └──────┬──────┘                  │
│         │                       │                          │
│         ▼                       ▼                          │
│  ┌─────────────┐         ┌─────────────┐                  │
│  │ commit 成功 │         │ commit 失败 │                  │
│  └─────────────┘         └─────────────┘                  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

npm i eslint-config-ts-ruleset --save-dev
yarn add eslint-config-ts-ruleset --save-dev
pnpm i eslint-config-ts-ruleset --save-dev

module.exports = {
  root: true,
  extends: ["plugin:@typescript-eslint/recommended", "prettier", "ts-ruleset", "ts-ruleset/strict"],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    project: "./tsconfig.json"
  },
  plugins: ["react", "@typescript-eslint"],
  rules: {
    "react/react-in-jsx-scope": "off"
  }
}

'@typescript-eslint/array-type': ['error', {
  default: 'array',           // 默认使用 T[]
  readonly: 'array',          // readonly 使用 T[]
}]

// ❌ default: 'array' 时错误
const arr: Array<string> = ["a", "b", "c"]
const readonlyArr: ReadonlyArray<string> = ["a", "b", "c"]

// ✅ 正确
const arr: string[] = ["a", "b", "c"]
const readonlyArr: readonly string[] = ["a", "b", "c"]

'@typescript-eslint/consistent-type-assertions': ['error', {
  assertionStyle: 'as',       // 使用 as 语法
  objectLiteralTypeAssertions: 'allow-as-parameter',  // 对象字面量断言
}]

// ❌ assertionStyle: 'as' 时错误
const foo = <string>bar;

// ✅ 正确
const foo = bar as string;

// 特殊情况：在 JSX 中必须使用 as
const elem = <Component foo={bar as string} />;

'@typescript-eslint/consistent-type-definitions': ['error', 'interface']

// ❌ 使用 'interface' 时错误
type User = {
  name: string
  age: number
}

// ✅ 正确
interface User {
  name: string
  age: number
}

// ✅ type 仍可用于联合类型、交叉类型等
type Status = "pending" | "approved" | "rejected"
type UserWithRole = User & { role: string }

// ❌ 不推荐
const array = ["a", "b", "c"]
for (let i = 0; i < array.length; i++) {
  console.log(array[i])
}

// ✅ 推荐
const array = ["a", "b", "c"]
for (const item of array) {
  console.log(item)
}

// ✅ 需要索引时仍可使用 for 循环
for (let i = 0; i < array.length; i++) {
  console.log(i, array[i])
}

// ❌ 不推荐
const foo = obj && obj.a && obj.a.b && obj.a.b.c

// ✅ 推荐
const foo = obj?.a?.b?.c

// ❌ 不推荐
const bar = obj && obj.method && obj.method()

// ✅ 推荐
const bar = obj?.method?.()

'@typescript-eslint/explicit-function-return-type': ['error', {
  allowExpressions: true,              // 允许表达式函数不标注
  allowTypedFunctionExpressions: true, // 允许已类型的函数表达式不标注
  allowHigherOrderFunctions: true,     // 允许高阶函数不标注
  allowDirectConstAssertionInArrowFunctions: true, // 允许箭头函数 const 断言
}]

// ❌ 错误
function foo() {
  return "bar"
}

// ✅ 正确
function foo(): string {
  return "bar"
}

// ✅ allowExpressions: true 时允许
const result = [1, 2, 3].map((n) => n * 2)

// ✅ 箭头函数作为变量赋值时
const add = (a: number, b: number): number => a + b

'@typescript-eslint/explicit-module-boundary-types': ['error', {
  allowArgumentsExplicitlyTypedAsAny: true,
  allowedNames: ['handler'],  // 允许的函数名
}]

// ❌ 错误：导出的函数需要标注返回类型
export function add(a: number, b: number) {
  return a + b
}

// ✅ 正确
export function add(a: number, b: number): number {
  return a + b
}

// ✅ 内部函数不需要标注
function internalHelper() {
  return "helper"
}

// ❌ 错误：类型可以自动推断
const foo: number = 1
const bar: string = "bar"
const baz: boolean = true

// ✅ 正确
const foo = 1
const bar = "bar"
const baz = true

// ✅ 允许显式标注（用于文档目的）
const config: MyConfig = {
  /* ... */
}

'@typescript-eslint/no-explicit-any': ['error', {
  fixToUnknown: true,         // 自动修复为 unknown
  ignoreRestArgs: true,       // 允许剩余参数使用 any
}]

// ❌ 错误
function foo(value: any): any {
  return value
}

// ✅ 正确
function foo<T>(value: T): T {
  return value
}

// ✅ 使用 unknown 进行类型收窄
function process(value: unknown) {
  if (typeof value === "string") {
    return value.toUpperCase()
  }
}

// ✅ ignoreRestArgs: true 时允许
function merge(target: any, ...sources: any[]) {
  return Object.assign(target, ...sources)
}

// ❌ 错误：条件总是真
const value: string = "foo"
if (value) {
  console.log(value)
}

// ❌ 错误：类型推断已确定
function foo(value: "a" | "b") {
  if (value === "a") {
    return 1
  } else if (value === "b") {
    return 2
  } else {
    // ❌ 这里的 value 类型是 never
    return 3
  }
}

// ✅ 正确：必要的类型收窄
function bar(value: string | number) {
  if (typeof value === "string") {
    return value.toUpperCase()
  }
  return value.toFixed(2)
}

'@typescript-eslint/prefer-nullish-coalescing': ['error', {
  ignoreConditionalTests: true,
  ignoreMixedLogicalExpressions: true,
}]

// ❌ 错误：|| 会过滤掉 0 和 ''
const foo = value || "default"
const bar = count || 10

// ✅ 正确：使用 ??
const foo = value ?? "default"
const bar = count ?? 10

// 区别说明
const a = 0 || "default" // 'default'（0 是 falsy）
const b = 0 ?? "default" // 0（0 不是 null/undefined）

const c = "" || "default" // 'default'（'' 是 falsy）
const d = "" ?? "default" // ''（'' 不是 null/undefined）

// ❌ 错误：数组不会被修改
const arr: number[] = [1, 2, 3]

// ✅ 正确
const arr: readonly number[] = [1, 2, 3]

// ❌ 错误：对象不会被修改
const config: Config = { debug: true }

// ✅ 正确
const config: Readonly<Config> = { debug: true }

'@typescript-eslint/strict-boolean-expressions': ['error', {
  allowString: false,    // 不允许字符串隐式转换
  allowNumber: false,    // 不允许数字隐式转换
  allowNullableObject: true,  // 允许可空对象检查
}]

// ❌ 错误：隐式转换
const value: string = "foo"
if (value) {
  console.log(value)
}

// ✅ 正确：显式检查
if (value.length > 0) {
  console.log(value)
}

// ❌ 错误：数字隐式转换
const count: number = 0
if (count) {
  console.log(count)
}

// ✅ 正确：显式检查
if (count > 0) {
  console.log(count)
}

// ✅ allowNullableObject: true 时允许
const obj: string | null = null
if (obj) {
  // 检查 null/undefined
  console.log(obj)
}

'@typescript-eslint/no-floating-promises': ['error', {
  ignoreVoid: true,  // 允许使用 void 忽略
  ignoreIIFE: true,  // 允许 IIFE 形式
}]

// ❌ 错误：Promise 未被处理
async function fetchData() {
  return fetch("/api/data")
}

fetchData() // Promise 被忽略

// ✅ 正确：使用 await
async function main() {
  await fetchData()
}

// ✅ 正确：使用 catch
fetchData().catch(console.error)

// ✅ 正确：使用 void（ignoreVoid: true）
void fetchData()

// ✅ 正确：使用 then
fetchData().then(console.log)

// ❌ 错误：对非 Promise 使用 await
async function foo() {
  const value = await 42
  const text = await "hello"
}

// ✅ 正确
async function foo() {
  const value = 42
  const text = "hello"
}

// ✅ 正确：对 Promise 使用 await
async function bar() {
  const response = await fetch("/api/data")
  const data = await response.json()
}

'@typescript-eslint/no-misused-promises': ['error', {
  checksConditionals: true,
  checksVoidReturn: true,
}]

// ❌ 错误：Promise 在条件中总是 truthy
async function checkPermission() {
  return true
}

if (checkPermission()) {
  // 忘记 await
  console.log("allowed")
}

// ✅ 正确
if (await checkPermission()) {
  console.log("allowed")
}

// ❌ 错误：Promise 回调不应该是 async
;[1, 2, 3].forEach(async (item) => {
  await processItem(item)
})

// ✅ 正确：使用 for...of
for (const item of [1, 2, 3]) {
  await processItem(item)
}

module.exports = {
  extends: [
    "plugin:@typescript-eslint/recommended",
    "prettier" // 必须放在最后
  ]
}

{
  "scripts": {
    "lint:ci": "eslint . --ext .js,.jsx,.ts,.tsx --max-warnings 0"
  }
}

// eslint-disable-next-line @typescript-eslint/no-explicit-any
const value: any = JSON.parse(data)

/* eslint-disable @typescript-eslint/no-explicit-any */
const a: any = 1
const b: any = 2
/* eslint-enable @typescript-eslint/no-explicit-any */

declare module "untyped-package" {
  const value: any
  export default value
}

parserOptions: {
  project: './tsconfig.json',
}

// packages/eslint-config/index.js
module.exports = {
  extends: ["plugin:@typescript-eslint/recommended", "prettier"],
  rules: {
    // 共享规则
  }
}

// packages/app/.eslintrc.js
module.exports = {
  extends: ["@my-org/eslint-config"]
}

// .eslintrc.js
module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking",
    "prettier"
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
    project: "./tsconfig.json"
  },
  plugins: ["@typescript-eslint"],
  rules: {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/no-unused-vars": [
      "error",
      {
        argsIgnorePattern: "^_"
      }
    ],
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-floating-promises": "error",
    "@typescript-eslint/await-thenable": "error"
  }
}

┌─────────────────────────────────────────────────────────────┐
│                    规则启用策略                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  第一阶段：基础规则                                          │
│  ├── plugin:@typescript-eslint/recommended                  │
│  └── 解决所有 error 级别问题                                 │
│                                                             │
│  第二阶段：类型感知规则                                      │
│  ├── 添加 parserOptions.project                             │
│  ├── plugin:@typescript-eslint/recommended-requiring-type   │
│  └── 解决类型相关问题                                        │
│                                                             │
│  第三阶段：严格规则                                          │
│  ├── no-explicit-any: error                                 │
│  ├── no-floating-promises: error                            │
│  └── 其他团队约定规则                                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

// .vscode/settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"]
}

// .vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "editorconfig.editorconfig"
  ]
}