---
name: eslint-setup
version: 1.0.0
description: |
  为 Vue3 / Vue2 / uniapp / React 项目配置 novlan1 专属 ESLint 全家桶
  （eslint-config-light-vue3 + eslint-config-rookie + eslint-plugin-light + 全量依赖清单），
  并生成 .eslintrc.js / .eslintignore / tsconfig.eslint.json / package.json script。

  使用场景：
  - 新项目接入 eslint（"配置 eslint" / "加 eslint" / "接入 eslint" / "eslint 初始化"）
  - 现有项目升级到用户专属 eslint 规范
  - 想统一所有项目的代码风格（分号/单引号/import 顺序/命名规范）

  前置条件：项目已初始化（有 package.json），pnpm/npm 可用。
---

# ESLint Setup — novlan1 专属 ESLint 配置

> **版本**: v1.0.0

为项目配置 novlan1 自己维护的 ESLint 规范（`eslint-config-light-vue3` 全家桶），
所有项目统一风格：**分号 + 单引号 + import 顺序强制 + Airbnb 基础规则 + Vue/TS strict**。

---

## 一、依赖清单（复制即用）

```bash
pnpm i -D \
  eslint@8.57.1 \
  eslint-config-light-vue3@latest \
  eslint-config-rookie@1.1.2 \
  eslint-plugin-light@1.0.3 \
  eslint-import-resolver-alias@1.1.2 \
  eslint-import-resolver-node@0.3.9 \
  eslint-plugin-import@2.26.0 \
  eslint-plugin-jest@25 \
  eslint-plugin-prettier@4.2.1 \
  eslint-plugin-react@7.26.1 \
  eslint-plugin-react-hooks@4.2.0 \
  eslint-plugin-vue@9.14.0 \
  @typescript-eslint/eslint-plugin@7.18.0 \
  @typescript-eslint/parser@7.18.0 \
  dotenv@^16.5.0
```

> ⚠️ **eslint 必须锁 8.57.1**（不是 9.x）——eslint-config-light-vue3 基于 eslint 8 的 `.eslintrc` 格式，9.x 是 flat config 且不兼容。
> ⚠️ `eslint-plugin-tailwindcss@3.18.0` 仅 Tailwind 项目需要，非 Tailwind 项目**不要装**（否则 .eslintrc 里配了插件会报错）。
> ⚠️ `eslint-plugin-jest` 需锁 `25`（26+ 破坏性变更）。

## 二、配置文件

### 1. `.eslintrc.js`

**Vue3 + Vite + TS（非 uniapp，参考 koa-blog-end/packages/web / gp-hor）：**

```js
module.exports = {
  root: true,
  // 用户专属 eslint 配置（novlan1 维护）：Vue3 全家桶规则
  extends: ['eslint-config-light-vue3'],
  globals: {
    globalThis: true,
  },
  parserOptions: {
    ecmaVersion: 'latest',
    extraFileExtensions: ['.vue'],
  },
  overrides: [
    {
      files: ['*.js', '*.ts'],
      excludedFiles: ['*.test.js', '*.spec.js'],
      parserOptions: {
        project: require('path').resolve(__dirname, 'tsconfig.eslint.json'),
      },
    },
  ],
  rules: {
    // 与 koa-blog-end/packages/web 保持一致：允许 PascalCase 文件名
    // （View 组件叫 XxxView.vue 时，改成 kebab-case 会破坏路由 import 可读性）
    'light/valid-file-name': 0,
  },
  settings: {
    'import/resolver': {
      alias: {
        map: [
          // 参照项目的 @ 别名配置映射（vite.config.ts / webpack alias）
          ['@', './src'],
        ],
        extensions: ['.ts', '.tsx', '.js', '.jsx', '.json', '.vue'],
      },
    },
    'import/ignore': ['node_modules'],
  },
};
```

**uniapp 项目**额外要点：
- globals 加 `uni: true, getCurrentPages: true, wx: true, qq: true, $t: true`
- alias map 按 uniapp 实际路径配置（如 `['@', './src']` + `['@/api', './src/api']` 等）
- 参考项目：gp-next（uniapp）/ gp-hor（非 uniapp）

### 2. `.eslintignore`

```gitignore
node_modules/
dist/
*.local
script/
```

### 3. `tsconfig.eslint.json`

```json
{
  "extends": "./tsconfig.json",
  "include": [
    "**/*.ts",
    "**/*.js",
    "src/**/*.d.ts",
    "src/**/*.vue",
    ".eslintrc.js",
    "vite.config.ts"
  ]
}
```

### 4. package.json scripts

```json
"lint": "eslint . --fix"
```

---

## 三、执行流程（给 AI）

1. 先 `ls package.json` 确认项目存在，读 `package.json` 看框架类型（Vue3/uni-app/React）
2. 按框架类型选择 `.eslintrc.js` 模板（见上文）
3. 执行依赖安装命令（见上文依赖清单）
4. 创建 `.eslintrc.js` / `.eslintignore` / `tsconfig.eslint.json`
5. package.json 加 `"lint": "eslint . --fix"` script
6. 跑 `pnpm lint`（或 `npx eslint . --fix`）自动修复存量代码风格
7. 若剩余 error 无法自动修复，逐个处理：
   - `light/valid-file-name` → 项目是 PascalCase 风格则 `.eslintrc.js` 关掉（`'light/valid-file-name': 0`）
   - `no-explicit-any` / `no-param-reassign` → 属于 warning 可保留（不阻塞 lint 退出码）
   - import 顺序报错 → `pnpm lint` 的 `--fix` 会自动排序，不用手改
8. 验收：`npx eslint .` 退出码 0（可留 warning）

---

## 四、常见问题

1. **VSCode 保存时自动格式化（.vue / .html）**

`.vscode/settings.json`：

```json
{
  "[vue]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
  },
  "[html]": {
    "editor.defaultFormatter": "dbaeumer.vscode-eslint",
    "editor.formatOnSave": false,
    "editor.codeActionsOnSave": {
      "source.fixAll.eslint": "explicit"
    }
  },
  "eslint.validate": ["javascript", "typescript", "vue", "html"]
}
```

2. **`Unable to resolve path to module`（index.vue 报错）**

settings 里配了 `import/resolver.alias` 就能解决；alias map 必须与构建工具的 @ 别名 1:1。

3. **eslint 报 `project` 相关错误**

`tsconfig.eslint.json` 必须存在且被 `.eslintrc.js` 的 overrides 引用；若项目无 TS 可删除 overrides 整块。

4. **lint-staged + husky pre-commit（可选）**

```bash
pnpm i -D lint-staged husky
```

```json
// package.json
"lint-staged": {
  "*.{js,ts,vue}": ["eslint --fix"]
}
```

5. **为什么不用 prettier 单独配置**

eslint-config-light-vue3 内置 `eslint-plugin-prettier`（prettier 规则走 eslint 报错），无需单独 prettier 配置，VSCode 格式化器直接选 eslint。

---

## 五、参考项目

| 项目类型 | 参考仓库 | 文件 |
|---|---|---|
| Vue3 + Vite（非 uniapp） | koa-blog-end/packages/web | [.eslintrc.js](https://github.com/novlan1/koa-blog-end/blob/master/packages/web/.eslintrc.js) |
| uniapp | gp-next | .eslintrc.js + tsconfig.eslint.json |
| 配置包源码 | plugin-light/packages/eslint-config-light-vue3 | index.js（lib 下按文件类型分发规则） |
| 文档 | plugin-light/docs/zh/eslint-config-light-vue3.md | 使用 + FAQ |