Vue 前端代码规范实战：ESLint v9、Prettier 与 Stylelint 集成指南与最佳实践

🚀 作者主页： 有来技术
🔥 开源项目： youlai-mall ︱vue3-element-admin︱youlai-boot︱vue-uniapp-template
🌺 仓库主页： GitCode︱ Gitee ︱ Github
💖 欢迎点赞 👍 收藏 ⭐评论 📝 如有错误敬请纠正！

前言

本指南以开源项目 vue3-element-admin 的 Vue3 + TypeScript 技术栈为基础，提供 2025 年前端开发中 ESLint V9、Prettier 和 Stylelint 的最新配置与最佳实践，帮助开发者快速集成工具，提升团队协作效率和代码质量。

集成 ESLint

ESLint 是一款 JavaScript 和 TypeScript 的代码规范工具，能够帮助开发团队保持代码风格一致并减少常见错误。

ESLint 中文网：https://eslint.nodejs.cn/

安装插件

VSCode 插件市场搜索 ESLint 插件并安装

配置 ESLint

快速初始化

按照 ESLint 官方指南，可以使用以下命令快速生成 ESLint 配置文件：

npm init @eslint/config@latest

运行该命令后，ESLint 将通过交互式问答的方式，帮助安装相关依赖并生成默认配置文件 eslint.config.js。

默认生成的配置如下：

import globals from "globals";
import pluginJs from "@eslint/js";
import tseslint from "typescript-eslint";
import pluginVue from "eslint-plugin-vue";

/** @type {import('eslint').Linter.Config[]} */
export default [
  {files: ["**/*.{js,mjs,cjs,ts,vue}"]},
  {languageOptions: { globals: globals.browser }},
  pluginJs.configs.recommended,
  ...tseslint.configs.recommended,
  ...pluginVue.configs["flat/essential"],
  {files: ["**/*.vue"], languageOptions: {parserOptions: {parser: tseslint.parser}}},
];

定制化配置

由于项目使用了 Vue 3 和 TypeScript，我们需要在默认配置的基础上进行调整，以适配当前项目。首先，安装必要的 ESLint 依赖：

pnpm add -D eslint-plugin-vue vue-eslint-parser eslint-config-prettier eslint-plugin-prettier 

依赖	作用
eslint-plugin-vue	提供 Vue 相关的 ESLint 规则
vue-eslint-parser	解析 .vue 文件
eslint-config-prettier	关闭与 Prettier 冲突的 ESLint 规则
eslint-plugin-prettier	将 Prettier 作为 ESLint 规则进行检测

以下是优化后的 eslint.config.js 配置，涵盖了 JavaScript、TypeScript 和 Vue 代码的检查规则，并集成了 Prettier 进行代码格式化。

// https://eslint.nodejs.cn/docs/latest/use/configure/configuration-files

import globals from "globals";
import pluginJs from "@eslint/js"; // JavaScript 规则
import pluginVue from "eslint-plugin-vue"; // Vue 规则
import pluginTypeScript from "@typescript-eslint/eslint-plugin"; // TypeScript 规则

import parserVue from "vue-eslint-parser"; // Vue 解析器
import parserTypeScript from "@typescript-eslint/parser"; // TypeScript 解析器

import configPrettier from "eslint-config-prettier"; // 禁用与 Prettier 冲突的规则
import pluginPrettier from "eslint-plugin-prettier"; // 运行 Prettier 规则


