UniApp + Vite + Vue3 + TypeScript 项目中 ESLint 与 Prettier 的完整配置指南

在现代前端开发中，写代码不仅要能跑，还要整洁、规范、安全。特别是团队开发或大型项目，如果代码风格不统一，容易出现 bug、难以维护、代码 review 也很痛苦。

ESLint 和 Prettier 是最常用的"守护代码质量"和"统一代码风格"的工具，它们可以帮助我们自动检查、规范和格式化代码。配合 Git Hooks 和 lint-staged，还能实现提交前自动美化，确保团队代码风格完全统一。

本指南包含：

🎯 ESLint 代码质量检查配置
🎨 Prettier 代码格式化配置
🚀 提交前自动美化（Git Hooks + lint-staged）
🔧 VS Code 编辑器集成配置
👥 团队协作最佳实践

一、问题：什么是代码规范工具？为什么需要它们？

想象一下，你和几个朋友一起写一篇文章，但是：

有人用逗号，有人用句号结尾
有人每段空一行，有人空两行
有人用粗体，有人用斜体

这样写出来的文章会是什么样子？乱七八糟！

写代码也是一样的道理。在团队开发中，如果没有统一的代码规范，就会出现这些问题：

1.1 📝 代码风格混乱

问题示例：

javascript 复制代码

// 开发者A写的代码
function getUserInfo(){
    const name="张三";
    const age=25;
    return {name,age}
}

// 开发者B写的代码
function getUserInfo() {
  const name = '张三';
  const age = 25;
  return { name, age };
}

// 开发者C写的代码
function getUserInfo()
{
    const name = "张三";
    const age = 25;
    return {name, age};
}

问题分析：

缩进不一致：有人用2个空格，有人用4个空格
引号不统一：有人用单引号，有人用双引号
分号随意：有的行有分号，有的行没有
括号位置不同：有人把{放在行尾，有人放在下一行

1.2 🔄 Git提交混乱

真实场景：

bash 复制代码

# 你提交代码时，Git显示的变化
+ function getUserInfo() {
+   const name = '张三';
+   const age = 25;
+   return { name, age };
+ }
- function getUserInfo(){
-     const name="张三";
-     const age=25;
-     return {name,age}
- }

问题： 看起来改了很多，其实只是格式调整，真正的业务逻辑没变！

1.3 👀 代码Review困难

Review时的痛苦：

花大量时间看格式问题，而不是业务逻辑
真正的bug被格式问题掩盖
效率低下，心情烦躁

1.4 😰 维护成本高

新人加入时，需要花时间学习项目的"格式习惯"
每个开发者都要手动调整格式
多人协作时，格式冲突不断

二、解决方案：ESLint + Prettier

简单理解：

ESLint：像是一个严格的老师，检查你的代码有没有错误和问题
Prettier：像是一个专业的排版师，帮你把代码排得整整齐齐

它们的分工：

ESLint：检查代码错误（比如变量没定义、语法错误等）
Prettier：统一代码格式（缩进、引号、分号等）

2.1 为什么要用 ESLint？

ESLint 是 JavaScript/TypeScript 代码检查工具，就像一个严格的代码审查员，在开发过程中实时检查你的代码，帮你发现潜在错误、不规范代码和性能问题。

2.1.1 ESLint 重点检测的问题类型

1. 变量声明问题

问题：使用 var 而不是 let/const

❌ 容易出错的写法：

javascript 复制代码

// 变量提升陷阱
console.log(name); // undefined（不会报错，但逻辑错误）
var name = "张三";

// 作用域泄露
for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100); // 输出 3, 3, 3
}

// 重复声明不报错
var age = 20;
var age = 25; // 不会报错，容易出错

✅ ESLint 推荐的写法：

javascript 复制代码

// 使用 let/const，更安全
console.log(name); // ReferenceError: Cannot access 'name' before initialization
const name = "张三";

// 块级作用域，正确输出
for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100); // 输出 0, 1, 2
}

// 重复声明会报错
const age = 20;
const age = 25; // SyntaxError: Identifier 'age' has already been declared

ESLint 规则： no-var - 禁止使用 var，强制使用 let/const

2. 比较操作问题

