说句实话我前阵子接了一个uni-app项目进去第一件事不是看业务代码而是先翻 git 提交记录。结果翻完差点没崩某一天的提交里全项目的单引号被换成了双引号隔了两天又有一次提交把双引号全改回单引号有人用 4 空格缩进有人用 tab最离谱的是一个只改了一行的需求git diff 里却多了两百多行改动全是格式化带来的噪音。这种场景在 HBuilderX 用户里太常见了——因为大家打开编辑器就直接写业务很少有人愿意花十几分钟把“保存自动格式化代码 Prettier eslint”这套基础设施配好。这篇文章就专门聊这件事在 HBuilderX现在基本都是 HBuilderX 了里怎么把保存自动格式化、Prettier 和 eslint 一次性配到位并且尽量避开我踩过的坑。1. 为什么非要在 HBuilderX 里折腾“保存自动格式化”代码整洁背后的真实痛点很多新手觉得“代码能跑就行格式化不重要”这个想法在一个人写小项目的时候确实没毛病。但一旦进入多人协作或者项目文件超过几十个代码风格不统一带来的麻烦会直接吃掉你的开发效率。1.1 格式化不一致是团队协作里的“隐形杀手”你想象一个场景同事 A 习惯双引号同事 B 习惯单引号同事 C 用的是 VSCode默认就是 2 空格缩进加自动补分号。三个人各自提交代码git 里每一条 diff 都混着大量的“空白字符变化”。等你去做 code review 的时候真正逻辑改了什么反而看不清整页全是红红绿绿的格式化差异。更要命的是合并冲突。两个人同时改了一个文件一个人用了 tab另一个人用了 2 空格git 在合并时可能就把整片代码视为冲突哪怕实际改动完全不重叠。我见过团队因此吵过架最后谁也没说服谁只能花半天手工处理冲突。这事说白了就是缺少一个“全项目统一的格式化标准”。而“保存自动格式化”就是把这个标准落地的第一步。1.2 手动格式化靠不住前端项目尤其明显有人说“那我写代码的时候注意规范不就行了”我劝你别高估自己。前端代码里对象嵌套对象、函数套函数、模板字符串里塞各种表达式手写缩进很容易出现层级错误尤其是 vue 单文件组件里 template、script、style 三块混在一起的时候。人不是机器连续写两个小时后缩进漏一格、引号用混太正常了。手动格式化另一个问题是“只格式化自己改的部分”。我见过很多人只格式化当前文件里自己改的那一段导致同一个文件里前面是 2 空格、后面是 4 空格文件越写越乱。自己单机写还没什么一旦代码交给别人维护对方第一反应就是“这文件被谁搞过”。所以我的原则一直是格式化这件事永远交给工具处理不要留给人的自觉。1.3 uni-app 多端项目的特殊性格式化能帮你提前暴露问题如果你用的是 HBuilderX 开发 uni-app 项目那“保存自动格式化”就不是锦上添花而是刚需。原因很简单uni-app 项目要跨端编译到小程序、App、H5代码里充满了条件编译注释比如// #ifdef APP-PLUS这种。如果代码层级是乱的条件编译注释的位置就很容易出错轻则导致某段代码在某个端没有生效重则编译直接报错。另外uni-app 项目里pages.json是 JSONC 格式可以带注释但这种文件对格式非常敏感少个逗号或者缩进不对整个应用的路由都崩。这种问题靠肉眼很难查。如果配置好了 Prettier ESLint很多格式问题在“保存”的那一刻就会被自动修复或者直接报错提醒而不是等编译的时候才炸出来。这就是我强烈建议每个 HBuilderX 用户都把这套东西配起来的原因。2. HBuilderX 自带的格式化能力先摸清家底再说很多人不知道HBuilderX 本身是有代码格式化功能的也不是非要装插件才能用。但在深入 Prettier 和 ESLint 之前我建议先把 HBuilderX 自带的东西摸明白因为你后面要做的所有配置本质上都是在“替换”或者“增强”这些默认行为。2.1 HBuilderX 内置格式化器的真面目HBuilderX 基于 VS Code 的内核做了深度定制所以它内置了 js-beautify 这类经典的格式化引擎。对 JS、CSS、HTML 这些基础文件直接右键“格式化代码”是有用的它能帮你自动缩进、统一空格。但问题是js-beautify 默认规则比较“古老”跟现在前端主流规范差别很大。比如 js-beautify 默认会在对象最后一项后面保留逗号对箭头函数参数的括号处理也很死板遇到 ES6 的语法偶尔还会把代码“美化”得奇奇怪怪。更麻烦的是它几乎不认 vue 单文件组件的语法结构你格式化一个.vue文件它可能只处理了script部分template和style基本原封不动。我说句实在话内置格式化器更适合应急不适合当团队统一标准。它最大的问题不是“不能用”而是“规则不可配置”五个同事装同一个 HBuilderX格式化出来结果还是一样的但一旦有人动了别的配置或者用了别的工具结果就千差万别。2.2 保存自动格式化开关在哪HBuilderX 里“保存时自动格式化”是内置功能不用装额外插件也能开。路径在工具 - 设置 - 编辑器配置。进去之后找到“保存时自动格式化”把它勾上。这里有两个细节需要留意。第一HBuilderX 的格式化逻辑默认是“保存的时候格式化整个文件”但也提供“仅格式化最近编辑的行”这个选项。我个人的建议是先用“格式化整个文件”因为这样可以保证全文件风格统一等你对 Prettier 配置非常熟悉、并且只是改了一行的时候可以切换成“仅格式化最近编辑的行”避免大范围 diff。第二勾上之后要注意看旁边的“格式化方式”HBuilderX 里可以选择使用内置格式化器还是外部插件。如果你已经装了 Prettier 插件在这里把它选成 Prettier保存动作才会真正走 Prettier 规则否则走的还是内置 js-beautify。这个选择项藏得比较深很多人勾了“保存时自动格式化”发现没效果多半就是没把格式化器切换过来。2.3 内置格式化的局限为什么最终还得靠 Prettier 和 ESLint我把话说透一点HBuilderX 内置格式化能解决“缩进混乱”但解决不了“风格统一”和“代码质量”这两个问题。什么叫“风格统一”就是全项目的单引号、双引号、分号、尾逗号、换行符这些细节全部都一致。这叫格式化规范需要的是 Prettier 这种专门做风格统一的工具。什么叫“代码质量”就是有没有未使用的变量、有没有 console.log 忘记删、有没有隐式的类型转换风险。这叫代码规则需要的是 ESLint 这种专门做静态检查的工具。而 HBuilderX 内置的能力只覆盖了“基础缩进”这一个维度对风格和质量基本无能为力。所以结论很明确HBuilderX 自带功能是地基Prettier 和 ESLint 才是真正让工程变得规范的上层建筑。两者不冲突配合使用效果才能拉满。3. 在 HBuilderX 中接入 Prettier格式化规则向工程化看齐Prettier 是现在前端生态里事实标准的代码格式化工具它设计的核心理念是“意见统一”不给你太多配置项声称“没有选择就是一种美德”。它支持 JS、TS、Vue、CSS、Less、SCSS、JSON、Markdown 等等几乎所有常见文件类型尤其对 vue 单文件组件有很好的支持。3.1 Prettier 是什么和“保存自动格式化”是什么关系Prettier 本身是一个基于 Node.js 的命令行工具。你在终端里执行npx prettier --write src/App.vue它会按照预定的规则把文件重写一遍。但真正好用的方式是把它集成进编辑器让你在“保存”的瞬间自动执行格式化。在 HBuilderX 里Prettier 的地位就是一个“格式化器”。你把 HBuilderX 默认的格式化器替换成 Prettier那么每次触发保存自动格式化时HBuilderX 就会调用 Prettier 去处理当前文件。所以这里有一个很多人忽略的点你不仅要装 Prettier 插件还要在 HBuilderX 的设置里明确告诉它“请用 Prettier”否则两者各干各的等于白配。3.2 安装 Prettier 插件HBuilderX 装插件有两种方式。推荐第一种打开 HBuilderX点击菜单栏的工具 - 插件安装在弹出的插件市场里搜“Prettier”找到对应插件点击安装。安装之后会提示重启 HBuilderX照做即可。第二种是手动安装适合插件市场里找不到的情况某些内网环境或者版本较老。你可以先用命令行全局安装 Prettiernpm install -g prettier然后在 HBuilderX 的插件配置里把 Prettier 的可执行文件路径指到你的全局安装目录。这个办法稍微麻烦一点但胜在可控。我个人建议能装插件就装插件省心。实操心得装完插件后先别急着写代码。随便开一个已有的 js 文件按CtrlShiftPMac 是CmdShiftP调出命令面板输入“Format Document”如果弹出的菜单里有 “Prettier” 的选项说明插件已经生效了。3.3 写一份可以直接复制的 .prettierrc.js 配置Prettier 支持在项目根目录放一个.prettierrc或.prettierrc.js文件来定义规则。我直接给你一份我在 uni-app 项目里用了很久的配置你可以直接复制// .prettierrc.js module.exports { printWidth: 120, // 每行代码最大宽度超过就换行 tabWidth: 2, // 缩进宽度这里用 2 空格uni-app 默认项目就是 2 空格 useTabs: false, // 不使用 tab 缩进 semi: false, // 句尾不加分号个人偏好习惯加分号的改成 true singleQuote: true, // 字符串强制用单引号 quoteProps: as-needed, // 对象属性名只有在必要时候才加引号 trailingComma: all, // 多行对象、数组末尾加逗号这个能有效减少 git diff bracketSpacing: true, // 对象花括号两侧加空格: { foo: bar } arrowParens: always, // 箭头函数参数始终加括号: (x) x proseWrap: preserve, // 对 Markdown 文本不强制换行 htmlWhitespaceSensitivity: ignore, // HTML 空格的敏感度建议 ignore避免 vue 模板产生多余空格 endOfLine: lf, // 换行符统一用 LF避免 Windows 和 Mac 冲突 vueIndentScriptAndStyle: false, // vue 中 script 和 style 标签内部不额外缩进 }这套配置有一个核心思路尽量把 diff 控制到最小。semi和singleQuote是纯风格偏好你团队内部定一个就行但trailingComma我强烈建议设成all因为多行结构的最后一项加逗号以后新增一行时 git diff 只会有一行新增而不是“上一行改了逗号 新增一行”两条记录。3.4 怎么让保存时走 Prettier配好.prettierrc.js之后接下来要让 HBuilderX 在保存时用 Prettier 格式化。具体操作打开工具 - 设置 - 编辑器配置勾选“保存时自动格式化”。在“格式化方式”或“默认格式化器”这一项里选择Prettier。如果设置里有“语言配置”可以单独把 JavaScript、TypeScript、Vue、CSS、JSON 这些语言都指到 Prettier。这里不同版本的 HBuilderX 界面文字可能不太一样但大方向是先勾保存自动格式化再把格式化器切到 Prettier。配完之后你随意改一个文件故意把缩进打乱然后CtrlS代码会被瞬间整理得整整齐齐那感觉非常解压。注意如果你项目里已经有大量历史代码第一次保存格式化时会一次性把整个文件都重排导致 git diff 巨大。这种情况建议分文件提交或者先在测试分支跑一遍确认格式化结果不会破坏条件编译注释再合入主干。4. 接入 ESLint让代码质量和格式一起被管住Prettier 解决的只是“格式好不好看”的问题而 ESLint 解决的是“代码写得对不对”的问题。两者配合才是工程化标准的完整形态。4.1 为什么有了 Prettier 还要 ESLint我用一句话解释Prettier 是美化师ESLint 是质检员。美化师只管把排版弄得整齐漂亮但不关心你代码里有没有声明了却没用的变量、有没有没删掉的 console.log、有没有在 Vue 组件里写了不推荐的写法。这些是质量层面的事。反过来ESLint 也不擅长统一风格。ESLint 虽然有缩进、引号之类的风格规则但它的强项是逻辑检查如果你让 ESLint 去管所有代码风格你会发现规则配起来极其繁琐而且它的格式化能力远不如 Prettier 细腻。所以业界的主流做法是Prettier 格式化ESLint 查质量两者通过配置文件互相配合互不干扰。在没有 ESLint 的时候代码只是“好看”有了 ESLint代码才真正“健康”。4.2 HBuilderX 中把 ESLint 跑起来的几种姿势在 HBuilderX 里跑 ESLint 有几种方式我按推荐程度排一下方式一安装 ESLint 插件。在工具 - 插件安装里搜索“ESLint”安装后重启。这个插件会在你编辑代码时实时显示红色波浪线并给出规则提示。配置好之后保存时还能自动修复一部分问题。这是最贴近 VS Code 使用体验的方案。方式二用命令行。在项目根目录打开终端HBuilderX 左下角有终端图标或者用内置终端直接执行npx eslint src --fix这会把src目录下所有 JS/Vue 文件扫描一遍并自动修复可修复的问题。适合做提交前全量检查。方式三配到 npm scripts 里。在package.json里加一段{ scripts: { lint: eslint --ext .js,.vue src --fix, format: prettier --write src } }然后不管用什么工具只要执行npm run lint就能全项目统一检查。这个方法对团队协作最友好因为你不能强迫每个人都在 HBuilderX 里装插件但你可以要求每个人在提交前必须跑npm run lint。4.3 核心用 eslint-config-prettier 化解冲突这是整个配置过程中最关键的环节也是最多人卡住的地方。你可能会遇到这种情况Prettier 说“字符串应该用单引号”ESLint 也说“字符串应该用单引号”两个规则一致倒好说但有时候 Prettier 要加尾逗号ESLint 的规则又禁止尾逗号两个工具就吵起来了。解决这个问题的办法是安装eslint-config-prettier并在 ESLint 配置里把 Prettier 的规则排到最后意思就是“凡是有冲突的规则一律以 Prettier 为准”。这样 ESLint 就会主动闭嘴不去报那些和 Prettier 冲突的格式错误。有个更省事的方案是直接用plugin:prettier/recommended它帮你把eslint-config-prettier和eslint-plugin-prettier都配好了。eslint-plugin-prettier的作用是把 Prettier 当成一个 ESLint 规则来跑这样你执行eslint --fix的时候实际上也等于执行了 Prettier 格式化。4.4 保存时让 ESLint 自动修复能修的当场修如果你装的是新版 ESLint 插件HBuilderX 的插件配置里一般会有一项“保存时自动修复”勾上之后保存文件时 ESLint 会扫描当前文件把能自动修复的问题直接修掉不能自动修复的继续用红波浪线标出来。如果你的 HBuilderX 版本里没有这个设置项也别急。我实际用下来发现只要你自己写代码习惯不太“野”大部分常见问题比如多了空格、少了分号、用了双引号都能被 Prettier 先处理掉ESLint 自动修复的工作量其实很小。真正需要人工处理的都是些“变量未使用”“组件命名不规范”这种没法自动改的问题。5. 完整实操从零配好“保存自动格式化 Prettier ESLint”前面原理讲得差不多了现在给你一个可以直接照着操作的完整流程。我用一个最典型的 uni-app 项目举例非 uni-app 的普通前端项目也同理往上套就行。5.1 准备项目与安装依赖假设你已经在 HBuilderX 里创建了一个 uni-app 项目或者打开已有项目接下来第一步是安装依赖。在项目根目录打开终端npm init -y npm install -D prettier eslint eslint-config-prettier eslint-plugin-prettier eslint-plugin-vue babel/eslint-parser这里解释一下每个包是干嘛的prettier格式化引擎。eslint代码检查核心。eslint-config-prettier关闭 ESLint 里与 Prettier 冲突的规则。eslint-plugin-prettier把 Prettier 作为 ESLint 的一个规则运行这样eslint --fix也能完成格式化。eslint-plugin-vue给 Vue 文件提供 ESLint 规则uni-app 项目必装。babel/eslint-parser让 ESLint 能正确解析现代 JavaScript包括 ES6 语法。如果你的项目里有package.json了直接执行上面第二条安装命令即可。安装过程可能有点慢别急等它跑完。5.2 配置文件直接抄.prettierrc.js / .eslintrc.js / .editorconfig / .prettierignore依赖装好之后在项目根目录新建几个配置文件。我直接把能用的配置贴出来.prettierrc.jsmodule.exports { printWidth: 120, tabWidth: 2, useTabs: false, semi: false, singleQuote: true, quoteProps: as-needed, trailingComma: all, bracketSpacing: true, arrowParens: always, proseWrap: preserve, htmlWhitespaceSensitivity: ignore, endOfLine: lf, vueIndentScriptAndStyle: false, }.eslintrc.jsmodule.exports { root: true, env: { browser: true, es2021: true, node: true, }, extends: [ plugin:vue/vue3-essential, // Vue 3 项目用这个Vue 2 项目换成 plugin:vue/vue2-essential plugin:prettier/recommended, // 关键把 Prettier 规则作为 ESLint 规则跑并关闭冲突项 ], parserOptions: { parser: babel/eslint-parser, ecmaVersion: 2021, sourceType: module, }, rules: { vue/multi-word-component-names: off, // 关闭 Vue 组件必须多单词命名的限制uni-app 里很多页面是单单词 no-console: process.env.NODE_ENV production ? warn : off, // 生产环境 console 给警告 no-debugger: process.env.NODE_ENV production ? error : off, // 生产环境禁止 debugger }, }.editorconfig这个文件能让 HBuilderX、VS Code、WebStorm 等所有工具遵守统一缩进风格root true [*] charset utf-8 indent_style space indent_size 2 end_of_line lf insert_final_newline true trim_trailing_whitespace true [*.md] trim_trailing_whitespace false.prettierignore告诉 Prettier 哪些文件不要动node_modules/ unpackage/ dist/ *.min.js *.map package-lock.json uni_modules/uni_modules这个目录建议忽略因为它是插件市场下载的第三方插件代码格式化后会产生大量无效 diff而且下个版本更新插件时大概率会冲突。5.3 HBuilderX 侧的关键设置配置文件放好之后回到 HBuilderX 操作界面安装插件工具 - 插件安装分别安装 Prettier 插件和 ESLint 插件按提示重启。开启保存时自动格式化工具 - 设置 - 编辑器配置勾选“保存时自动格式化”并把格式化器选成 Prettier。开启 ESLint 插件安装完 ESLint 插件后在工具 - 插件配置 - ESLint里确认启用了“保存时自动修复”。设置语言格式化器在编辑器配置的“语言格式”里把 JavaScript、Vue、JSON、CSS 这些语言都默认指向 Prettier。这里有个心理准备不同版本的 HBuilderX 插件配置界面长得可能不一样但核心就是找到“格式化器选 Prettier”和“ESLint 保存时自动修复”这两个开关。5.4 保存瞬间发生了什么一次实测过程记录配好之后我做了一个小测试验证整个链路是否真的通了。我故意写了一段“脏代码”const a1 const b{ name:张三 } if(a1){console.log(b.name)}然后CtrlS保存。瞬间文件变成了const a 1 const b { name: 张三 } if (a 1) { console.log(b.name) }单引号被纠正、等号两边加上了空格、对象花括号里有了空格、if语句的大括号换行也对齐了。这是 Prettier 在起作用。紧接着ESLint 的红波浪线出现了。它标出了if (a 1)下面的波浪线提示Expected and instead saw 建议用严格相等以及console在生产环境下的警告。这些是 Prettier 管不了的质量问题只能靠 ESLint。保存时如果能自动修复的比如双引号改单引号、号后加空格ESLint 已经在后台悄悄改掉了。从这次测试可以看出Prettier 和 ESLint 的分工是真实存在的一个管排版一个管代码质量两者同时挂载在“保存”这个动作上互不冲突还互相兜底。6. 常见问题与排查技巧实录配置过程中总会碰到各种幺蛾子。下面这些是我实际用 HBuilderX 过程中遇到过、并且已经找到解决办法的问题直接给你列成速查。6.1 最常踩的坑保存没反应这个问题 90% 的原因是“保存时自动格式化”没勾上或者勾上了但格式化器没切成 Prettier。先去工具 - 设置 - 编辑器配置里看一遍确认两项都在。第二个常见原因是项目根目录没有.prettierrc.js或.prettierignore里把当前文件给忽略了。还有一种情况是 HBuilderX 还没识别你的项目类型试着关掉项目重新打开。6.2 引号、分号反复横跳ESLint 和 Prettier 打架如果你发现按保存时引号从单变双、分号加加减减说明你的 ESLint 配置里没有引入eslint-config-prettier或者extends的顺序不对。一定要把plugin:prettier/recommended放在extends数组最后面这样它的规则优先级最高。记住这个口诀Prettier 是风格上的最终裁决者ESLint 不得反对。6.3 vue 文件只格式化一半template 和 script 冰火两重天这种情况一般是你项目里同时装了好几款格式化插件而 vue 文件的格式化器被另一个插件接管了。解决办法在 HBuilderX 的编辑器配置里明确把.vue文件的格式化器指定为 Prettier。另外要确保eslint-plugin-vue已安装并且.eslintrc.js里extends包含了plugin:vue/vue3-essential或 vue2 对应版本否则 ESLint 可能连 vue 文件都不解析。6.4 条件编译注释被格式化弄乱uni-app 项目里用// #ifdef APP-PLUS这种条件编译注释Prettier 有时会把它当成普通注释整理导致位置变化。目前没有特别完美的根治办法我的经验是把条件编译的注释行单独顶格写不要缩进如果某段代码格式特别敏感可以在文件顶部加// prettier-ignore注释让 Prettier 跳过下一行。但这种情况极少只有在条件编译和复杂嵌套同时出现时才需要。6.5 eslint 红波浪线一直在分子两种情况。第一插件没启用去插件配置里开启。第二项目根目录没有node_modules或者 ESLint 相关的依赖没装全红波浪线会一直转圈不出来。运行一次npm install重新装依赖再重启 HBuilderX 就好了。还有一种可能是你改了.eslintrc.js但 HBuilderX 缓存了旧配置把 HBuilderX 彻底关闭重开能解决。6.6 团队配置文件冲突的速查与兜底团队成员有人用 HBuilderX有人用 VS Code那配置怎么统一我的建议是全队统一使用.editorconfig作为底层缩进约定这块 HBuilderX 和 VS Code 都原生支持。Prettier 的规则看.prettierrc.jsESLint 看.eslintrc.js这两个文件必须提交到 git 仓库并且严禁个人在本地随意修改。我还建议在package.json里加上lint和format两个 scripts 脚本让不依赖编辑器的全量检查成为可能。最终兜底方案也很简单git 提交前强制过一遍npm run lint加了 pre-commit 钩子的话连漏网之鱼都没有。说实话配置这套东西看起来要学的东西挺多但真操作一遍会发现无非就是“装两个插件 复制三份配置文件 在设置面板里点几个开关”的事。我个人的体会是花这十几分钟非常值因为它等于给整个项目的代码质量上了一道“自动防线”以后再也不用在评审代码时为了引号分号去和人争论了。最后再分享一个小建议把这份配置提交到仓库之后约定全组不准私自改改配置必须走 MR 评审。这样才能保证“保存自动格式化”真正成为团队共识而不是一个人自嗨。
HBuilderX 保存自动格式化：Prettier 与 ESLint 工程化配置指南
说句实话我前阵子接了一个uni-app项目进去第一件事不是看业务代码而是先翻 git 提交记录。结果翻完差点没崩某一天的提交里全项目的单引号被换成了双引号隔了两天又有一次提交把双引号全改回单引号有人用 4 空格缩进有人用 tab最离谱的是一个只改了一行的需求git diff 里却多了两百多行改动全是格式化带来的噪音。这种场景在 HBuilderX 用户里太常见了——因为大家打开编辑器就直接写业务很少有人愿意花十几分钟把“保存自动格式化代码 Prettier eslint”这套基础设施配好。这篇文章就专门聊这件事在 HBuilderX现在基本都是 HBuilderX 了里怎么把保存自动格式化、Prettier 和 eslint 一次性配到位并且尽量避开我踩过的坑。1. 为什么非要在 HBuilderX 里折腾“保存自动格式化”代码整洁背后的真实痛点很多新手觉得“代码能跑就行格式化不重要”这个想法在一个人写小项目的时候确实没毛病。但一旦进入多人协作或者项目文件超过几十个代码风格不统一带来的麻烦会直接吃掉你的开发效率。1.1 格式化不一致是团队协作里的“隐形杀手”你想象一个场景同事 A 习惯双引号同事 B 习惯单引号同事 C 用的是 VSCode默认就是 2 空格缩进加自动补分号。三个人各自提交代码git 里每一条 diff 都混着大量的“空白字符变化”。等你去做 code review 的时候真正逻辑改了什么反而看不清整页全是红红绿绿的格式化差异。更要命的是合并冲突。两个人同时改了一个文件一个人用了 tab另一个人用了 2 空格git 在合并时可能就把整片代码视为冲突哪怕实际改动完全不重叠。我见过团队因此吵过架最后谁也没说服谁只能花半天手工处理冲突。这事说白了就是缺少一个“全项目统一的格式化标准”。而“保存自动格式化”就是把这个标准落地的第一步。1.2 手动格式化靠不住前端项目尤其明显有人说“那我写代码的时候注意规范不就行了”我劝你别高估自己。前端代码里对象嵌套对象、函数套函数、模板字符串里塞各种表达式手写缩进很容易出现层级错误尤其是 vue 单文件组件里 template、script、style 三块混在一起的时候。人不是机器连续写两个小时后缩进漏一格、引号用混太正常了。手动格式化另一个问题是“只格式化自己改的部分”。我见过很多人只格式化当前文件里自己改的那一段导致同一个文件里前面是 2 空格、后面是 4 空格文件越写越乱。自己单机写还没什么一旦代码交给别人维护对方第一反应就是“这文件被谁搞过”。所以我的原则一直是格式化这件事永远交给工具处理不要留给人的自觉。1.3 uni-app 多端项目的特殊性格式化能帮你提前暴露问题如果你用的是 HBuilderX 开发 uni-app 项目那“保存自动格式化”就不是锦上添花而是刚需。原因很简单uni-app 项目要跨端编译到小程序、App、H5代码里充满了条件编译注释比如// #ifdef APP-PLUS这种。如果代码层级是乱的条件编译注释的位置就很容易出错轻则导致某段代码在某个端没有生效重则编译直接报错。另外uni-app 项目里pages.json是 JSONC 格式可以带注释但这种文件对格式非常敏感少个逗号或者缩进不对整个应用的路由都崩。这种问题靠肉眼很难查。如果配置好了 Prettier ESLint很多格式问题在“保存”的那一刻就会被自动修复或者直接报错提醒而不是等编译的时候才炸出来。这就是我强烈建议每个 HBuilderX 用户都把这套东西配起来的原因。2. HBuilderX 自带的格式化能力先摸清家底再说很多人不知道HBuilderX 本身是有代码格式化功能的也不是非要装插件才能用。但在深入 Prettier 和 ESLint 之前我建议先把 HBuilderX 自带的东西摸明白因为你后面要做的所有配置本质上都是在“替换”或者“增强”这些默认行为。2.1 HBuilderX 内置格式化器的真面目HBuilderX 基于 VS Code 的内核做了深度定制所以它内置了 js-beautify 这类经典的格式化引擎。对 JS、CSS、HTML 这些基础文件直接右键“格式化代码”是有用的它能帮你自动缩进、统一空格。但问题是js-beautify 默认规则比较“古老”跟现在前端主流规范差别很大。比如 js-beautify 默认会在对象最后一项后面保留逗号对箭头函数参数的括号处理也很死板遇到 ES6 的语法偶尔还会把代码“美化”得奇奇怪怪。更麻烦的是它几乎不认 vue 单文件组件的语法结构你格式化一个.vue文件它可能只处理了script部分template和style基本原封不动。我说句实在话内置格式化器更适合应急不适合当团队统一标准。它最大的问题不是“不能用”而是“规则不可配置”五个同事装同一个 HBuilderX格式化出来结果还是一样的但一旦有人动了别的配置或者用了别的工具结果就千差万别。2.2 保存自动格式化开关在哪HBuilderX 里“保存时自动格式化”是内置功能不用装额外插件也能开。路径在工具 - 设置 - 编辑器配置。进去之后找到“保存时自动格式化”把它勾上。这里有两个细节需要留意。第一HBuilderX 的格式化逻辑默认是“保存的时候格式化整个文件”但也提供“仅格式化最近编辑的行”这个选项。我个人的建议是先用“格式化整个文件”因为这样可以保证全文件风格统一等你对 Prettier 配置非常熟悉、并且只是改了一行的时候可以切换成“仅格式化最近编辑的行”避免大范围 diff。第二勾上之后要注意看旁边的“格式化方式”HBuilderX 里可以选择使用内置格式化器还是外部插件。如果你已经装了 Prettier 插件在这里把它选成 Prettier保存动作才会真正走 Prettier 规则否则走的还是内置 js-beautify。这个选择项藏得比较深很多人勾了“保存时自动格式化”发现没效果多半就是没把格式化器切换过来。2.3 内置格式化的局限为什么最终还得靠 Prettier 和 ESLint我把话说透一点HBuilderX 内置格式化能解决“缩进混乱”但解决不了“风格统一”和“代码质量”这两个问题。什么叫“风格统一”就是全项目的单引号、双引号、分号、尾逗号、换行符这些细节全部都一致。这叫格式化规范需要的是 Prettier 这种专门做风格统一的工具。什么叫“代码质量”就是有没有未使用的变量、有没有 console.log 忘记删、有没有隐式的类型转换风险。这叫代码规则需要的是 ESLint 这种专门做静态检查的工具。而 HBuilderX 内置的能力只覆盖了“基础缩进”这一个维度对风格和质量基本无能为力。所以结论很明确HBuilderX 自带功能是地基Prettier 和 ESLint 才是真正让工程变得规范的上层建筑。两者不冲突配合使用效果才能拉满。3. 在 HBuilderX 中接入 Prettier格式化规则向工程化看齐Prettier 是现在前端生态里事实标准的代码格式化工具它设计的核心理念是“意见统一”不给你太多配置项声称“没有选择就是一种美德”。它支持 JS、TS、Vue、CSS、Less、SCSS、JSON、Markdown 等等几乎所有常见文件类型尤其对 vue 单文件组件有很好的支持。3.1 Prettier 是什么和“保存自动格式化”是什么关系Prettier 本身是一个基于 Node.js 的命令行工具。你在终端里执行npx prettier --write src/App.vue它会按照预定的规则把文件重写一遍。但真正好用的方式是把它集成进编辑器让你在“保存”的瞬间自动执行格式化。在 HBuilderX 里Prettier 的地位就是一个“格式化器”。你把 HBuilderX 默认的格式化器替换成 Prettier那么每次触发保存自动格式化时HBuilderX 就会调用 Prettier 去处理当前文件。所以这里有一个很多人忽略的点你不仅要装 Prettier 插件还要在 HBuilderX 的设置里明确告诉它“请用 Prettier”否则两者各干各的等于白配。3.2 安装 Prettier 插件HBuilderX 装插件有两种方式。推荐第一种打开 HBuilderX点击菜单栏的工具 - 插件安装在弹出的插件市场里搜“Prettier”找到对应插件点击安装。安装之后会提示重启 HBuilderX照做即可。第二种是手动安装适合插件市场里找不到的情况某些内网环境或者版本较老。你可以先用命令行全局安装 Prettiernpm install -g prettier然后在 HBuilderX 的插件配置里把 Prettier 的可执行文件路径指到你的全局安装目录。这个办法稍微麻烦一点但胜在可控。我个人建议能装插件就装插件省心。实操心得装完插件后先别急着写代码。随便开一个已有的 js 文件按CtrlShiftPMac 是CmdShiftP调出命令面板输入“Format Document”如果弹出的菜单里有 “Prettier” 的选项说明插件已经生效了。3.3 写一份可以直接复制的 .prettierrc.js 配置Prettier 支持在项目根目录放一个.prettierrc或.prettierrc.js文件来定义规则。我直接给你一份我在 uni-app 项目里用了很久的配置你可以直接复制// .prettierrc.js module.exports { printWidth: 120, // 每行代码最大宽度超过就换行 tabWidth: 2, // 缩进宽度这里用 2 空格uni-app 默认项目就是 2 空格 useTabs: false, // 不使用 tab 缩进 semi: false, // 句尾不加分号个人偏好习惯加分号的改成 true singleQuote: true, // 字符串强制用单引号 quoteProps: as-needed, // 对象属性名只有在必要时候才加引号 trailingComma: all, // 多行对象、数组末尾加逗号这个能有效减少 git diff bracketSpacing: true, // 对象花括号两侧加空格: { foo: bar } arrowParens: always, // 箭头函数参数始终加括号: (x) x proseWrap: preserve, // 对 Markdown 文本不强制换行 htmlWhitespaceSensitivity: ignore, // HTML 空格的敏感度建议 ignore避免 vue 模板产生多余空格 endOfLine: lf, // 换行符统一用 LF避免 Windows 和 Mac 冲突 vueIndentScriptAndStyle: false, // vue 中 script 和 style 标签内部不额外缩进 }这套配置有一个核心思路尽量把 diff 控制到最小。semi和singleQuote是纯风格偏好你团队内部定一个就行但trailingComma我强烈建议设成all因为多行结构的最后一项加逗号以后新增一行时 git diff 只会有一行新增而不是“上一行改了逗号 新增一行”两条记录。3.4 怎么让保存时走 Prettier配好.prettierrc.js之后接下来要让 HBuilderX 在保存时用 Prettier 格式化。具体操作打开工具 - 设置 - 编辑器配置勾选“保存时自动格式化”。在“格式化方式”或“默认格式化器”这一项里选择Prettier。如果设置里有“语言配置”可以单独把 JavaScript、TypeScript、Vue、CSS、JSON 这些语言都指到 Prettier。这里不同版本的 HBuilderX 界面文字可能不太一样但大方向是先勾保存自动格式化再把格式化器切到 Prettier。配完之后你随意改一个文件故意把缩进打乱然后CtrlS代码会被瞬间整理得整整齐齐那感觉非常解压。注意如果你项目里已经有大量历史代码第一次保存格式化时会一次性把整个文件都重排导致 git diff 巨大。这种情况建议分文件提交或者先在测试分支跑一遍确认格式化结果不会破坏条件编译注释再合入主干。4. 接入 ESLint让代码质量和格式一起被管住Prettier 解决的只是“格式好不好看”的问题而 ESLint 解决的是“代码写得对不对”的问题。两者配合才是工程化标准的完整形态。4.1 为什么有了 Prettier 还要 ESLint我用一句话解释Prettier 是美化师ESLint 是质检员。美化师只管把排版弄得整齐漂亮但不关心你代码里有没有声明了却没用的变量、有没有没删掉的 console.log、有没有在 Vue 组件里写了不推荐的写法。这些是质量层面的事。反过来ESLint 也不擅长统一风格。ESLint 虽然有缩进、引号之类的风格规则但它的强项是逻辑检查如果你让 ESLint 去管所有代码风格你会发现规则配起来极其繁琐而且它的格式化能力远不如 Prettier 细腻。所以业界的主流做法是Prettier 格式化ESLint 查质量两者通过配置文件互相配合互不干扰。在没有 ESLint 的时候代码只是“好看”有了 ESLint代码才真正“健康”。4.2 HBuilderX 中把 ESLint 跑起来的几种姿势在 HBuilderX 里跑 ESLint 有几种方式我按推荐程度排一下方式一安装 ESLint 插件。在工具 - 插件安装里搜索“ESLint”安装后重启。这个插件会在你编辑代码时实时显示红色波浪线并给出规则提示。配置好之后保存时还能自动修复一部分问题。这是最贴近 VS Code 使用体验的方案。方式二用命令行。在项目根目录打开终端HBuilderX 左下角有终端图标或者用内置终端直接执行npx eslint src --fix这会把src目录下所有 JS/Vue 文件扫描一遍并自动修复可修复的问题。适合做提交前全量检查。方式三配到 npm scripts 里。在package.json里加一段{ scripts: { lint: eslint --ext .js,.vue src --fix, format: prettier --write src } }然后不管用什么工具只要执行npm run lint就能全项目统一检查。这个方法对团队协作最友好因为你不能强迫每个人都在 HBuilderX 里装插件但你可以要求每个人在提交前必须跑npm run lint。4.3 核心用 eslint-config-prettier 化解冲突这是整个配置过程中最关键的环节也是最多人卡住的地方。你可能会遇到这种情况Prettier 说“字符串应该用单引号”ESLint 也说“字符串应该用单引号”两个规则一致倒好说但有时候 Prettier 要加尾逗号ESLint 的规则又禁止尾逗号两个工具就吵起来了。解决这个问题的办法是安装eslint-config-prettier并在 ESLint 配置里把 Prettier 的规则排到最后意思就是“凡是有冲突的规则一律以 Prettier 为准”。这样 ESLint 就会主动闭嘴不去报那些和 Prettier 冲突的格式错误。有个更省事的方案是直接用plugin:prettier/recommended它帮你把eslint-config-prettier和eslint-plugin-prettier都配好了。eslint-plugin-prettier的作用是把 Prettier 当成一个 ESLint 规则来跑这样你执行eslint --fix的时候实际上也等于执行了 Prettier 格式化。4.4 保存时让 ESLint 自动修复能修的当场修如果你装的是新版 ESLint 插件HBuilderX 的插件配置里一般会有一项“保存时自动修复”勾上之后保存文件时 ESLint 会扫描当前文件把能自动修复的问题直接修掉不能自动修复的继续用红波浪线标出来。如果你的 HBuilderX 版本里没有这个设置项也别急。我实际用下来发现只要你自己写代码习惯不太“野”大部分常见问题比如多了空格、少了分号、用了双引号都能被 Prettier 先处理掉ESLint 自动修复的工作量其实很小。真正需要人工处理的都是些“变量未使用”“组件命名不规范”这种没法自动改的问题。5. 完整实操从零配好“保存自动格式化 Prettier ESLint”前面原理讲得差不多了现在给你一个可以直接照着操作的完整流程。我用一个最典型的 uni-app 项目举例非 uni-app 的普通前端项目也同理往上套就行。5.1 准备项目与安装依赖假设你已经在 HBuilderX 里创建了一个 uni-app 项目或者打开已有项目接下来第一步是安装依赖。在项目根目录打开终端npm init -y npm install -D prettier eslint eslint-config-prettier eslint-plugin-prettier eslint-plugin-vue babel/eslint-parser这里解释一下每个包是干嘛的prettier格式化引擎。eslint代码检查核心。eslint-config-prettier关闭 ESLint 里与 Prettier 冲突的规则。eslint-plugin-prettier把 Prettier 作为 ESLint 的一个规则运行这样eslint --fix也能完成格式化。eslint-plugin-vue给 Vue 文件提供 ESLint 规则uni-app 项目必装。babel/eslint-parser让 ESLint 能正确解析现代 JavaScript包括 ES6 语法。如果你的项目里有package.json了直接执行上面第二条安装命令即可。安装过程可能有点慢别急等它跑完。5.2 配置文件直接抄.prettierrc.js / .eslintrc.js / .editorconfig / .prettierignore依赖装好之后在项目根目录新建几个配置文件。我直接把能用的配置贴出来.prettierrc.jsmodule.exports { printWidth: 120, tabWidth: 2, useTabs: false, semi: false, singleQuote: true, quoteProps: as-needed, trailingComma: all, bracketSpacing: true, arrowParens: always, proseWrap: preserve, htmlWhitespaceSensitivity: ignore, endOfLine: lf, vueIndentScriptAndStyle: false, }.eslintrc.jsmodule.exports { root: true, env: { browser: true, es2021: true, node: true, }, extends: [ plugin:vue/vue3-essential, // Vue 3 项目用这个Vue 2 项目换成 plugin:vue/vue2-essential plugin:prettier/recommended, // 关键把 Prettier 规则作为 ESLint 规则跑并关闭冲突项 ], parserOptions: { parser: babel/eslint-parser, ecmaVersion: 2021, sourceType: module, }, rules: { vue/multi-word-component-names: off, // 关闭 Vue 组件必须多单词命名的限制uni-app 里很多页面是单单词 no-console: process.env.NODE_ENV production ? warn : off, // 生产环境 console 给警告 no-debugger: process.env.NODE_ENV production ? error : off, // 生产环境禁止 debugger }, }.editorconfig这个文件能让 HBuilderX、VS Code、WebStorm 等所有工具遵守统一缩进风格root true [*] charset utf-8 indent_style space indent_size 2 end_of_line lf insert_final_newline true trim_trailing_whitespace true [*.md] trim_trailing_whitespace false.prettierignore告诉 Prettier 哪些文件不要动node_modules/ unpackage/ dist/ *.min.js *.map package-lock.json uni_modules/uni_modules这个目录建议忽略因为它是插件市场下载的第三方插件代码格式化后会产生大量无效 diff而且下个版本更新插件时大概率会冲突。5.3 HBuilderX 侧的关键设置配置文件放好之后回到 HBuilderX 操作界面安装插件工具 - 插件安装分别安装 Prettier 插件和 ESLint 插件按提示重启。开启保存时自动格式化工具 - 设置 - 编辑器配置勾选“保存时自动格式化”并把格式化器选成 Prettier。开启 ESLint 插件安装完 ESLint 插件后在工具 - 插件配置 - ESLint里确认启用了“保存时自动修复”。设置语言格式化器在编辑器配置的“语言格式”里把 JavaScript、Vue、JSON、CSS 这些语言都默认指向 Prettier。这里有个心理准备不同版本的 HBuilderX 插件配置界面长得可能不一样但核心就是找到“格式化器选 Prettier”和“ESLint 保存时自动修复”这两个开关。5.4 保存瞬间发生了什么一次实测过程记录配好之后我做了一个小测试验证整个链路是否真的通了。我故意写了一段“脏代码”const a1 const b{ name:张三 } if(a1){console.log(b.name)}然后CtrlS保存。瞬间文件变成了const a 1 const b { name: 张三 } if (a 1) { console.log(b.name) }单引号被纠正、等号两边加上了空格、对象花括号里有了空格、if语句的大括号换行也对齐了。这是 Prettier 在起作用。紧接着ESLint 的红波浪线出现了。它标出了if (a 1)下面的波浪线提示Expected and instead saw 建议用严格相等以及console在生产环境下的警告。这些是 Prettier 管不了的质量问题只能靠 ESLint。保存时如果能自动修复的比如双引号改单引号、号后加空格ESLint 已经在后台悄悄改掉了。从这次测试可以看出Prettier 和 ESLint 的分工是真实存在的一个管排版一个管代码质量两者同时挂载在“保存”这个动作上互不冲突还互相兜底。6. 常见问题与排查技巧实录配置过程中总会碰到各种幺蛾子。下面这些是我实际用 HBuilderX 过程中遇到过、并且已经找到解决办法的问题直接给你列成速查。6.1 最常踩的坑保存没反应这个问题 90% 的原因是“保存时自动格式化”没勾上或者勾上了但格式化器没切成 Prettier。先去工具 - 设置 - 编辑器配置里看一遍确认两项都在。第二个常见原因是项目根目录没有.prettierrc.js或.prettierignore里把当前文件给忽略了。还有一种情况是 HBuilderX 还没识别你的项目类型试着关掉项目重新打开。6.2 引号、分号反复横跳ESLint 和 Prettier 打架如果你发现按保存时引号从单变双、分号加加减减说明你的 ESLint 配置里没有引入eslint-config-prettier或者extends的顺序不对。一定要把plugin:prettier/recommended放在extends数组最后面这样它的规则优先级最高。记住这个口诀Prettier 是风格上的最终裁决者ESLint 不得反对。6.3 vue 文件只格式化一半template 和 script 冰火两重天这种情况一般是你项目里同时装了好几款格式化插件而 vue 文件的格式化器被另一个插件接管了。解决办法在 HBuilderX 的编辑器配置里明确把.vue文件的格式化器指定为 Prettier。另外要确保eslint-plugin-vue已安装并且.eslintrc.js里extends包含了plugin:vue/vue3-essential或 vue2 对应版本否则 ESLint 可能连 vue 文件都不解析。6.4 条件编译注释被格式化弄乱uni-app 项目里用// #ifdef APP-PLUS这种条件编译注释Prettier 有时会把它当成普通注释整理导致位置变化。目前没有特别完美的根治办法我的经验是把条件编译的注释行单独顶格写不要缩进如果某段代码格式特别敏感可以在文件顶部加// prettier-ignore注释让 Prettier 跳过下一行。但这种情况极少只有在条件编译和复杂嵌套同时出现时才需要。6.5 eslint 红波浪线一直在分子两种情况。第一插件没启用去插件配置里开启。第二项目根目录没有node_modules或者 ESLint 相关的依赖没装全红波浪线会一直转圈不出来。运行一次npm install重新装依赖再重启 HBuilderX 就好了。还有一种可能是你改了.eslintrc.js但 HBuilderX 缓存了旧配置把 HBuilderX 彻底关闭重开能解决。6.6 团队配置文件冲突的速查与兜底团队成员有人用 HBuilderX有人用 VS Code那配置怎么统一我的建议是全队统一使用.editorconfig作为底层缩进约定这块 HBuilderX 和 VS Code 都原生支持。Prettier 的规则看.prettierrc.jsESLint 看.eslintrc.js这两个文件必须提交到 git 仓库并且严禁个人在本地随意修改。我还建议在package.json里加上lint和format两个 scripts 脚本让不依赖编辑器的全量检查成为可能。最终兜底方案也很简单git 提交前强制过一遍npm run lint加了 pre-commit 钩子的话连漏网之鱼都没有。说实话配置这套东西看起来要学的东西挺多但真操作一遍会发现无非就是“装两个插件 复制三份配置文件 在设置面板里点几个开关”的事。我个人的体会是花这十几分钟非常值因为它等于给整个项目的代码质量上了一道“自动防线”以后再也不用在评审代码时为了引号分号去和人争论了。最后再分享一个小建议把这份配置提交到仓库之后约定全组不准私自改改配置必须走 MR 评审。这样才能保证“保存自动格式化”真正成为团队共识而不是一个人自嗨。
