1. 这套代码校验组合到底解决了什么问题？
在某次接手一个跨平台项目时，我打开团队仓库的第一反应是：这代码风格简直像被五个人轮流用不同口味的咖啡因写出来的——有人用单引号，有人用双引号；有人在if后面加空格，有人直接贴着括号写；<template>里标签缩进混乱，<style>里单位混用px和rem，连v-if和v-show的使用场景都经常被搞反。更头疼的是，每次git commit后 CI 流水线总在 ESLint 阶段报错，动不动就卡住整个发布流程。后来我们花了整整三天时间统一代码规范，但第二天又有人提交了带分号的代码，因为本地根本没跑校验。
这就是为什么我坚持把uni-app 配置 eslint + prettier + stylelint + lint-staged + husky这套组合落地到每一个新项目里。它不是炫技，而是给团队装上“自动刹车系统”：在代码真正进入仓库前，就拦截掉格式错误、潜在 bug 和风格冲突。你不需要记住几十条规则，也不用靠人工 Code Review 去揪缩进问题——所有检查都在你敲下git commit的瞬间完成，失败即中止，不讲情面。
这套方案特别适合 uni-app 项目，因为它的三端（H5/小程序/App）同构特性，让代码结构天然复杂：.vue文件里同时存在<script>（JS/TS）、<template>（Vue 模板语法）、<style>（CSS/SCSS/Less），每一块都需要不同工具精准覆盖。ESLint 管逻辑，Prettier 管格式，Stylelint 管样式，而 lint-staged + husky 则是它们的调度中枢——只检查本次提交改动的文件，不扫全量，不拖慢开发节奏。它不替代单元测试，也不解决架构问题，但它能让你每天少花 20 分钟在“这个分号要不要删”“那个空行该不该加”的无意义争论上。如果你是 solo 开发者，它帮你建立职业级代码习惯；如果你是团队负责人，它就是最沉默也最可靠的代码守门员。
2. 整体设计思路与工具选型逻辑
2.1 为什么不是“只用 ESLint”或“只用 Prettier”？
很多开发者第一次尝试代码校验时，会直接npm install eslint --save-dev，然后配个eslint:recommended就以为万事大吉。实测下来，这种做法在 uni-app 场景下很快就会碰壁。原因很实在：ESLint 的核心职责是代码质量与潜在错误检测，比如console.log未删除、undefined变量访问、this指向错误等。它对代码“好不好看”几乎不关心——你写if(a){b()}还是if (a) { b(); }，只要语法合法，ESLint 默认不会报错。
而 Prettier 是另一个极端：它只管格式，不管逻辑。它能把一团乱麻的 JS 自动重排成标准缩进、统一引号、合理换行，但它完全识别不了v-for中缺少key属性这种 Vue 特有风险。更关键的是，ESLint 和 Prettier 在部分规则上会打架。比如 ESLint 的semi: ["error", "always"]要求加分号，而 Prettier 的semi: false要求不加——两者共存且未协调，eslint --fix和prettier --write就会互相覆盖，越修越乱。
所以我们的设计起点很明确：分工协作，各司其职。ESLint 负责“能不能跑”，Prettier 负责“好不好看”，Stylelint 负责“美不美观”，三者通过配置桥接（如eslint-config-prettier）消除冲突，再由 lint-staged 把它们按需调用，husky 把执行时机卡死在commit前。这不是堆砌工具，而是构建一条流水线：提交 → 拦截 → 分类检查 → 自动修复 → 放行/报错。
2.2 为什么必须引入 lint-staged + husky？跳过行不行？
有人问：“我手动运行npm run lint不就行了？”——理论上可以，但实践中等于没装。我跟踪过三个不同规模的 uni-app 团队，发现手动执行的平均执行率不到 35%。原因很现实：开发者在功能开发尾声往往急于提交，觉得“就差这一行了，先 commit 再 fix”，结果那“一行”就成了永远欠下的技术债。CI 流水线虽然也能做全量检查，但代价是每次 PR 都要等 3~5 分钟跑完所有文件，反馈延迟高，修复成本陡增。
lint-staged 的价值在于精准、轻量、即时。它只读取git status中标记为staged（已git add）的文件，比如你这次只改了pages/index/index.vue和utils/request.js，它就只对这两个文件运行 ESLint/Prettier/Stylelint，跳过其他几百个未改动的文件。实测下来，一次典型提交的校验耗时从全量的 8.2 秒压缩到 1.3 秒以内，开发者几乎感觉不到卡顿。
husky 则是这条流水线的“开关阀”。它监听 Git 生命周期钩子（hook），我们重点绑定pre-commit钩子——也就是在git commit命令真正写入本地仓库前的最后一道关卡。一旦校验失败，husky 会直接中断提交，并清晰打印出哪行代码违反了哪条规则（比如Expected indentation of 2 spaces but found 4），开发者当场就能修正。没有 husky，lint-staged 就只是个摆设命令；没有 lint-staged，husky 就只能执行全量脚本，失去精准性。二者是硬绑定的搭档，缺一不可。
2.3 uni-app 的特殊性如何影响工具链配置？
uni-app 的.vue单文件组件（SFC）是这套方案的最大挑战点，也是最关键的适配环节。一个标准.vue文件包含三个逻辑区块：
<script>：可能是 JS 或 TS，需 ESLint + TypeScript 插件支持；<template>：Vue 模板语法，需eslint-plugin-vue专门解析；<style>：可能是普通 CSS、SCSS 或 Less，需 Stylelint 对应预处理器插件。
如果按普通 Vue 项目配置，会直接漏掉 uni-app 特有语法。比如uni.navigateTo、uni.getSystemInfoSync这些 API，在标准eslint-plugin-vue规则里是未知的，会导致误报。我们必须显式声明env: { 'uni-app': true }，并引入eslint-plugin-uni插件——这是由 uni-app 官方维护的规则集，专门识别uni.开头的 API、<canvas>在小程序中的特殊用法、条件编译注释/* #ifdef H5 */的合法性等。
同样，Stylelint 也不能只配stylelint-config-standard。uni-app 的样式单位在不同平台表现差异极大：H5 支持vh/vw，小程序只认rpx，App 端又偏好px。我们需要通过stylelint-scss插件约束 SCSS 变量命名，用stylelint-order强制属性排序（比如display必须在flex前），再配合自定义规则禁止在.nvue文件中使用background-image: url()（因为 nvue 不支持网络图片），这些细节才是让校验真正“贴地飞行”的关键。
3. 核心配置详解与实操步骤
3.1 初始化依赖安装（含版本锁定说明）
所有操作均在项目根目录下进行。注意：uni-app 项目通常基于 Vue 2 或 Vue 3，本方案以Vue 3 + TypeScript为基准（当前 uni-app 最新稳定版默认支持），若你的项目是 Vue 2，请在最后一步替换对应插件。
# 一次性安装全部 devDependencies npm install -D eslint@8.57.0 prettier@3.2.5 stylelint@16.10.0 \ eslint-plugin-vue@9.25.0 eslint-plugin-typescript@7.2.0 \ @typescript-eslint/eslint-plugin@6.21.0 @typescript-eslint/parser@6.21.0 \ eslint-config-prettier@9.1.0 eslint-plugin-prettier@5.1.3 \ stylelint-config-standard@35.0.0 stylelint-config-prettier@9.0.5 \ lint-staged@15.2.7 husky@8.0.3 \ eslint-plugin-uni@4.2.0提示：这里所有版本号均经过实测兼容性验证。特别注意
eslint@8.x与@typescript-eslint/parser@6.x必须严格匹配，否则会出现Parsing error: Cannot read property 'map' of undefined类型报错。Prettier 3.x 与 ESLint 8.x 的集成更稳定，避免使用 Prettier 2.x（已停止维护）。
安装完成后，立即初始化 husky：
npx husky install这会在项目根目录创建.husky/文件夹，并生成基础钩子脚本。接着，将pre-commit钩子与 lint-staged 绑定：
npx husky add .husky/pre-commit "npx lint-staged"此时.husky/pre-commit文件内容应为：
#!/usr/bin/env sh . "$(dirname -- "$0")/_/husky.sh" npx lint-staged注意：不要手动编辑此文件，必须用
npx husky add命令生成，否则 husky 无法正确加载环境变量，导致npx找不到本地安装的 lint-staged。
3.2 ESLint 全局配置（.eslintrc.cjs）
创建.eslintrc.cjs（推荐用 CommonJS 格式，兼容性最好），内容如下：
module.exports = { // 指定解析器，必须与项目语言匹配 parser: '@typescript-eslint/parser', // 解析器选项，关键：启用 Vue SFC 支持 parserOptions: { ecmaVersion: 2022, sourceType: 'module', ecmaFeatures: { jsx: true, tsx: true, legacyDecorators: true }, // 必须！让 parser 识别 .vue 文件中的 <script setup> extraFileExtensions: ['.vue'] }, // 运行环境，uni-app 专属 env: { browser: true, es2021: true, node: true, 'uni-app': true // 关键：启用 uni-app 全局变量和 API }, // 全局变量声明，避免 'uni is not defined' 报错 globals: { uni: 'readonly', plus: 'readonly', wx: 'readonly', my: 'readonly', tt: 'readonly', swan: 'readonly' }, // 插件列表，顺序很重要 plugins: [ 'vue', // Vue 基础规则 '@typescript-eslint', // TS 支持 'uni', // uni-app 专属规则 'prettier' // 将 Prettier 规则接入 ESLint ], // 继承的共享配置，按优先级从低到高 extends: [ 'eslint:recommended', // ESLint 官方推荐 'plugin:vue/vue3-essential', // Vue 3 基础规则（非强烈推荐，因 uni-app 混合模式） 'plugin:@typescript-eslint/recommended', // TS 推荐规则 'plugin:uni/recommended', // uni-app 官方推荐规则 'eslint-config-prettier', // 关闭所有与 Prettier 冲突的规则 'plugin:prettier/recommended' // 启用 Prettier 作为 ESLint 规则 ], // 自定义规则，覆盖继承配置 rules: { // 强制使用 const/let，禁用 var 'no-var': 'error', // 禁止 console（上线前必须清理） 'no-console': ['warn', { allow: ['warn', 'error'] }], // 禁止 debugger 'no-debugger': 'error', // uni-app 特有：强制使用 uni.navigateTo 而非 wx.navigateTo 'uni/no-native-api': 'error', // 模板中 v-for 必须带 key 'vue/require-v-for-key': 'error', // script setup 中 props 必须用 defineProps 声明 'vue/require-define-options': 'off', // uni-app 中 defineProps 已足够 // Prettier 规则由插件接管，此处不重复定义 'prettier/prettier': 'error' }, // 指定检查的文件类型，必须包含 .vue overrides: [ { files: ['*.ts', '*.tsx', '*.vue'], rules: { // TS 文件中允许 any 类型（仅开发期，上线前应关闭） '@typescript-eslint/no-explicit-any': 'warn' } } ] }实操心得：
'uni/no-native-api': 'error'这条规则极其重要。它能阻止开发者在 H5 环境下误用wx.request，或在微信小程序中调用my.request，避免运行时白屏。我们曾在线上环境因此类错误导致 15% 的页面加载失败，启用此规则后归零。
3.3 Prettier 配置（.prettierrc）
创建.prettierrc（JSON 格式），内容精简但覆盖 uni-app 全场景：
{ "semi": true, "singleQuote": true, "tabWidth": 2, "printWidth": 100, "trailingComma": "es5", "bracketSpacing": true, "arrowParens": "avoid", "htmlWhitespaceSensitivity": "ignore", "endOfLine": "lf", "embeddedLanguageFormatting": "auto", "vueIndentScriptAndStyle": true }关键参数说明：
"vueIndentScriptAndStyle": true：这是 uni-app 专属配置！它确保<script setup>和<style lang="scss">内部的缩进与外部模板一致，避免 Prettier 把<script>里的代码缩进多两格。"htmlWhitespaceSensitivity": "ignore"：忽略 HTML/Vue 模板中的空白符敏感性，防止 Prettier 错误折叠<view>标签间的换行，影响小程序渲染。"printWidth": 100：比默认 80 更宽，适配 uni-app 中常见的长 API 调用链（如uni.showToast({ title: '操作成功', icon: 'none', duration: 2000 })）。
3.4 Stylelint 配置（.stylelintrc.cjs）
创建.stylelintrc.cjs，专治 uni-app 样式乱象：
module.exports = { extends: [ 'stylelint-config-standard', 'stylelint-config-prettier' ], plugins: [ 'stylelint-scss', 'stylelint-order' ], rules: { // 强制使用 rpx（小程序）或 px（App/H5），禁用 rem/vh/vw 'unit-disallowed-list': ['rem', 'vh', 'vw', 'vmin', 'vmax'], // 允许的单位，按平台区分（需配合构建脚本） 'unit-allowed-list': { 'font-size': ['rpx', 'px'], 'width': ['rpx', 'px'], 'height': ['rpx', 'px'] }, // SCSS 变量必须以 $ 开头 'scss/dollar-variable-pattern': '^\\$[a-z][a-z0-9]*(-[a-z0-9]+)*$', // 属性排序：显示相关 > 盒模型 > 文本 > 背景 > 边框 > 动画 'order/order': [ 'custom-properties', 'dollar-variables', 'at-rules', 'declarations', 'rules' ], 'order/properties-alphabetical-order': true, // 禁止 !important（uni-app 中极易引发样式覆盖混乱） 'declaration-no-important': true, // 选择器最大嵌套深度为 3（防止单页样式失控） 'max-nesting-depth': 3, // 注释必须以 // 开头（SCSS 注释） 'comment-pattern': '^//' }, overrides: [ { files: ['**/*.vue'], customSyntax: 'postcss-html' }, { files: ['**/*.scss'], customSyntax: 'postcss-scss' } ] }注意事项：
'unit-disallowed-list'并非绝对禁止，而是配合 uni-app 的条件编译。例如：<style lang="scss"> /* #ifdef MP-WEIXIN */ .container { width: 750rpx; } /* #endif */ /* #ifdef H5 */ .container { width: 100vw; } /* #endif */ </style>Stylelint 会识别
#ifdef注释，对 H5 分支的vw不报错。这是 uni-app 工具链的原生能力，无需额外插件。
3.5 lint-staged 配置（lint-staged.config.cjs）
创建lint-staged.config.cjs，定义“对什么文件做什么事”：
module.exports = { // 匹配所有 .vue 文件，先跑 ESLint 再跑 Prettier '*.{vue,js,jsx,ts,tsx}': [ 'eslint --fix', 'prettier --write' ], // 匹配所有样式文件，只跑 Stylelint '*.{css,scss,sass,less,styl,stylus,html,vue}': [ 'stylelint --fix' ], // 额外保障：对 package.json 运行 sort-package-json（可选） 'package.json': ['npx sort-package-json'] }实操技巧：这里
*.{vue,js,jsx,ts,tsx}的匹配顺序很重要。必须先eslint --fix再prettier --write，因为 ESLint 的--fix会处理逻辑性修复（如补key、删console），而 Prettier 的--write专注格式重排。如果顺序颠倒，Prettier 可能先把代码格式化好，ESLint 的--fix又在末尾加个分号，导致二次格式化。
3.6 验证配置是否生效
配置完成后，务必执行三步验证：
本地手动触发：修改一个
.vue文件（比如加个空格、删个分号），然后运行：npx lint-staged观察控制台是否自动修复并输出
✔ ... fixed。若报错，根据提示定位配置文件语法错误。模拟提交流程：
git add src/pages/index/index.vue git commit -m "test: verify lint setup"此时 husky 会自动触发 lint-staged。如果一切正常，应看到类似：
✔ Preparing... ✔ Running tasks... ✔ Applying modifications... ✔ Cleaning up... [main 123abc] test: verify lint setup若失败，husky 会打印具体哪条规则被违反，比如
src/pages/index/index.vue: line 15, col 20, Error - Expected indentation of 2 spaces but found 4。IDE 集成检查：在 VS Code 中安装
ESLint、Prettier、Stylelint三个官方插件，并确保工作区设置中启用了"editor.codeActionsOnSave"："editor.codeActionsOnSave": { "source.fixAll.eslint": true, "source.fixAll.stylelint": true, "source.fixAll.prettier": true }保存
.vue文件时，应自动触发修复。这是开发者日常体验的关键——提交前的校验是兜底，编辑时的实时修复才是效率倍增器。
4. 常见问题与排查技巧实录
4.1 “ESLint 报错：Parsing error: Cannot read property 'map' of undefined”
这是版本不匹配的典型症状。常见于@typescript-eslint/parser版本高于eslint。解决方案：
- 查看当前版本：
npm list eslint @typescript-eslint/parser - 强制降级（以
eslint@8.57.0为准）：npm install -D eslint@8.57.0 @typescript-eslint/parser@6.21.0 @typescript-eslint/eslint-plugin@6.21.0 - 清理缓存并重启 IDE：
npx eslint --clear-cache
踩坑记录：某次升级
@typescript-eslint到 7.x 后，所有.vue文件的<script setup>部分全部报此错。回退到 6.21.0 后立即恢复。官方文档未明确标注此兼容性断层，必须以实测为准。
4.2 “Prettier 修复后，ESLint 又报格式错误，循环打架”
根源在于eslint-config-prettier未正确关闭冲突规则。检查.eslintrc.cjs中extends数组：
- ✅ 正确顺序：
'eslint-config-prettier'必须在'plugin:prettier/recommended'之前； - ❌ 错误顺序：若
'plugin:prettier/recommended'在前，它会先开启 Prettier 规则，后加载的'eslint-config-prettier'无法覆盖。
验证方法：运行npx eslint --print-config src/pages/index/index.vue，搜索prettier/prettier字段，确认其值为'error'（而非'off'）。若为'off'，说明eslint-config-prettier生效位置错误。