/** @type {import('eslint').Linter.Config[]} */
export default [
  // 指定检查文件和忽略文件
  {
    files: ["**/*.{js,mjs,cjs,ts,vue}"],
    ignores: ["**/*.d.ts"],
  },
  // 全局配置
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
        // 添加自定义的类型
        //  PageQuery: "readonly"
        
      },
    },
    plugins: { prettier: pluginPrettier },
    rules: {
      ...configPrettier.rules, // 关闭与 Prettier 冲突的规则
      ...pluginPrettier.configs.recommended.rules, // 启用 Prettier 规则
      "prettier/prettier": "error", // 强制 Prettier 格式化
      "no-unused-vars": [
        "error",
        {
          argsIgnorePattern: "^_", // 忽略以 _ 开头的变量未使用警告
          varsIgnorePattern: "^[A-Z0-9_]+$", // 忽略变量名为大写字母、数字或下划线组合的未使用警告（枚举定义未使用场景）
          ignoreRestSiblings: true, // 忽略解构赋值中同级未使用变量的警告
        },
      ],
    },
  },
  // JavaScript 配置
  pluginJs.configs.recommended,

  // TypeScript 配置
  {
    files: ["**/*.ts"],
    ignores: ["**/*.d.ts"], // 排除d.ts文件
    languageOptions: {
      parser: parserTypeScript,
      parserOptions: {
        sourceType: "module",
      },
    },
    plugins: { "@typescript-eslint": pluginTypeScript },
    rules: {
      ...pluginTypeScript.configs.strict.rules, // TypeScript 严格规则
      "@typescript-eslint/no-explicit-any": "off", // 允许使用 any
      "@typescript-eslint/no-empty-function": "off", // 允许空函数
      "@typescript-eslint/no-empty-object-type": "off", // 允许空对象类型
    },
  },

  // Vue 配置
  {
    files: ["**/*.vue"],
    languageOptions: {
      parser: parserVue,
      parserOptions: {
        parser: parserTypeScript,
        sourceType: "module",
      },
    },
    plugins: { vue: pluginVue, "@typescript-eslint": pluginTypeScript },
    processor: pluginVue.processors[".vue"],
    rules: {
      ...pluginVue.configs["vue3-recommended"].rules, // Vue 3 推荐规则
      "vue/no-v-html": "off", // 允许 v-html
      "vue/multi-word-component-names": "off", // 允许单个单词组件名
    },
  },
];

添加 ESLint 运行脚本

为了方便使用 ESLint，我们可以在 package.json 中添加 lint 脚本：

{
  "scripts": {
    "lint:eslint": "eslint --cache  \"src/**/*.{vue,ts}\" --fix",
  }
}

该命令会自动修复符合 ESLint 规则的代码问题，并输出检查结果。

测试 ESLint

在 App.vue 文件中添加一个未使用的变量，并运行以下命令：

pnpm run lint:eslint

集成 Prettier

Prettier 是一个代码格式化工具，能够和 ESLint 配合使用，确保代码风格统一。

prettier 中文网：https://prettier.nodejs.cn/

安装插件

VSCode 插件市场搜索 Prettier - Code formatter 插件安装

安装依赖

pnpm install -D prettier eslint-config-prettier eslint-plugin-prettier 

• prettier：主要的 Prettier 格式化库。
• eslint-config-prettier：禁用 ESLint 中与 Prettier 冲突的规则。
• eslint-plugin-prettier：将 Prettier 的规则作为 ESLint 的规则来运行。

配置 Prettier

参考 Prettier 官方配置文档 在项目根目录下新建配置文件 .prettierrc.yaml，用于定义代码格式化规则。我们选择 YAML 格式，原因如下：

1. JSON 文件不支持注释，不利于配置的说明和维护。
2. JS 文件在某些情况下配置可能不生效（例如，测试发现 printWidth: 100 仍会按默认值 80 换行），可能是优先级问题，建议进一步验证。

以下是推荐的基础配置，供参考使用：

# 每行最多字符数量，超出换行(默认80)
printWidth: 100
# 缩进空格数，默认2个空格
tabWidth: 2
# 指定缩进方式，空格或tab，默认false，即使用空格
useTabs: false
# 使用分号
semi: true
# 使用单引号 (true:单引号;false:双引号)
singleQuote: false
# 末尾使用逗号
trailingComma: all

配置忽略文件

项目根目录新建 .prettierignore 文件指定 Prettier 不需要格式化的文件和文件夹

# .prettierignore
node_modules
dist
public
*.min.js

添加格式化脚本

在 package.json 文件中添加：

{
  "scripts": {
    "lint:prettier": "prettier --write \"**/*.{js,cjs,ts,json,css,scss,vue,html,md}\""
  }
}

保存自动格式化

打开 VSCode 的 File → Preferences → Settings，然后选择 Open Settings (JSON)，添加以下配置

{
  "editor.formatOnSave": true, // 保存格式化文件
  "editor.defaultFormatter": "esbenp.prettier-vscode" // 指定 prettier 为所有文件默认格式化器
}

测试 Prettier

下图演示了保存时的自动格式化效果，展示了代码中引号和换行的自动调整：

集成 Stylelint

Stylelint 一个强大的 CSS linter(检查器)，可帮助您避免错误并强制执行约定。

Stylelint 官网：https://stylelint.io/

安装插件

VSCode 插件搜索 Stylelint 并安装

安装依赖

