最近有朋友问我HBuilderX 里写代码每次都要手动整理格式太烦了能不能像 VS Code 那样一按保存就自动格式化顺便把 ESLint 的报错也顺手修掉。这问题我太有感触了早年做 uni-app 项目代码风格靠手调提交到仓库后 diff 里全是缩进和引号的改动代码评审的人看两行就崩溃。后来我把 Prettier 和 ESLint 这套组合完整搬进 HBuilderX才算是真正解决问题。这篇文章就专门聊聊在 HBuilderX 里怎样把 Prettier 和 ESLint 配好实现保存自动格式化并且尽量不踩我踩过的那些坑。内容同时覆盖 HBuilderX 和 HBuilderX 3.x 的常见配置方式做 uni-app、H5 项目的同学都可以直接参考。1. 为什么非要折腾 Prettier 和 ESLint而不是用内置格式化1.1 内置格式化到底差在哪HBuilderX 本身是有格式化功能的菜单里就有“格式化代码”的选项普通场景下 CtrlK 一下也能用。但用过一段时间你就会发现它的格式化和 Prettier 这种专业工具相比差的不是一点半点。内置格式化默认按 HBuilderX 自己的风格来双引号、分号、缩进宽度这些跟团队规范不一定兼容而且它对 Vue 单文件组件里 template、script、style 三块的处理能力有限经常格式化完 script 块template 里却没动或者把已经排好的结构搞乱了。更重要的问题是内置格式化只处理“长什么样”它不关心“代码有没有问题”。你在 HBuilderX 里按了格式化只是把换行和空格理顺但变量未使用、console 残留、隐式类型转换这些 ESLint 能发现的问题它一概不管。团队协作的时候光好看没用还得有人盯着规范。这时候就需要把 ESLint 拉进来用它做代码质量检查用 Prettier 做风格统一两者配合才能既好看又规范。1.2 Prettier 和 ESLint 的正确分工很多刚接触这两样东西的人容易弄混Prettier 是格式化工具ESLint 是代码检查工具它们应用场景有重合但定位完全不同。Prettier 的核心是“固执己见的代码格式化器”你不需要告诉它代码应该怎样才好看它有一套内置规则输出结果几乎不给你太多选择空间。它的好处是团队所有人格式化出来都是一模一样的彻底终结“这段代码应该 2 空格还是 4 空格”这种无意义争论。ESLint 的核心是“代码质量检测器”它能检查出潜在的 bug、未使用的变量、危险的语法还支持各种规则配置比如强制使用单引号、不允许 console 输出等。从某个角度看ESLint 也能做格式化比如 quotes 规则可以自动把双引号改成单引号indent 规则可以调整缩进但它的强项不在样式上它的强项是发现问题format 只是附带的修整能力。所以正确的用法是Prettier 负责所有跟“外观”有关的事情ESLint 负责所有跟“质量”有关的事情两者通过 eslint-plugin-prettier 和 eslint-config-prettier 打通。前者让你在 ESLint 运行时也能跑 Prettier 规则后者把 ESLint 里跟格式化冲突的规则全部关掉避免两家打架。这个组合选型的逻辑说白了就是让专业的工具干专业的事别让一个工具大包大揽最后的体验反而最顺。1.3 这套方案适合谁如果你正在用 HBuilderX 开发 uni-app、H5 项目或者团队里有人在用 HBuilderX 而其他人用 VS Code那这套配置几乎是刚需。因为 HBuilderX 和 VS Code 底层虽然都是基于类似 Electron 的技术在做编辑器但插件生态和配置方式并不完全一致直接拿 VS Code 的配置往 HBuilderX 里塞是行不通的。把 Prettier 和 ESLint 统一配置到项目目录里不管谁用什么编辑器打开这个项目拿到的格式化结果都一致。另外如果你已经受够了每次手动 CtrlK 格式化、提交代码前还要自己检查一遍有没有把 console.log 带到生产环境那这篇内容也能帮到你。我会尽量把配置步骤拆细连依赖怎么装、配置文件写在哪、保存自动格式化为什么不生效这类细节都讲清楚。2. 开工前的准备工作环境、目录与依赖安装2.1 确认本地环境在 HBuilderX 里配置 Prettier 和 ESLint虽然不要求你必须精通 Node.js但 Node 环境是绕不开的。因为 Prettier 和 ESLint 都是基于 Node 的命令行工具你要在项目中通过 npm 安装和调用它们。一般建议 Node 版本不要低于 14如果你是新建的 uni-app 项目用 16 或 18 都比较稳。你可以先打开终端输入 node -v 和 npm -v 看一下版本号。如果没有安装 Node去 Node 官网下载 LTS 版本安装就行装完以后记得重新打开 HBuilderX让编辑器能识别到最新的环境变量。这个细节经常有人忽略Node 装好了HBuilderX 却还是提示找不到 npm就是因为 HBuilderX 是在安装 Node 之前启动的环境变量没刷新。重启一下 HBuilderX 或者重启电脑问题基本就解决了。2.2 项目目录里的配置文件应该放哪经常有人在 uni-app 项目里找不到该把 Prettier 和 ESLint 的配置文件放哪这其实要看你的项目结构。以 HBuilderX 新建的 uni-app 项目来说根目录下会有 pages、static、uni.scss、main.js、App.vue、manifest.json 这些内容配置文件就放在根目录和 package.json 平级。注意不是放在 src 目录里面除非你的项目结构是 src 模式否则根目录就是唯一正确的位置。如果你用的 HBuilderX 3.x 创建的项目默认不会自动生成 package.json这点和 VS Code 里用脚手架创建项目不太一样。所以你要么在 HBuilderX 里右键项目根目录选择“使用命令行窗口打开所在目录”之类的入口然后执行 npm init -y 快速生成一个 package.json要么手动新建一个。别小看这一步没有 package.json后面所有依赖都没法管理。2.3 安装依赖prettier、eslint 组合套装打开终端切到项目根目录先初始化 package.json再安装依赖。如果你用的是 npm命令大概是这样的npm init -y npm install --save-dev prettier eslint eslint-plugin-prettier eslint-config-prettier这里我把依赖选型解释一下。prettier 是格式化核心eslint 是代码检查核心eslint-plugin-prettier 的作用是让 ESLint 在检查代码时能把 Prettier 当作一条规则来运行这样你跑 ESLint --fix 的时候Prettier 的格式化效果也会被带出来eslint-config-prettier 的作用是关闭 ESLint 里跟 Prettier 冲突的格式相关规则。这四个装完基本配置就够用了。如果你的项目是 Vue 3 语法可能还需要配合 vue/eslint-config-prettier 或者 eslint-plugin-vue但 uni-app 项目常用的是 Vue 2 和 Vue 3 混合的情况先不着急加太多插件核心四件套搞定保存自动格式化已经足够后面有 Vue 模板解析需求再按需扩展。2.4 使用 pnpm 或 yarn 时的小差异有些同学习惯用 pnpm 或者 yarn安装命令上就是把 npm 换成 pnpm 或 yarn这没什么好说的。但有个坑要注意用 pnpm 安装 eslint-plugin-prettier 时如果项目里预处理依赖有问题可能会出现找不到模块的情况这时候删掉 node_modules 和 lock 文件重新安装就好。另外HBuilderX 内置的终端对新版本 pnpm 的支持有时候有点迷如果跑命令报错建议优先用系统终端在项目根目录操作不要迷信 HBuilderX 内置终端。3. 编写 Prettier 和 ESLint 的核心配置3.1 Prettier 配置一份可复用的 .prettierrc在项目根目录新建一个文件命名为 .prettierrc注意文件名前面有个点不要写成 prettierrc.js 或者其他名字虽然 Prettier 支持多种配置文件名但用 .prettierrc 最省事HBuilderX 和命令行工具都能自动识别。内容我建议先用这一份{ printWidth: 100, tabWidth: 2, useTabs: false, semi: false, singleQuote: true, quoteProps: as-needed, trailingComma: none, bracketSpacing: true, arrowParens: avoid, htmlWhitespaceSensitivity: ignore, vueIndentScriptAndStyle: false, endOfLine: auto }每项的含义我简单解释一下方便你根据团队规范调整。printWidth 是单行最大长度超过就换行uni-app 项目里经常有很长的 API 调用链我习惯设成 100避免换行太频繁。tabWidth 是缩进宽度uni-app 官方模板是 2 空格et 就保持 2。useTabs 设置是否用 Tab 缩进统一 false因为不同环境 Tab 渲染宽度不一样容易造成对齐混乱。semi 是否加分号false 是不要分号前端圈子现在挺流行无分号风格但如果你们团队习惯加分号改成 true 就行。singleQuote 是单引号还是双引号我默认 true使用单引号。trailingComma 设置为 none表示对象和数组最后一项后面不加逗号。arrowParens 设为 avoid意思是箭头函数只有一个参数时不加括号比如写 x x 而不是 (x) x。htmlWhitespaceSensitivity 比较关键它影响 Vue 模板里空格的处理设为 ignore 以后Prettier 不会因为模板里的换行和空格而调整得太激进对于 uni-app 的小程序模板很重要。endOfLine 设为 auto让 Prettier 根据当前操作系统的换行符来处理避免在 Windows 上生成 CRLF到了 Mac 上又变成 LF导致整个文件都被判为修改。这些配置写完后最好再建一个 .prettierignore 文件用来告诉 Prettier 哪些文件不用格式化。一般我这样写node_modules dist unpackage .hbuilderx *.min.jsunpackage 目录是 HBuilderX 打包和运行时的产物目录里面文件都是生成出来的格式化没有意义必须排除。3.2 ESLint 配置面向 uni-app 项目的 .eslintrc.js新建 .eslintrc.js这是 ESLint 的配置文件。因为 uni-app 项目经常同时包含普通 JavaScript 和 Vue 单文件组件我会先给一份精简够用的版本再说明它做了什么。module.exports { root: true, env: { browser: true, node: true, es6: true }, parserOptions: { ecmaVersion: 2020, sourceType: module }, extends: [ eslint:recommended, plugin:prettier/recommended ], plugins: [prettier], rules: { prettier/prettier: error, no-console: process.env.NODE_ENV production ? warn : off, no-debugger: process.env.NODE_ENV production ? warn : off } }这里的关键是 extends 里的 plugin:prettier/recommended。这一行干了三件事把 Prettier 规则作为 ESLint 规则开启把 prettier 注册到 plugins并且引入 eslint-config-prettier关掉所有跟 Prettier 冲突的 ESLint 格式规则。你不需要手动写一堆 quotes、semi、indent 规则只要用了这个 recommended 配置ESLint 在做 --fix 时就会自动把代码改成 Prettier 想要的格式。root 设为 true 很重要表示 ESLint 检查到这个文件就不再向上查找父级目录的配置了。如果你把项目放在某个大目录下面大目录里碰巧有一份 ESLint 配置没有 root: true 的话就不会正确合并经常导致本地不报错、编译时突然冒出一堆错误。no-console 和 no-debugger 是项目里比较实用的规则。开发环境允许 console 和 debugger但生产环境报警告提醒你别把调试语句带到线上。如果你希望更严格可以把 warn 改成 error这样提交代码前不处理掉就过不了检查。如果你在项目里用到了 uni-app 的全局 API比如 uni.request、uni.navigateToESLint 可能会报 no-undef 错误。解决办法两个一是在文件顶部加注释 /* global uni */二是把 uni 加到 globals 配置里。我建议在 env 下面加一个 globals 配置globals: { uni: readonly, getApp: readonly, getCurrentPages: readonly }3.3 ESLint 规则的插件扩展什么时候需要 eslint-plugin-vue如果你的项目里 Vue 文件比较多并且希望 ESLint 能检查 template 部分那就得额外安装 eslint-plugin-vue。安装命令npm install --save-dev eslint-plugin-vue然后在 .eslintrc.js 的 extends 里加上 plugin:vue/recommended。不过要注意plugin:vue/recommended 对 Vue 文件的格式要求比我上面写的 Prettier 风格要严格模板缩进、属性换行这些都会有要求。如果你只想简单做保存自动格式化建议先不加 eslint-plugin-vue等 Prettier 和 ESLint 的配合稳定了再逐步补充 Vue 规则。因为一旦加了它报错量会明显增加新手容易不知道先改哪个体验会比较崩溃。3.4 配置里的常见坑缩进冲突与重复修复我见过不少人配置完以后保存一次文件变成 2 空格再保存一次又变成 4 空格来回拉扯。这多半是 ESLint 里的 indent 规则和 Prettier 的 tabWidth 设置不一致导致的。使用 eslint-config-prettier 后这种冲突本来应该自动消除但如果你再手动在 rules 里添加了 indent、quotes 之类的规则它们又会重新被启用和 Prettier 打架。所以记住一条原则ESLint 的 rules 里不要手动配置任何跟格式相关的规则交给 Prettier 就好。还有一个小细节eslint-plugin-prettier 运行时会把 Prettier 当成规则执行这意味着你保存自动格式化时如果有 eslint --fix 的流程它也会触发 Prettier。反之如果只用 Prettier 做格式化但 ESLint 的规则没有同步那格式化完依然会报 prettier/prettier 错误。常见的做法是把 eslint --fix 作为保存时的触发器这样一步到位。4. 在 HBuilderX 里实现保存自动格式化4.1 HBuilderX 的插件机制与 vs code 插件差异先明确一点HBuilderX 不是 VS Code虽然界面有几分相似但插件生态不是完全相通的。HBuilderX 有自己独立的插件市场里面有一些官方和第三方插件比如 eslint 插件、prettier 插件但数量和质量跟 VS Code 没法比。有些人直接把 VS Code 的 .vscode/settings.json 拿过来放在 HBuilderX 项目里发现保存自动格式化并没有生效就是这个原因。HBuilderX 官方插件市场里确实存在 ESLint 和 Prettier 相关插件但不同版本提供的功能不完全一样。最稳的做法是打开 HBuilderX 的菜单选择“工具”-“插件安装”然后搜索 prettier 和 eslint 关键字看看你的 HBuilderX 版本能不能搜到对应的插件能装就装上。装好后很多插件还需要单独配置触发方式比如设置保存时自动执行或者通过快捷键触发。因为插件市场版本更新较快我不能保证你搜到的插件跟我当时用的是同一个所以下面我提供一个不管插件市场怎么变都能落地生效的思路。4.2 通过 HBuilderX 的配置实现保存时自动格式化如果你能在插件市场里搜到 HBuilderX 的 prettier 插件通常装上以后在“工具”-“设置”-“插件配置”里会看到和 Prettier 相关的选项包括是否在保存时自动格式化。把这个开关打开然后回到代码文件里改一行格式按 CtrlS 保存如果代码被重新排版了说明保存自动格式化已经生效。如果没有对应的插件或者你不想完全依赖插件市场还有一个比较原始但很稳定的做法利用 HBuilderX 的快捷键绑定功能把格式化命令绑定到一个组合键上然后通过 HBuilderX 的自定义快捷键模拟“保存并格式化”。这个操作的本质是不追求纯自动而是用快捷键一步完成保存和格式化。虽然体验上没有 VS Code 那种“保存即格式化”流畅但已经能很大程度避免因为忘记格式化而提交出混乱代码的情况。具体操作路径是菜单“工具”-“自定义快捷键”在打开的配置文件里新增一条快捷键规则把 HBuilderX 的格式化命令绑定到 CtrlS。注意这样会覆盖默认的保存行为你需要把原保存命令的键位换掉或者把格式化命令绑定为 CtrlShiftS 这类组合键保险一点。这个方法有个好处它不依赖第三方插件什么项目都能用缺点是它本质上不是“自动”更适合作为兜底方案。4.3 更彻底的做法用命令行脚本 文件监听实现真自动保存格式化如果上面的插件和快捷键方案你都不满意我还有一招更彻底的就是通过 npm script 配合 nodemon 之类的工具监听项目文件变动一旦检测到文件被修改并且保存就自动执行 eslint --fix 和 prettier 的格式化命令。这样甚至不需要 HBuilderX 做什么只要你保存文件脚本就会自己跑。第一步在 package.json 的 scripts 里加入这样两个命令{ scripts: { format: prettier --write \**/*.{js,ts,vue,json,css,scss,html}\, lint:fix: eslint --fix \src/**/*.{js,vue}\ --ext .js,.vue } }第二步如果你希望文件一保存就触发可以安装 nodemon 作为开发依赖然后加一个 watch 脚本npm install --save-dev nodemonwatch 脚本可以写成{ scripts: { watch:format: nodemon --watch src --ext js,vue,css,scss,json --exec \npm run format npm run lint:fix\ } }运行 npm run watch:format 以后它会监听 src 目录下所有 js、vue、css、scss、json 文件的变化一旦你保存文件它马上执行格式化命令和 ESLint 修复命令。这个方案的优点是跟编辑器无关HBuilderX、VS Code、WebStorm 通用而且可以使用在 CI 环境里保证所有人提交的代码风格一致。缺点也很明显nodemon 监听到文件变化后会立刻执行而你在编辑过程中如果出现临时文件、半行代码它也会触发格式化所以建议监听目录尽量缩小。HBuilderX 开发 uni-app 项目时临时目录和 unpackage 目录一定要排除掉否则脚本会疯狂执行。监听脚本只适合长期开启的场景如果你只在提交前跑一次那直接用 npm run format 和 npm run lint:fix 就够了。4.4 在 HBuilderX 3.x 中结合 package.json 脚本实现快速修复HBuilderX 3.x 版本在 project 的右键菜单里提供了“使用命令行窗口打开所在目录”的功能这为快速执行 npm script 提供了非常方便的入口。你在项目根目录打开终端直接执行 npm run lint:fix它就会按 .eslintrc.js 的规则自动修复所有能修的代码问题包括 Prettier 格式。虽然不是保存时自动触发但在提交本地代码前跑一跑效果完全不输保存自动格式化。如果你对“保存自动格式化”这个诉求非常强烈我通常会建议组合拳插件如果能用优先开插件的保存自动格式化插件不能用就用快捷键方案保证一键格式化同时把 npm script 写好配合 lint-staged 和 husky在 git 提交前自动先格式化再提交。这样即便编辑器里的保存没有触发格式化提交前的拦截也会强制把代码格式化好。4.5 验证配置是否生效的简单方法配置完以后怎么判断是否成功我一般会先新建一个测试文件故意写出明显不符合 Prettier 风格的代码比如字符串用双引号、行尾加很多空格、对象最后一项加逗号然后保存。如果文件里双引号变成了单引号多余的空格被删除说明保存自动格式化已经生效。再故意引入一个未使用的变量保存后看 ESLint 是否报 no-unused-vars 错误。如果报错说明 ESLint 检查正常工作如果没报错可能 ESLint 插件没有被正确加载或者配置文件没被识别。需要注意的是HBuilderX 对 eslint 插件加载有时需要重启编辑器。每次改完 .eslintrc.js 或者 .prettierrc如果发现配置不生效先别急着改配置重启一下 HBuilderX 再说很多诡异的“不生效”都是因为编辑器缓存了旧配置。5. 常见问题与排查技巧实录5.1 HBuilderX 保存时格式化但不生效保存没有触发布局格式化优先检查有没有安装对应的 Prettier 插件因为 HBuilderX 不会像 VS Code 那样自动读取 .prettierrc 就给你格式化。如果没有插件就去看快捷键设置里有没有绑定格式化命令。还有一个很容易被忽略的点插件安装以后有的版本需要在“工具”-“插件管理”里手动启用或者更改插件配置把“在保存时自动格式化”从关闭状态打开。我遇到过太多次装完插件没启用的情况看起来像是装了实际一点反应都没有。5.2 保存后代码被格式化但是格式不对如果保存后格式化是生效了但格式化出来的风格跟预期不一致比如你明明是单引号风格结果全部变成了双引号那基本可以断定 HBuilderX 调用的不是你的 Prettier 配置而是它内置格式化器的风格。这时候你需要把 Prettier 插件的配置指向项目根目录的 .prettierrc 文件。有些插件会有一个“读取配置文件”的开关默认可能没打开把它打开并指定为项目根目录再重启 HBuilderX 就好了。还有一种情况是你项目里同时存在 .prettierrc 和 .prettierrc.jsPrettier 会优先读取其中一个两个文件内容不一致会导致结果随机。建议只保留 .prettierrc 一种格式别叠着写。5.3 保存时提示 ESLint 服务器启动失败或找不到模块这类问题多半是 node_modules 没装全或者路径不对。比如报 Cannot find module eslint-plugin-prettier排查顺序先看项目根目录有没有 node_modules再确认 node_modules 里有没有对应的包然后确认 .eslintrc.js 在项目根目录而不是在其他层级。如果你是在别的目录执行的 npm install依赖装到了上一层目录HBuilderX 检查项目时未必能识别。解决办法是删掉 node_modules 和 package-lock.json在项目根目录重新执行 npm install。如果项目是通过 HBuilderX 创建的时候自动带了一套 node_modules而你手动把 package.json 替换了一定要重新安装依赖否则可能出现版本不一致的问题。5.4 uni-app 项目运行到微信小程序提示“不是开发者”是不是配置惹的祸配置完 Prettier 和 ESLint 后有人会遇到运行到微信小程序时提示不是开发者的问题。这里要说明一下这大概率跟格式化配置没关系是微信开发者工具的安全设置或者登录态问题。HBuilderX 运行到微信小程序时的“不是开发者”提示通常是微信开发者工具没打开服务端口或者当前微信账号不是该小程序的开发者。解决办法是打开微信开发者工具的“设置”-“安全设置”打开服务端口然后再回到 HBuilderX 重新运行。这个坑放在这里提醒一下是因为不少初学者在配置完一套工具链后会把各种怪问题都归结到工具链头上结果排查半天发现是无关问题。实际上只要你的 Prettier 和 ESLint 配置没有语法错误它绝对不会影响微信小程序的编译和授权两者完全处于不同层级。5.5 Vue 文件里格式化不完整如果你遇到 .vue 文件的 template 部分没有被格式化而 script 部分被格式化了很可能是 Prettier 版本较老或者缺少对应的解析器。新版本 Prettier 默认支持 Vue 文件解析不需要额外配置。如果你的版本比较低建议升级到最新版本同时检查 .prettierrc 里是否有 vueIndentScriptAndStyle 设置为 true这个选项会让 script 和 style 部分整体缩进一格让结构更清晰但有些版本的 HBuilderX 处理得不太好如果你遇到格式化异常可以把这个选项设置成 false 再试。5.6 保存自动格式化和 lint-staged、husky 结合保证提交前统一最后强烈建议不管你在 HBuilderX 里保存自动格式化是否成功都要加上 lint-staged 和 husky 这条安全底线。安装命令npm install --save-dev lint-staged husky然后在 package.json 里配置{ lint-staged: { *.{js,vue}: eslint --fix, *.{js,ts,vue,json,css,scss,html}: prettier --write } }再配合 husky 初始化 git hooks让它在 pre-commit 阶段自动执行 lint-staged。这样即使有人没开保存自动格式化只要他想提交代码就会被强制格式化并检查不通过就提交不了。这个机制对团队协作特别有用能保证仓库里的代码风格始终统一。6. 实用经验与最后的建议配置这套环境的过程中我踩过最深的一个坑是在 .eslintrc.js 里同时配置了 prettier/prettier 规则又在 rules 里手动加了几条 indent 和 quotes 规则结果导致每次 eslint --fix 都要反复改两遍格式整个文件 diff 大得吓人。后来想明白了Prettier 是格式化权威ESLint 只做质量检查两者交叉的部分全部交给 PrettierESLint 的 rules 里只保留业务相关规则比如 no-console、no-debugger、no-unused-vars 这种。自那以后格式化问题再也没有回来找过我。另外一个经验是HBuilderX 对配置文件的缓存有点顽固。每次修改 .prettierrc 或者 .eslintrc.js我都建议直接关闭项目再重新打开而不是只点一下刷新。很多时候你满心期待地保存测试结果毫无反应不一定是配置写错就是缓存问题。所以排查顺序永远是先重启编辑器再检查配置最后才是重新安装依赖。这套方案做下来最直接的收益是代码提交的 diff 变小了代码评审速度明显变快。我根据实际经验推荐的组合是HBuilderX 插件优先开保存自动格式化如果插件不灵就用快捷键方案项目里必须有 npm 脚本和 lint-staged 做兜底。双保险之下基本不会再因为格式问题被人找上门。后面如果你想把“自动格式化”再推向更深一步还可以在 .prettierrc 里针对不同文件类型做单文件配置或者扩展 ESLint 插件体系但这都是后话了先把保存自动格式化跑稳体验就已经很舒服了。