问题：使用 == 而不是 ===

为什么这是个问题？

== 会进行类型转换，容易产生意外的结果
=== 严格比较类型和值，更安全、更可预测
使用 == 是很多 bug 的根源

❌ 容易出错的写法：

javascript 复制代码

// 类型转换陷阱 - 这些结果都容易让人困惑
if (0 == false) {        // true（数字0被转换为false）
  console.log("意外执行"); // 会执行，但逻辑不清晰
}

if ("" == false) {       // true（空字符串被转换为false）
  console.log("意外执行"); // 会执行，但容易出错
}

if (null == undefined) { // true（特殊规则）
  console.log("意外执行"); // 会执行，但逻辑不明确
}

// 数组比较问题
if ([1,2,3] == "1,2,3") { // true（数组被转换为字符串）
  console.log("意外执行"); // 会执行，但容易出错
}

// 实际项目中的问题
const userInput = "0";
if (userInput == false) { // true！用户输入"0"被当作false
  console.log("用户没有输入"); // 错误！用户确实输入了"0"
}

✅ ESLint 推荐的写法：

javascript 复制代码

// 严格比较，结果更可预测
if (0 === false) {        // false（类型不同）
  console.log("不会执行");
}

if ("" === false) {       // false（类型不同）
  console.log("不会执行");
}

if (null === undefined) { // false（类型不同）
  console.log("不会执行");
}

// 明确类型转换
if (String([1,2,3]) === "1,2,3") { // true（明确意图）
  console.log("正确执行");
}

// 实际项目中的正确做法
const userInput = "0";
if (userInput === "0") { // 明确比较字符串
  console.log("用户输入了0");
} else if (userInput === "") { // 明确检查空字符串
  console.log("用户没有输入");
}

ESLint 规则： eqeqeq - 强制使用 === 和 !==

实际好处：

避免类型转换带来的 bug
代码逻辑更清晰，更容易理解
减少调试时间，提高代码质量

3. 未使用变量问题

问题：声明了变量但没有使用

为什么这是个问题？

浪费内存空间
代码冗余，影响可读性
可能是忘记使用的变量，导致功能缺失
增加代码维护成本

❌ 容易出错的写法：

javascript 复制代码

// 函数参数未使用，浪费内存
function uploadFile(file, progress, fileInfo) { // progress, fileInfo 未使用
  // 上传逻辑
  console.log('文件上传中...');
}


// 可能是忘记使用的变量
function validateForm(formData) {
  const email = formData.email;
  const password = formData.password;
  const confirmPassword = formData.confirmPassword; // 忘记验证确认密码。
  
  return email && password; // 缺少确认密码验证
}

✅ ESLint 推荐的写法：

javascript 复制代码

function processUser(userData) {
  const { name, email } = userData; // 只解构需要的属性
  
  return { name, email };
}


// 或者完全移除未使用的参数
function handleClick(event) {
  console.log('clicked');
}

// 实际项目中的正确做法
function uploadFile(file) { // 只保留需要的参数
  console.log('文件上传中...');
}

ESLint 规则： @typescript-eslint/no-unused-vars - 检测未使用的变量

实际好处：

减少内存占用
提高代码可读性
避免忘记使用重要变量
帮助发现逻辑错误

4. 重复键值问题

问题：对象中有重复的键

为什么这是个问题？

重复的键会导致后面的值覆盖前面的值
容易造成逻辑错误和数据丢失
代码维护困难，容易产生 bug

❌ 容易出错的写法：

javascript 复制代码

// Vue 组件中的重复键
export default {
  data() {
    return {
      name: '张三',
      age: 25
    };
  },
  methods: {
    onShow() {
      console.log('显示');
    },
    onHide() {
      console.log('隐藏');
    },
    onHide() { // 重复的键！会覆盖上面的方法
      console.log('另一个隐藏逻辑');
    }
  }
};

// 配置对象中的重复键
const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
  apiUrl: 'https://api.new.com', // 重复的键！会覆盖上面的值
  retries: 3
};

✅ ESLint 推荐的写法：

javascript 复制代码

