js代码格式化插件prettier：从配置到排错的完整教程
在团队协作中，不同成员写出的 JavaScript 代码风格往往不一致，导致代码审查时出现大量无关紧要的格式改动，增加合并冲突的概率。手动调整格式既耗时又容易遗漏。js代码格式化插件prettier 能够按照预设规则自动调整代码排版，让团队把精力集中在逻辑本身。本文面向已经了解基本前端工具链、但尚未系统配置过 Prettier 的开发者，从零开始讲解如何在项目中引入并稳定使用它，同时给出常见问题的排查思路和进阶用法。
准备工作：明确环境与项目现状
在动手配置之前，先确认几件事。第一，检查项目是否已经存在格式化相关的配置，比如 .prettierrc、.editorconfig 或者编辑器自带的格式化设置，避免重复配置导致规则冲突。第二，确认项目使用的包管理器类型，是 npm、yarn 还是 pnpm，后续安装依赖和运行脚本时命令会有所不同。第三，了解项目是否已经接入 ESLint。ESLint 关注代码质量，Prettier 关注代码风格，两者职责不同但可能对同一段代码给出矛盾的要求。如果项目已有 ESLint，需要提前规划好两者的边界。第四，确认团队是否使用统一的编辑器。如果成员使用不同编辑器，建议把配置写入项目文件而不是编辑器个人设置，这样规则才能随代码库一起分发。最后，和团队约定好本次格式化的范围：是只格式化新改动的文件，还是对存量代码做一次整体整理。范围不同，后续操作步骤会有差异。
分步操作：把 Prettier 接入项目
第一步，安装依赖。在项目根目录执行安装命令，把 Prettier 作为开发依赖加入项目。使用 npm 时运行 npm install --save-dev prettier，使用 yarn 时运行 yarn add --dev prettier，使用 pnpm 时运行 pnpm add -D prettier。安装完成后，可以在命令行中直接调用它来验证是否可用。
第二步，创建配置文件。在项目根目录新建 .prettierrc 文件，写入你需要的规则。常见的配置项包括 semi 控制是否在语句末尾添加分号，singleQuote 控制是否使用单引号，printWidth 控制换行的参考宽度，tabWidth 控制缩进宽度，trailingComma 控制多行结构末尾是否保留逗号。配置项不宜一次设置过多，先确定团队最在意的几条即可。
第三步，添加忽略文件。新建 .prettierignore，把构建产物目录、第三方依赖目录、自动生成的代码文件写进去。这些文件通常不需要格式化，强行处理反而会引入噪音。忽略文件的语法与 .gitignore 类似，可以按目录或按文件名模式书写。
第四步，配置编辑器集成。在编辑器中安装 Prettier 扩展，并把默认格式化工具设置为 Prettier，同时开启保存时自动格式化。这样每次保存文件时，格式就会自动调整，减少手动触发的次数。
第五步，添加脚本命令。在 package.json 的 scripts 字段中加入格式化命令，例如用 prettier --write . 处理整个项目，用 prettier --check . 只检查而不修改。前者用于主动整理，后者适合放进持续集成流程中做校验。
第六步，处理与 ESLint 的关系。如果项目同时使用 ESLint，建议安装 eslint-config-prettier 并在 ESLint 配置中继承它，关闭那些与 Prettier 冲突的规则。这样两个工具各司其职，不会互相覆盖对方的判断。
第七步，提交前校验。可以配合 Git 钩子工具，在提交代码前对暂存区的文件运行格式化，确保进入仓库的代码都符合约定。
常见错误与排查
配置完成后，最容易遇到的问题是格式化没有生效。先检查编辑器是否把 Prettier 设为默认格式化工具，有些编辑器会优先使用内置的格式化器。其次确认配置文件的位置是否正确，Prettier 会从当前文件所在目录向上查找配置，如果配置文件放在了子目录，可能不会被外层文件读取到。
第二个常见问题是保存时格式被反复改回原样。这通常意味着有另一个工具在同时格式化，比如 ESLint 的自动修复功能。需要检查编辑器的保存动作绑定了哪些操作，并确保只保留一个格式化来源。
第三个问题是规则冲突。当 Prettier 和 ESLint 对同一段代码给出不同要求时，编辑器可能来回修改。解决办法是使用 eslint-config-prettier 关闭冲突规则，而不是手动逐条禁用。
第四个问题是部分文件没有被格式化。检查 .prettierignore 是否误写了规则，把需要处理的目录排除掉了。同时确认文件扩展名是否在 Prettier 的识别范围内，某些特殊后缀的文件默认不会被处理。
第五个问题是命令行执行报错。先确认当前目录确实是项目根目录，再确认依赖是否安装成功。如果提示找不到命令，可以尝试通过包管理器提供的执行入口来调用，而不是直接使用全局命令。
进阶技巧：让格式化更贴合团队习惯
当基础配置稳定后，可以考虑一些进阶做法。第一，为不同目录设置不同的配置。Prettier 支持在子目录放置独立的配置文件，覆盖上层规则。比如测试目录和源码目录可以采用不同的换行宽度，这时在对应目录放置配置文件即可。
第二，利用配置继承减少重复。可以把公共规则抽成一个共享配置包，在多个项目中引用，避免每个项目都复制一份配置。
第三，把检查命令接入持续集成。在流水线中运行检查命令，如果代码不符合格式要求就让流程失败。这样可以在合并前拦截格式问题，而不是等到代码审查时才发现。
第四，与编辑器的工作区设置配合。把格式化相关设置写入项目的工作区配置文件，团队成员打开项目后会自动获得一致的编辑器行为，减少口头约定带来的偏差。
第五，处理历史代码。对存量代码做整体格式化时，建议单独提交一次，不要和功能改动混在同一个提交里。这样代码审查时更容易区分哪些是格式变化，哪些是逻辑变化。
第六，关注插件的扩展能力。Prettier 本身只处理格式，对于排序导入、组织代码结构等需求，可以配合其他工具完成，但要注意它们与 Prettier 的执行顺序，避免相互干扰。
总结
接入 js代码格式化插件prettier 的关键步骤是：安装依赖、创建配置文件、添加忽略文件、配置编辑器保存时格式化、在 package.json 中添加脚本命令、处理与 ESLint 的规则冲突，并在提交前做校验。遇到格式化不生效时，优先检查默认格式化工具、配置文件位置和忽略规则。进阶阶段可以把检查命令接入持续集成，并为不同目录设置独立配置，让格式规范真正落地。
常见问题
Q1为什么保存文件后代码格式没有变化？
先确认编辑器是否把 Prettier 设为默认格式化工具，有些编辑器会优先使用内置格式化器。再检查配置文件是否放在项目根目录，以及当前文件是否被忽略规则排除。如果这些都没问题，尝试手动执行一次格式化命令，看命令行是否报错。
Q2Prettier 和 ESLint 应该怎么分工？
Prettier 负责代码的排版风格，比如缩进、引号、换行；ESLint 负责代码质量和潜在问题，比如未使用变量、可疑逻辑。两者职责不同，但规则可能冲突。建议安装 eslint-config-prettier 并继承，关闭 ESLint 中与格式相关的规则，让 Prettier 单独管理格式。
Q3配置文件应该用哪种格式？
Prettier 支持多种配置格式，包括 JSON、YAML、JavaScript 等。选择团队最熟悉、编辑器支持最好的一种即可。如果配置需要根据环境动态计算，可以用 JavaScript 格式；如果只是静态规则，JSON 或 YAML 更直观。关键是整个项目统一使用一种，不要混用。
Q4如何只格式化自己改动的文件？
可以在命令行中指定文件路径或使用通配模式，只处理目标文件。也可以配合 Git 钩子，在提交前只对暂存区的文件运行格式化。这样既能保证新代码符合规范，又不会一次性改动大量历史文件。
Q5忽略文件应该写哪些内容？
通常包括构建输出目录、依赖安装目录、自动生成的代码文件、压缩后的资源文件等。这些内容要么不需要人工维护，要么格式化后反而影响可读性。忽略文件的写法与 .gitignore 类似，可以按目录或文件名模式书写。