pnpm install -D postcss postcss-html postcss-scss stylelint stylelint-config-recommended stylelint-config-recommended-scss stylelint-config-recommended-vue stylelint-config-recess-order stylelint-config-html stylelint-prettier

依赖	说明	备注
postcss	CSS 解析工具，允许使用现代 CSS 语法并将其转换为兼容的旧语法	-
postcss-html	解析 HTML (类似 HTML) 的 PostCSS 语法	参见 postcss-html 文档
postcss-scss	PostCSS 的 SCSS 解析器	参见 postcss-scss 文档，支持 CSS 行类注释
stylelint	stylelint 核心库	参见 stylelint
stylelint-config-recommended	提供了基础的 Stylelint 配置，适用于大多数项目，允许自定义规则集	与 stylelint-config-standard 相比，此配置提供了更多的灵活性
stylelint-config-recommended-scss	扩展基础配置，为 SCSS 特定规则提供支持	参见 stylelint-config-recommended-scss 文档
stylelint-config-recommended-vue	扩展基础配置，为 Vue 文件中的样式提供支持	参见 stylelint-config-recommended-vue 文档
stylelint-config-recess-order	提供优化样式顺序的配置	参见 CSS 书写顺序规范
stylelint-config-html	为 HTML (类似 HTML) 文件提供共享配置	参见 stylelint-config-html 文档
stylelint-prettier	统一代码风格，格式冲突时以 Prettier 规则为准	参见 stylelint-prettier

其中选择 stylelint-config-recommended 替代 stylelint-config-standard 的原因在于它不仅提供了灵活性，还更加轻量。stylelint-config-recommended 默认包含的规则较少，避免了 stylelint-config-standard 中可能不需要的规则，这样可以减少配置的复杂度，提高项目的启动速度，同时让开发者能够集中关注对项目真正重要的风格指南。轻量配置有助于简化工作流程，特别是在大型或复杂的项目中。

配置 Stylelint

根目录新建 .stylelintrc.cjs 文件，配置如下：

{
  "extends": [
    "stylelint-config-recommended",
    "stylelint-config-recommended-scss",
    "stylelint-config-recommended-vue/scss",
    "stylelint-config-html/vue",
    "stylelint-config-recess-order"
  ],
  "plugins": ["stylelint-prettier"],
  "overrides": [
    {
      "files": ["**/*.{vue,html}"],
      "customSyntax": "postcss-html"
    },
    {
      "files": ["**/*.{css,scss}"],
      "customSyntax": "postcss-scss"
    }
  ],

  "rules": {
    "import-notation": "string",
    "selector-class-pattern": null,
    "custom-property-pattern": null,
    "keyframes-name-pattern": null,
    "no-descending-specificity": null,
    "no-empty-source": null,
    "selector-pseudo-class-no-unknown": [
      true,
      {
        "ignorePseudoClasses": ["global", "export", "deep"]
      }
    ],
    "unit-no-unknown": [true, {
      "ignoreUnits": ["rpx"]
    }]   
    "property-no-unknown": [
      true,
      {
        "ignoreProperties": []
      }
    ],
    "at-rule-no-unknown": [
      true,
      {
        "ignoreAtRules": ["apply", "use", "forward"]
      }
    ]
  }
}

配置忽略文件

根目录创建 .stylelintignore 文件，配置忽略文件如下：

*.min.js
dist
public
node_modules

添加 Stylelint 脚本

package.json 添加 Stylelint 检测指令：

  "scripts": {
      "lint:stylelint": "stylelint  \"**/*.{css,scss,vue,html}\" --fix"
  }

保存自动修复

项目根目录下.vscode/settings.json 文件添加配置：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": true 
  },
  "stylelint.validate": ["css", "scss", "vue", "html"]
}

为了验证把尺寸属性 width 放置在定位属性 position 前面，根据 CSS 书写顺序规范 推断是不符合规范的，在保存时 Stylelint 自动将属性重新排序，达到预期。

测试 Stylelint

执行以下命令进行检测

npm run lint:stylelint

结语

通过集成 ESLint、Prettier 和 Stylelint，您的项目将实现代码规范与风格的高度统一，提升开发效率和代码质量。这些工具的结合不仅能够自动检测和修复代码问题，还能确保团队协作中的一致性，减少沟通成本。随着项目的迭代，持续优化配置并遵循最佳实践，将为您的团队带来更高效的开发体验，同时为项目的长期维护打下坚实的基础。让我们以规范为基石，以工具为助力，共同打造高质量的代码！