// 避免重复键
export default {
  data() {
    return {
      name: '张三',
      age: 25
    };
  },
  methods: {
    onShow() {
      console.log('显示');
    },
    onHide() {
      console.log('隐藏');
    },
    onAnotherHide() { // 使用不同的方法名
      console.log('另一个隐藏逻辑');
    }
  }
};

// 配置对象避免重复
const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
  retries: 3
};

ESLint 规则： no-dupe-keys - 禁止对象字面量中出现重复的键

2.2.2 ESLint 带来的实际好处总结

通过上面的例子，我们可以看到 ESLint 不仅仅是一个代码检查工具，它更像是一个经验丰富的代码审查员，帮你：

🛡️ 预防 Bug

类型转换陷阱 ：== vs === 的问题
作用域问题 ：var vs let/const 的陷阱
异步代码错误 ：忘记 await、错误的 Promise 处理

💡 提高代码质量

减少冗余：检测未使用的变量和函数
避免重复：防止对象键重复、代码重复
规范写法：统一代码风格和最佳实践

⚡ 提升开发效率

实时反馈：写代码时立即发现问题
减少调试时间：提前发现潜在问题
团队协作：统一的代码规范，减少冲突

2.2 为什么要用 Prettier？

Prettier 是代码格式化工具，它的任务不是找 bug，而是统一代码的"长相"，就像一个专业的排版师，专门负责把代码排得整整齐齐。

统一缩进（都用2个空格）
统一引号（都用单引号）
统一分号（每行都加分号）
统一换行（长代码自动换行）
Vue 模板属性多行显示（每个属性独占一行）

2.2.1 Typescript代码没格式示例：

格式化前：代码挤在一行，很难读。

ts 复制代码

const user={name:"Tom",age:20}

Prettier 格式化后：

ts 复制代码

const user = { name: "Tom", age: 20 }

2.2.2 Vue 模板多行格式化示例：

1、格式化前：

html 复制代码

<view class="uni-im-chat-input" :style="{ height: chatInputBoxHeight }" style="
    padding-bottom: constant(safe-area-inset-bottom);
    padding-bottom: env(safe-area-inset-bottom);
    background-color: #ffffff;
  " :class="{ 'theme-backgroundColor': themeColorMode == 'dark' }">
  ...
</view>

(1) 优点：

部分属性挤在一行，层级缩进稍紧凑。

(2) 缺点：

属性多时容易看花眼，尤其是动态绑定和内联样式混合；
改动属性时可能引入拼写错误或格式问题；

2、格式化后：

html 复制代码

<view
  class="uni-im-chat-input"
  :style="{ height: chatInputBoxHeight }"
  style="
    padding-bottom: constant(safe-area-inset-bottom);
    padding-bottom: env(safe-area-inset-bottom);
    background-color: #ffffff;
  "
  :class="{ 'theme-backgroundColor': themeColorMode == 'dark' }"
>
  ...
</view>

每个属性独立一行，长属性、动态绑定都很清晰，层级一目了然
新增/删除属性更安全，Git diff 更清楚

2.2.3 长函数调用格式化示例

1、格式化前： 参数太多，一行放不下

javascript 复制代码

const result = await fetchData(userId, startDate, endDate, { includeDeleted: false, sortBy: 'createdAt', sortOrder: 'desc', limit: 100, offset: 0 });

2、格式化后： 参数分行，清晰易读

javascript 复制代码

const result = await fetchData(
  userId,
  startDate,
  endDate,
  {
    includeDeleted: false,
    sortBy: 'createdAt',
    sortOrder: 'desc',
    limit: 100,
    offset: 0,
  }
);

2.2.4 条件语句和循环格式化示例

1、格式化前： 嵌套复杂，难以理解

javascript 复制代码

if(user.isActive&&user.hasPermission&&user.subscription.status==='active'&&user.subscription.expiresAt>new Date()){if(user.preferences.notifications){sendNotification('Welcome to premium!');}}

2、格式化后： 逻辑清晰，易于维护

javascript 复制代码

if (
  user.isActive &&
  user.hasPermission &&
  user.subscription.status === 'active' &&
  user.subscription.expiresAt > new Date()
) {
  if (user.preferences.notifications) {
    sendNotification('Welcome to premium!');
  }
}

总结：

