二、前端规范化 遇到的问题及解决方案

遇到的问题及解决方案

一、ESLint 相关问题

问题 1：ESLint 报错 "require is not defined"

现象：

require is not defined

原因：

ESLint v9+ 使用扁平配置格式（Flat Config），要求配置文件使用 ES module 格式，而不是 CommonJS 格式。

解决方案：

1. 将 .eslintrc.js 或 .eslintrc.cjs 重命名为 eslint.config.js
2. 使用 import 而不是 require
3. 使用 export default 而不是 module.exports

示例：

// 错误写法
const pluginVue = require("eslint-plugin-vue");
module.exports = {
  // ...
};

// 正确写法
import pluginVue from "eslint-plugin-vue";
export default [
  // ...
];

---

问题 2：ESLint 报错 "Expected object with parse() or parseForESLint() method"

现象：

Error: Key "parser": Expected object with parse() or parseForESLint() method

原因：

Vue ESLint 解析器配置不正确。

解决方案：

确保正确配置了 vue-eslint-parser 和 TypeScript 解析器。

示例：

import vueEslintParser from "vue-eslint-parser";
import typescriptParser from "@typescript-eslint/parser";

export default [
  {
    files: ["**/*.vue"],
    languageOptions: {
      parser: vueEslintParser,
      parserOptions: {
        parser: typescriptParser,
        ecmaVersion: "latest",
        sourceType: "module",
      },
    },
  },
];

---

问题 3：ESLint 报错 "--ignore-path is deprecated"

现象：

Warning: [eslint] The --ignore-path flag is deprecated. Please use the "ignores" key in your config file instead.

原因：

ESLint v9+ 不再支持 --ignore-path 命令行参数，需要在配置文件中使用 ignores 选项。

解决方案：

1. 在 package.json 中移除 --ignore-path 参数
2. 在 eslint.config.js 中添加 ignores 配置

示例：

// package.json
{
  "scripts": {
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix"
  }
}

// eslint.config.js
const ignores = [
  "node_modules",
  "dist",
  "dist-ssr",
  "*.local",
];

export default [
  { ignores },
  // ...
];

---

问题 4：ESLint 报错 "eqeqeq" 或 "no-eq-null"

现象：

Expected '===' and instead saw '=='.

原因：

ESLint 配置了 eqeqeq 规则，要求使用严格相等（===）而不是抽象相等（==）。

解决方案：

方案 1：关闭该规则（如果项目中存在数字和字符串比较的情况）

export default [
  {
    rules: {
      eqeqeq: "off",
    },
  },
];

方案 2：修复代码，使用严格相等

// 错误
if (value == 0) {}

// 正确
if (value === 0) {}

---

二、Prettier 相关问题

问题 5：Prettier 报错 "Ignored unknown option { ignorePath: "..." }"

现象：

[warn] Ignored unknown option { ignorePath: ".prettierignore" }.

原因：

Prettier 不支持 ignorePath 配置选项。Prettier 会自动读取 .prettierignore 文件，不需要在配置中指定。

解决方案：

从 .prettierrc.cjs 中移除 ignorePath 配置。

示例：

// 错误
module.exports = {
  // ...
  ignorePath: ".prettierignore",
};

// 正确
module.exports = {
  // ...
  // 不需要 ignorePath 配置
};

---

问题 6：Prettier 不生效

现象：

保存文件时代码没有自动格式化。

原因：

1. Prettier 插件未安装
2. VSCode 配置不正确
3. 配置文件路径不正确

解决方案：

步骤 1：安装 Prettier 插件

• 在 VSCode 扩展市场搜索 "Prettier - Code formatter"
• 安装插件

步骤 2：配置 VSCode

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "prettier.configPath": ".prettierrc.cjs",
}

步骤 3：检查配置文件

• 确保 .prettierrc.cjs 存在且语法正确
• 确保配置文件在项目根目录

---

问题 7：Prettier 和 ESLint 冲突

现象：

Prettier 格式化后 ESLint 报错，或者 ESLint 修复后 Prettier 又格式化回去。

原因：

Prettier 和 ESLint 的配置不一致。

解决方案：

1. 安装 eslint-config-prettier 和 eslint-plugin-prettier
2. 在 ESLint 配置中应用 Prettier 配置
3. 确保 Prettier 和 ESLint 的配置一致

示例：

import eslintConfigPrettier from "eslint-config-prettier";

export default [
  // ...
  eslintConfigPrettier,
];

确保 Prettier 和 ESLint 的配置一致：

// .prettierrc.cjs
module.exports = {
  singleQuote: false, // 使用双引号
  semi: true, // 行尾加分号
};

// eslint.config.js
export default [
  {
    rules: {
      quotes: ["error", "double"], // 双引号
      semi: ["error", "always"], // 行尾加分号
    },
  },
];

---

三、Husky 相关问题

问题 8：Husky 不生效

现象：

提交代码时没有自动格式化和检查。

原因：

1. Husky 未正确安装
2. Git 钩子未正确配置
3. lint-staged 配置不正确

解决方案：

步骤 1：重新安装 Husky

