一、前端规范化 Prettier + ESLint + Husky 安装配置指南

Prettier + ESLint + Husky 安装配置指南

一、安装依赖

1. 安装核心依赖

# 安装 ESLint 及相关插件
npm install eslint @typescript-eslint/eslint-plugin @typescript-eslint/parser --save-dev

# 安装 Prettier 及相关插件
npm install prettier eslint-plugin-prettier eslint-config-prettier --save-dev

# 安装 Vue ESLint 解析器
npm install eslint-plugin-vue vue-eslint-parser --save-dev

# 安装 Husky 和 lint-staged
npm install husky lint-staged --save-dev

2. 初始化 Husky

npx husky install
npm set-script prepare "husky install"
npx husky add .husky/pre-commit "npx lint-staged"

二、配置文件

1. Prettier 配置 (.prettierrc.cjs)

module.exports = {
  // 一行最多 120 字符
  printWidth: 120,
  // 使用 2 个空格缩进
  tabWidth: 2,
  // 不使用缩进符，而使用空格
  useTabs: false,
  // 行尾需要有分号
  semi: true,
  // 使用双引号
  singleQuote: false,
  // 对象的 key 仅在必要时用引号
  quoteProps: "as-needed",
  // jsx 不使用单引号，而使用双引号
  jsxSingleQuote: false,
  // 末尾需要有逗号
  trailingComma: "es5",
  // 大括号内的首尾需要空格
  bracketSpacing: true,
  // jsx 标签的反尖括号需要换行
  bracketSameLine: false,
  // 箭头函数，只有一个参数的时候，也需要括号
  arrowParens: "always",
  // 每个文件格式化的范围是文件的全部内容
  rangeStart: 0,
  rangeEnd: Infinity,
  // 不需要写文件开头的 @prettier
  requirePragma: false,
  // 不需要自动在文件开头插入 @prettier
  insertPragma: false,
  // 使用默认的折行标准
  proseWrap: "preserve",
  // 根据显示样式决定 html 要不要折行
  htmlWhitespaceSensitivity: "css",
  // vue 文件中的 script 和 style 内不用缩进
  vueIndentScriptAndStyle: false,
  // 换行符使用 lf
  endOfLine: "lf",
  // 格式化嵌入的内容
  embeddedLanguageFormatting: "auto",
};

2. Prettier 忽略文件 (.prettierignore)

node_modules
dist
dist-ssr
*.local