统一缩进、空格、分号、引号、尾逗号等，避免团队成员格式不同。
避免因为格式问题引起的代码 review 争论。
换行和缩进是 HTML/Vue 属性的"边界感"，Vue 模板属性自动多行显示，提高代码可读性。

2.3 ESLint 与 Prettier 的区别

工具	作用	关注点
ESLint	检查错误、代码规范	语法错误、潜在 bug、最佳实践
Prettier	格式化代码	缩进、引号、尾逗号、空格等风格

小结：ESLint 保证"代码没问题"，Prettier 保证"代码好看"。

三、完整配置步骤

3.1 ESLint 安装与配置

ESLint 是一个用于识别和报告在 ECMAScript/JavaScript 代码中发现的模式的工具，其目标是使代码更加一致并避免错误。

ESLint 中文网

3.1.1 初始化

按照ESLint官网的步骤，第一步初始化eslint，在你的项目根目录执行以下命令：

bash 复制代码

npm init @eslint/config@latest

3.1.2 安装与配置

按照提示,选择你需要的配置,完成所有步骤后，项目下会自动生成eslint的配置文件,安装需要的依赖包。

推荐使用简洁的现代配置方式，避免复杂的兼容性处理，让配置更易理解和维护。

配置特点：

✅ 简洁明了，易于理解
✅ 包含常用规则，提高代码质量
✅ 支持 Vue 和 TypeScript
✅ 自动修复功能完善

typescript 复制代码

//eslint.config.mts
// 导入需要的工具
import js from '@eslint/js'; //ESLint核心包
import globals from 'globals';//全局变量支持（让ESLint认识一些特殊变量）
import tseslint from 'typescript-eslint';//让ESLint能检查TypeScript代码
import pluginVue from 'eslint-plugin-vue';//让ESLint能检查Vue文件
import { defineConfig } from 'eslint/config';

// 导出配置（告诉ESLint怎么检查代码）
export default defineConfig([
  {
    // 检查哪些文件
    files: ['**/*.{js,mjs,cjs,ts,mts,cts,vue}'],
    plugins: { js },
    extends: ['js/recommended'],
    
    //全局变量配置（告诉ESLint认识这些变量）
    //没有配置：ESLint会报错"uni未定义"
    languageOptions: { 
      globals: { 
        ...globals.browser,    // 浏览器环境变量（如window、document）
        ...globals.node,       // Node.js环境变量（如process、require）
        uni: "writable"        // UniApp全局变量（如uni.request）
      } 
    },
    rules: {
      // 禁止使用 var，强制使用 let 或 const
      'no-var': 'error',
      // 要求使用 === 和 !==，禁止使用 == 和 !=
      eqeqeq: ['error', 'always'],
      // 禁止未使用的变量，提高代码质量
      'no-unused-vars': 'warn',
    },
  },
  // TypeScript检查规则
  tseslint.configs.recommended,
  // Vue文件检查规则
  pluginVue.configs['flat/essential'],
  // Vue文件特殊处理
  { 
    files: ['**/*.vue'], 
    languageOptions: { 
      parserOptions: { parser: tseslint.parser } 
    } 
  }
]);

3.1.3 添加.eslintignore忽略文件

告诉ESLint不检查这些文件：

复制代码

# 忽略 node_modules
node_modules/

# 忽略打包输出目录
dist/
build/
dev-dist/

# 忽略缓存和临时文件
.cache/
.temp/
.tmp/
*.log
*.pid
*.seed
*.pid.lock

# 忽略特定文件或文件夹
src/assets/**/*.js
src/static/**/*.js

# 忽略 uni_modules (第三方组件库)
src/uni_modules/

# 忽略自动生成的文件
components.d.ts
auto-imports.d.ts
auto-components.d.ts

# 忽略证书和密钥文件
cert/
*.pem
*.key
*.crt

# 忽略文档和说明文件
*.md
!README.md

# 忽略测试和配置文件
test.ts
preview.js
vite.config.ts

3.1.4 Vscode安装ESLint插件

要让vscode通过eslint检查代码，还得在vscode中安装eslint插件。

完成这步后，最好是重启下vscode，不出意外这个时候，你代码中如果有语法错误的地方，应该就会爆红了。