npm install husky --save-dev
npx husky install
npm set-script prepare "husky install"

步骤 2：添加 pre-commit 钩子

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

步骤 3：配置 lint-staged

// package.json
{
  "lint-staged": {
    "*.{vue,js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,json,md}": [
      "prettier --write"
    ]
  }
}

步骤 4：测试

# 测试 pre-commit 钩子
npx husky run .husky/pre-commit

---

问题 9：Husky 报错 "command not found: lint-staged"

现象：

husky - pre-commit hook exited with code 127 (error)
command not found: lint-staged

原因：
lint-staged 未安装或未在 package.json 中配置。

解决方案：

npm install lint-staged --save-dev

确保 package.json 中有 lint-staged 配置。

---

四、VSCode 相关问题

问题 10：VSCode 报错 "Cannot find module 'eslint-config-prettier'"

现象：

Error: Cannot find module 'eslint-config-prettier'

原因：

依赖包未安装或安装不完整。

解决方案：

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

---

问题 11：VSCode 自动导入使用单引号而不是双引号

现象：

VSCode 自动导入时使用单引号：

import Layout from '@/layout/index.vue';

原因：

VSCode TypeScript 配置使用单引号。

解决方案：

在 .vscode/settings.json 中配置：

{
  "typescript.preferences.quoteStyle": "double",
  "javascript.preferences.quoteStyle": "double",
}

---

问题 12：VSCode 右下角显示 ESLint 错误

现象：

VSCode 右下角显示红色错误图标，提示 ESLint 有问题。

原因：

1. ESLint 配置文件有语法错误
2. 依赖包版本不兼容
3. VSCode ESLint 插件配置不正确

解决方案：

步骤 1：检查配置文件语法

npx eslint --print-config .

步骤 2：更新依赖包

npm update

步骤 3：配置 VSCode

{
  "eslint.useFlatConfig": true,
  "eslint.options": {
    "overrideConfigFile": "eslint.config.js"
  },
}

---

五、其他问题

问题 13：TypeScript 报错 "Unexpected any. Specify a different type"

现象：

Unexpected any. Specify a different type  @typescript-eslint/no-explicit-any

原因：

ESLint 配置了 @typescript-eslint/no-explicit-any 规则，不允许使用 any 类型。

解决方案：

方案 1：关闭该规则

export default [
  {
    rules: {
      "@typescript-eslint/no-explicit-any": "off",
    },
  },
];

方案 2：使用具体类型

// 错误
function getData(): any {
  // ...
}

// 正确
interface Data {
  // ...
}
function getData(): Data {
  // ...
}

---

问题 14：Vue 报错 "Unexpected mutation of "xxx" prop"

现象：

Unexpected mutation of "createForm" prop  vue/no-mutating-props

原因：

Vue 组件中直接修改了 prop。

解决方案：

方案 1：关闭该规则

export default [
  {
    rules: {
      "vue/no-mutating-props": "off",
    },
  },
];

方案 2：使用 emit 通知父组件更新

<template>
  <el-input v-model="localValue" />
</template>

<script setup lang="ts">
const props = defineProps<{
  modelValue: string;
}>();
const emit = defineEmits<{
  (e: "update:modelValue", value: string): void;
}>();

const localValue = computed({
  get: () => props.modelValue,
  set: (value) => emit("update:modelValue", value),
});
</script>

---

问题 15：代码标红但没有错误信息

现象：

代码编辑器中代码标红，但没有具体的错误信息。

原因：

1. 编辑器配置与项目配置不一致
2. 插件版本不兼容
3. 缓存问题

解决方案：

步骤 1：重启编辑器

步骤 2：清除缓存

rm -rf node_modules/.cache

步骤 3：重新安装依赖

rm -rf node_modules package-lock.json
npm install

步骤 4：检查配置文件

确保 .vscode/settings.json 中的配置与项目配置一致。

---

六、总结

常见问题分类

1. 配置文件格式问题

   • ESLint v9+ 使用扁平配置格式
   • Prettier 使用 CommonJS 格式
   • VSCode 使用 JSON 格式

2. 依赖包版本问题

   • ESLint v9+ 与旧版本配置不兼容
   • Vue ESLint 插件需要正确配置
   • Prettier 和 ESLint 需要配合使用

3. 编辑器配置问题

   • VSCode 需要正确配置插件
   • 配置文件路径要正确
   • 自动格式化和代码修复要开启

调试技巧

1. 查看详细错误信息

npm run lint -- --debug

2. 检查配置文件

npx eslint --print-config .
npx prettier --check .

3. 测试钩子

npx husky run .husky/pre-commit
npx lint-staged

4. 查看插件版本

npm list eslint prettier husky

预防措施

1. 使用最新版本的依赖包

npm update

2. 使用官方文档

• ESLint 官方文档
• Prettier 官方文档
• Husky 官方文档

3. 使用模板项目

npm create vite@latest . -- --template vue-ts

4. 定期检查配置

npm run lint
npm run format

---

上一篇： 01-prettier-eslint-husky安装配置.md

下一篇： 03-项目代码规范.md