# Editor directories and files
.vscode/*
!.vscode/extensions.json
.idea
.DS_Store
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

# 忽略的文件类型
*.md
*.json
*.lock

3. ESLint 配置 (eslint.config.js)

import pluginVue from "eslint-plugin-vue";
import pluginPrettier from "eslint-plugin-prettier";
import typescriptEslint from "@typescript-eslint/eslint-plugin";
import typescriptParser from "@typescript-eslint/parser";
import vueEslintParser from "vue-eslint-parser";
import eslintConfigPrettier from "eslint-config-prettier";
import globals from "globals";

// 定义忽略的文件
const ignores = [
  "node_modules",
  "dist",
  "dist-ssr",
  "*.local",
  ".vscode/*",
  "!.vscode/extensions.json",
  ".idea",
  ".DS_Store",
  "*.suo",
  "*.ntvs*",
  "*.njsproj",
  "*.sln",
  "*.sw?",
];

export default [
  // 忽略文件配置
  { ignores },

  // 基础配置
  {
    files: ["**/*.{js,mjs,cjs,ts}"],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
        ...globals.es2021,
      },
      parser: typescriptParser,
      parserOptions: {
        ecmaVersion: "latest",
        sourceType: "module",
      },
    },
    plugins: {
      "@typescript-eslint": typescriptEslint,
      prettier: pluginPrettier,
    },
    rules: {
      // 关闭console和debugger的警告
      "no-console": process.env.NODE_ENV === "production" ? "warn" : "off",
      "no-debugger": process.env.NODE_ENV === "production" ? "warn" : "off",

      // TypeScript相关规则
      "@typescript-eslint/no-unused-vars": "off",
      "@typescript-eslint/no-explicit-any": "off",
      "@typescript-eslint/explicit-function-return-type": "off",
      "@typescript-eslint/explicit-module-boundary-types": "off",

      // Prettier相关规则
      "prettier/prettier": "error",

      // 其他规则
      "no-unused-vars": "off",
      "no-undef": "off",
      "no-var": "error",
      "prefer-const": "error",
      eqeqeq: "off",
      curly: "error",
      quotes: ["error", "double", { avoidEscape: true }],
      semi: ["error", "always"],
    },
  },

  // Vue文件的特殊配置
  {
    files: ["**/*.vue"],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node,
        ...globals.es2021,
      },
      parser: vueEslintParser,
      parserOptions: {
        parser: typescriptParser,
        ecmaVersion: "latest",
        sourceType: "module",
      },
    },
    plugins: {
      vue: pluginVue,
      prettier: pluginPrettier,
    },
    rules: {
      // Vue相关规则
      "vue/multi-word-component-names": "off",
      "vue/no-unused-vars": "off",
      "vue/no-mutating-props": "off",
      "vue/require-default-prop": "off",
      "vue/require-explicit-emits": "off",

      // Prettier相关规则
      "prettier/prettier": ["error", { parser: "vue" }],
    },
  },

  // 应用eslint-config-prettier
  eslintConfigPrettier,
];

4. package.json 配置

{
  "scripts": {
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix",
    "format": "prettier --write src/"
  },
  "lint-staged": {
    "*.{vue,js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss,json,md}": [
      "prettier --write"
    ]
  }
}

5. VSCode 配置 (.vscode/settings.json)

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit"
  },
  "prettier.configPath": ".prettierrc.cjs",
  "eslint.useFlatConfig": true,
  "eslint.options": {
    "overrideConfigFile": "eslint.config.js"
  },
  "typescript.preferences.quoteStyle": "double",
  "javascript.preferences.quoteStyle": "double",
  "typescript.suggest.autoImports": true,
  "javascript.suggest.autoImports": true
}

三、使用方法

1. 手动格式化

# 格式化所有文件
npm run format

# 检查并修复 ESLint 问题
npm run lint

2. 自动格式化

• 保存文件时自动格式化（需要 VSCode 配置）
• 提交代码时自动格式化（通过 Husky 和 lint-staged）

四、注意事项

1. ESLint v9+ 使用扁平配置格式

   • 使用 eslint.config.js 而不是 .eslintrc.js
   • 使用 export default 导出配置

2. Prettier 配置文件

   • 使用 .prettierrc.cjs 而不是 .prettierrc.js
   • 因为 Prettier 不支持 ES module 格式

3. VSCode 插件

   • 确保安装了 ESLint 和 Prettier 插件
   • 配置文件路径要正确

4. 忽略文件

   • Prettier 和 ESLint 都有各自的忽略文件
   • 确保忽略了不需要检查的文件

五、常见问题

1. ESLint 报错 "require is not defined"

原因： ESLint v9+ 使用 ES module 格式

解决方案：

• 使用 import 而不是 require
• 配置文件使用 .js 扩展名

2. Prettier 不生效

原因： Prettier 配置文件格式不正确

解决方案：

• 使用 .prettierrc.cjs 扩展名
• 确保配置文件语法正确

3. VSCode 不自动格式化

原因： VSCode 配置不正确

解决方案：

• 安装 Prettier 插件
• 配置 editor.defaultFormatter
• 配置 prettier.configPath

4. Husky 不生效

原因： Husky 钩子未正确安装

解决方案：

• 重新安装 Husky
• 检查 .husky/pre-commit 文件是否存在
• 确保 npx lint-staged 命令正确

---

下一篇： 02-遇到的问题及解决方案.md