3.1.5 在 package.json 中添加 Eslint 脚本

打开 package.json 文件，找到 "scripts" 部分，添加以下内容：

json 复制代码

{
  "scripts": {
    "lint:eslint": "eslint --cache --max-warnings 0 \"{src,mock}/**/*.{vue,ts,tsx}\" --fix",
    "lint:eslint:check": "eslint --cache --max-warnings 0 \"{src,mock}/**/*.{vue,ts,tsx}\""
  }
}

命令说明：

lint:eslint：检查代码并自动修复问题
lint:eslint:check：只检查代码，不自动修复

使用方法：

bash 复制代码

# 检查并修复代码
npm run lint:eslint

# 只检查代码（不修复）
npm run lint:eslint:check

3.2 Prettier 安装与配置

Prettier 是一个代码格式化程序：

Prettier中文官网

3.2.1 初始化

bash 复制代码

npm install --save-dev --save-exact prettier

3.2.2 配置

创建一个空的配置文件，让编辑器和其他工具知道你正在使用 Prettier：

bash 复制代码

node --eval "fs.writeFileSync('prettier.config.mjs','export default{}\n')"

在prettier.config.mjs配置文件中添加如下内容：

关键配置说明：

vueIndentScriptAndStyle: false - 避免 script/style 标签前的不必要缩进
singleAttributePerLine: true - Vue 模板每个属性独占一行
bracketSameLine: false - 标签的 > 符号不放在同一行
overrides - 确保 Vue 文件被正确处理

javascript 复制代码

export default {
  printWidth: 100,              // 每行最大字符数，100 更适合现代屏幕和 TS 类型较长的情况
  tabWidth: 2,                  // 缩进空格数
  useTabs: false,               // 使用空格而不是Tab
  semi: true,                   // 句末加分号
  singleQuote: true,            // 使用单引号
  trailingComma: "es5",         // 多行对象、数组、函数参数允许尾逗号
  bracketSpacing: true,         // 对象字面量的大括号内部加空格
  arrowParens: "always",        // 单参数箭头函数也加括号
  endOfLine: "lf",              // 换行符统一使用 LF
  vueIndentScriptAndStyle: false,// Vue <script>/<style> 标签前不添加缩进
  insertPragma: false,          // 不在文件头自动插入 @prettier
  quoteProps: "as-needed",      // 对象属性加引号仅在必要时
  htmlWhitespaceSensitivity: "css", // HTML 空格敏感性，"css" 保持和浏览器一致
  proseWrap: "preserve",        // Markdown 文本换行保留原样
  embeddedLanguageFormatting: "auto", // 自动格式化嵌入语言，如 HTML 中的 CSS/JS

  // Vue 模板换行控制
  singleAttributePerLine: true,    // 每个属性独占一行
  bracketSameLine: false,          // 标签的 > 符号不放在同一行
  
  // 确保 Vue 文件被正确处理
  overrides: [
    {
      files: "*.vue",
      options: {
        parser: "vue",
        singleAttributePerLine: true,
        bracketSameLine: false,
      },
    },
  ],
};

3.2.3 添加.prettierignore忽略文件

复制代码

# 依赖目录
node_modules/

# 构建输出目录
dist/
build/
dev-dist/

# 证书目录
cert/

# 静态资源目录（通常不需要格式化）
public/
src/static/

# 第三方模块和插件
src/uni_modules/
vendor/

# 配置文件（通常有特定格式要求）
*.config.js
*.config.ts
*.config.mjs
*.config.cjs
*.min.js
*.min.css

# 锁文件和包管理文件
package-lock.json
yarn.lock
pnpm-lock.yaml
*.lock

# 文档和说明文件
*.md
README.md
CHANGELOG.md

# 日志文件
*.log
logs/

# 临时文件和缓存
.temp/
.tmp/
.cache/
.DS_Store
Thumbs.db

# 内存数据目录
memory-data/

# 性能分析文件
bundle-stats.html
stats.html

# 备份文件
*.backup
*.bak

# 环境变量文件
.env
.env.local
.env.development
.env.production

# IDE 配置文件
.vscode/
.idea/

# 系统文件
.DS_Store
Thumbs.db

3.2.4 在 package.json 中添加 Prettier 脚本

在你的 package.json 文件中添加一个脚本来运行 Prettier：

json 复制代码

{
  "scripts": {
    "format": "prettier --write .",
    "format:check": "prettier --check ."
  }
}

命令说明：

format：美化所有代码文件
format:check：只检查代码格式，不美化

使用方法：

bash 复制代码

# 美化所有代码
npm run format

# 只检查格式（不美化）
npm run format:check

3.2.5 Vscode安装 Prettier - Code formatter 插件

3.2.6 配置VSCode（让编辑器自动工作）

在项目根目录创建 .vscode 文件夹
在 .vscode 文件夹中创建 settings.json 文件
复制以下内容到文件中：

json 复制代码

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  // 当保存的时候，eslint自动帮我们修复错误
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  // Vue 文件特定设置
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
  },
  // 确保 Prettier 处理 Vue 文件
  "prettier.documentSelectors": ["**/*.vue"],
  // 禁用 ESLint 对 Vue 模板的格式化，让 Prettier 处理
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

配置说明:

"editor.formatOnSave": true
- 保存文件时自动美化代码
"source.fixAll.eslint": "explicit"
- 保存时自动修复ESLint问题
"editor.defaultFormatter": "esbenp.prettier-vscode"
- 默认使用Prettier来美化代码
"[vue]": {...}
- Vue 文件特定设置，确保使用 Prettier 格式化
"prettier.documentSelectors": ["**/*.vue"]
- 确保 Prettier 处理 Vue 文件
"eslint.validate": [...]
- 限制 ESLint 作用范围，避免与 Prettier 冲突

四、解决 ESLint 和 Prettier 的冲突

4.1 为什么会有冲突？

问题： ESLint和Prettier都想管代码格式，但规则可能不一样

冲突示例：

javascript 复制代码

// ESLint说：要用单引号
// Prettier说：要用双引号
const message = "Hello World"; // 到底听谁的？😵

结果： 两个工具互相"打架"，代码格式乱套

4.2 解决方案（让它们分工合作）

解决思路： 让它们各管各的，不要重复

具体做法： 使用分离配置方式

ESLint：只负责代码质量检查（错误、未使用变量、语法问题等）
Prettier：只负责代码格式化（缩进、引号、分号、Vue 模板多行等）
VS Code 设置：确保两个工具各司其职，不会冲突

无需安装额外插件，使用现代配置方式即可。

配置方式：

ESLint 配置（eslint.config.mts）：

typescript 复制代码

export default defineConfig([
  {
    files: ['**/*.{js,mjs,cjs,ts,mts,cts,vue}'],
    plugins: { js },
    extends: ['js/recommended'],
    rules: {
      'no-var': 'error',           // 禁止使用 var
      eqeqeq: ['error', 'always'], // 强制使用 ===
      'no-unused-vars': 'warn',    // 警告未使用变量
    },
    // ... 其他配置
  },
  // ... 其他规则
]);

VS Code 配置（.vscode/settings.json）：

json 复制代码

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

注意： 使用分离配置方式，ESLint 和 Prettier 各司其职，通过 VS Code 设置协调工作。

4.3 分工明确

ESLint的职责：

检查代码错误（变量未定义、语法错误等）
检查代码质量（未使用的变量、类型错误等）

Prettier的职责：

统一代码格式（缩进、引号、分号等）
美化代码外观

🎯 重点理解：

注意: 不要在 eslint 配置文件中加上代码风格相关的配置，这样可能又会跟 prettier 冲突。让 eslint 检查代码错误，让 prettier 格式化。所以要改变代码风格，请到 prettier 中修改。

五、提交前自动美化（Git Hooks + lint-staged）

5.1 为什么需要提交前自动美化？

问题场景：

开发者忘记手动格式化代码就提交了
团队成员代码风格不一致
每次都要手动运行 npm run format 很麻烦
Git 提交历史中充满了格式化的提交记录

解决方案： 使用 Git Hooks + lint-staged 实现提交前自动美化

5.2 安装和配置 lint-staged

5.2.1 安装依赖

bash 复制代码

npm install --save-dev lint-staged

5.2.2 配置 lint-staged

在 package.json 中添加 lint-staged 配置：

json 复制代码

{
  "lint-staged": {
    "*.{vue,ts,js}": [
      "prettier --write"
    ],
    "*.{json,md,scss,css}": [
      "prettier --write"
    ]
  }
}

配置说明：

*.{vue,ts,js}：对 Vue、TypeScript、JavaScript 文件运行 Prettier
*.{json,md,scss,css}：对 JSON、Markdown、SCSS、CSS 文件运行 Prettier
--write：直接修改文件，而不是只检查

5.2.3 配置 Git Hooks

推荐使用 Husky，它是管理 Git Hooks 的最佳工具，让配置更简单、更可靠。

5.2.3.1 安装和初始化 Husky

bash 复制代码

# 安装 Husky
npm install --save-dev husky

# 初始化 Husky（创建 .husky 文件夹）
npx husky init

初始化后的项目结构：

复制代码

my-project/
├── .husky/
│   ├── _/
│   └── pre-commit          # 自动创建的示例文件
├── package.json
└── ...

5.2.3.2 配置 pre-commit 钩子

编辑 .husky/pre-commit 文件：

bash 复制代码

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

npx lint-staged

文件说明：

#!/usr/bin/env sh：指定使用 shell 解释器
. "$(dirname -- "$0")/_/husky.sh"：加载 Husky 环境
npx lint-staged：运行 lint-staged 命令

5.2.3.4 其他常用 Husky 钩子

commit-msg 钩子（验证提交信息）：

bash 复制代码

# 创建 commit-msg 钩子
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

pre-push 钩子（推送前检查）：

bash 复制代码

# 创建 pre-push 钩子
npx husky add .husky/pre-push 'npm run lint:eslint:check'

5.2.3.5 手动创建 Git Hook（不推荐）

如果没有使用 Husky，可以手动创建：

bash 复制代码

# 创建 pre-commit 钩子
echo 'npx lint-staged' > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

手动方式的缺点：

❌ 不会自动同步到团队成员
❌ 容易忘记配置
❌ 维护困难

5.3 工作原理

完整的工作流程：

你执行 git commit
pre-commit 钩子触发 → 运行 npx lint-staged
lint-staged 自动处理 ：
- 备份当前状态到 git stash
- 隐藏未暂存的更改
- 对暂存的文件运行格式化工具（Prettier）
- 自动将格式化后的文件重新添加到暂存区
- 恢复未暂存的更改
- 清理临时文件
继续提交流程

5.4 实际效果演示

提交前的代码：

javascript 复制代码

// 格式混乱的代码
const user={name:"Tom",age:20,items:[1,2,3,4,5]};
function testFunction(  param1,param2  ){
  console.log("test",param1,param2);
  return param1+param2;
}
testFunction( 1,2 );

执行 git commit 后，代码自动变成：

javascript 复制代码

// 自动美化后的代码
const user = { name: 'Tom', age: 20, items: [1, 2, 3, 4, 5] };
function testFunction(param1, param2) {
  console.log('test', param1, param2);
  return param1 + param2;
}
testFunction(1, 2);

5.5 关键特性

✅ 自动格式化：运行 Prettier 美化代码
✅ 自动 git add：格式化后的文件自动重新暂存
✅ 状态保护：未暂存的更改不会丢失
✅ 透明操作：你不需要手动执行任何额外命令

5.6 使用方法

现在你只需要：

bash 复制代码

git add .
git commit -m "你的提交信息"

系统会自动：

美化所有暂存的文件
将美化后的文件重新暂存
完成提交

你完全不需要手动执行 git add 来重新暂存格式化后的文件！ 🎉

5.7 高级配置（可选）

如果你想要更精细的控制，可以这样配置：

json 复制代码

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

注意： 如果同时使用 ESLint 和 Prettier，建议先运行 ESLint 修复，再运行 Prettier 格式化。

5.8 与保存时自动美化的关系

问题： 既然已经配置了保存时自动美化，为什么还需要提交前自动美化？

答案： 两者是互补关系，不是重复配置：

保存时自动美化（编辑器级别）：

实时反馈，开发体验好
依赖编辑器配置
团队成员可能使用不同编辑器

提交前自动美化（Git 级别）：

不依赖编辑器，100% 保证
团队统一，新成员无需配置
作为最后一道防线

六、最终效果

6.1 项目结构（配置完成后的样子）

复制代码

my-vue3-project/              # 你的项目文件夹
├── .vscode/                  # VSCode配置文件夹
│   └── settings.json         # VSCode设置
├── .husky/                   # Git Hooks配置文件夹
│   └── pre-commit            # 提交前钩子
├── src/                      # 源代码文件夹
├── .eslintignore             # ESLint忽略文件
├── .prettierignore           # Prettier忽略文件
├── eslint.config.mts         # ESLint配置文件
├── prettier.config.mjs       # Prettier配置文件
├── package.json              # 项目配置文件（包含lint-staged配置）
└── vite.config.ts            # 构建工具配置

6.2 配置后的好处

通过合理配置ESLint和Prettier，你可以获得：

🎨 统一代码风格：团队成员代码风格完全一致
⚡ 提高开发效率：自动格式化，减少手动调整
🔄 减少Git冲突：格式统一，减少不必要的冲突
🐛 提升代码质量：ESLint检查潜在问题
👀 简化Code Review：专注于业务逻辑，而非格式问题
🚀 提交前自动美化：无需手动格式化，提交时自动处理
💾 自动git add：格式化后的文件自动重新暂存
🛡️ 状态保护：未暂存的更改不会丢失

6.3 记住这些要点

ESLint：负责检查代码错误和质量问题
Prettier：负责统一代码格式和美化
lint-staged：负责提交前自动美化和重新暂存
三者配合：各司其职，和谐共存
配置一次：团队受益，长期使用
透明操作：开发者无需关心格式化过程

总结

ESLint、Prettier 和 lint-staged 是现代前端开发不可或缺的工具。通过合理配置，它们能够：

确保代码质量和一致性
提高团队协作效率
减少代码审查时间
降低维护成本
实现提交前自动美化
自动处理格式化后的文件暂存

配置完成后，你的代码将变得更加规范、美观和易于维护。记住，好的工具配置是高效开发的基础！

常见问题解决

问题1：Vue 模板属性没有多行显示

原因： 缺少 singleAttributePerLine: true 配置
解决： 在 prettier.config.mjs 中添加该配置

问题2：script/style 标签前有不必要的缩进

原因： vueIndentScriptAndStyle: true 设置错误
解决： 设置为 false

问题3：保存时没有自动格式化

原因： VS Code 设置不完整
解决： 确保添加了 [vue] 特定配置和 prettier.documentSelectors

问题4：ESLint 和 Prettier 冲突

原因： ESLint 和 Prettier 都想管理代码格式
解决： 使用分离配置，ESLint 负责代码质量，Prettier 负责代码格式

问题5：配置过于复杂

原因： 使用了过时的兼容性配置方式
解决： 使用现代的 Flat Config 格式，直接配置，无需复杂的兼容性处理

问题6：提交时没有自动格式化

原因： 缺少 lint-staged 配置或 Git Hooks 配置
解决：

安装 lint-staged：npm install --save-dev lint-staged
在 package.json 中添加 lint-staged 配置
配置 pre-commit 钩子：npx lint-staged

问题7：格式化后的文件没有自动暂存

原因： 这是 lint-staged 的正常行为
解决： lint-staged 会自动处理，无需手动 git add

问题8：提交时出现格式化冲突

原因： 团队成员配置不一致
解决： 确保所有团队成员使用相同的配置文件

推荐配置特点：

✅ 简洁明了，易于理解
✅ 现代配置方式，稳定可靠
✅ 功能完整，支持所有必要特性
✅ 维护成本低，团队协作友好
✅ 包含常用规则，自动检测代码问题
✅ 支持自动修复，提高开发效率
✅ 提交前自动美化，无需手动操作
✅ 自动处理文件暂存，透明化操作

核心规则说明：

no-var: 'error' - 禁止使用 var，强制使用 let/const
eqeqeq: ['error', 'always'] - 强制使用 === 和 !==
no-unused-vars: 'warn' - 警告未使用的变量