企业官网建设流程全解析

Prettier 编辑器集成完全指南：从本地安装到各大编辑器配置与源码级解析

【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier

本文以 Prettier 官方 编辑器集成文档 为主体，系统讲解 Prettier 在各主流编辑器（VS Code、JetBrains 系列、Vim、Helix、Sublime Text、Visual Studio、Espresso）中的接入方式与配置要点。文档会先讲清“为什么必须在每个项目中本地安装 Prettier”这一核心前提，再逐编辑器给出可复制的配置步骤，最后结合 公共 API、文件监听方案 以及src/下的源码实现（如formatWithCursor、getFileInfo），剖析编辑器插件调用 Prettier 的底层链路，帮助你在任何开发环境中把 Prettier 用起来并理解其工作原理。

一、核心前提：在编辑器里运行，而不是只在命令行里

官方文档开篇即给出两条最重要的使用原则：

1. 推荐从编辑器中运行 Prettier——通过快捷键或保存时自动触发，这是体验最好的用法；
2. 必须把 Prettier 本地安装到每个项目中——让每个项目使用各自锁定的 Prettier 版本。

第二条原则之所以关键，是因为编辑器插件在解析版本时会优先拾取项目本地的 Prettier（即node_modules中的版本）。这一点在 安装指南 中被反复强调：

Don't skip the regular local install! Editor plugins will pick up your local version of Prettier, making sure you use the correct version in every project. (You wouldn't want your editor accidentally causing lots of changes because it's using a newer version of Prettier than your project!)

换句话说：如果你偷懒只装了全局版本，编辑器插件可能悄悄使用一个与项目版本不同的 Prettier 去格式化代码。由于 Prettier 的排版策略会随版本演进（每个发布版本都可能改变输出格式），版本不一致会导致团队成员之间反复“互相格式化对方的代码”，产生大量无意义的 diff 和合并冲突。

本地安装的完整步骤（继承自 docs/install.md）：

# 以 npm 为例（yarn/pnpm/bun/deno 类似，均需加 exact 锁定版本） npm install --save-dev --save-exact prettier

然后创建空配置文件，让编辑器和相关工具“知道”这个项目在用 Prettier：

node --eval "fs.writeFileSync('.prettierrc','{}\n')"

再创建.prettierignore明确哪些文件不格式化：

node --eval "fs.writeFileSync('.prettierignore','# Ignore artifacts:\nbuild\ncoverage\n')"

提示：如果项目目录下存在.gitignore，Prettier 会默认遵循其中的规则；--ignore-unknown参数可让 CLI 跳过不支持的文件类型而不报错。

下面按编辑器逐个展开。各编辑器插件的共同工作模式是：调用本地安装的 Prettier（Node API 或 CLI）→ 传入源码与文件路径 → Prettier 自动解析配置 → 返回格式化结果与光标位置。这一模式的底层实现在第四节结合源码剖析。

二、各编辑器接入方式

2.1 Visual Studio Code

• 在扩展侧边栏安装名为"Prettier - Code formatter"（即prettier-vscode）的扩展即可，配置项与快捷键以该扩展仓库为准；
• 如果想要在状态栏一键开关格式化，可额外安装vscode-status-bar-format-toggle扩展。

这是官方文档中描述最直接的一种编辑器：安装扩展后无需额外配置，插件会自动探测项目本地的 Prettier 版本与.prettierrc配置。

2.2 JetBrains 系列（WebStorm、PHPStorm、PyCharm 等）

完整的 WebStorm 配置指南 摘要如下：

• WebStorm 内置 Prettier 支持；IntelliJ IDEA、PhpStorm、PyCharm 等其他 JetBrains IDE 需要在Preferences / Settings | Plugins中安装并启用 Prettier 插件；
• 手动格式化：使用Reformat with Prettier动作（macOS 为Opt+Shift+Cmd+P，Windows/Linux 为Alt+Shift+Ctrl+P），可格式化选区、当前文件或整个目录；
• 自动化配置：打开Preferences / Settings | Languages & Frameworks | JavaScript | Prettier，勾选：
  • On save（保存时运行，对应Cmd+S / Ctrl+S）；
  • On 'Reformat Code' action（作为Opt+Cmd+L / Ctrl+Alt+L的默认格式化工具）；
• 默认作用范围为项目中已编辑过的.js、.ts、.jsx、.tsx文件。要扩展到其他文件类型或限定到特定目录，可按 glob 语法自定义模式。

2.3 Vim / Neovim

官方 Vim 配置指南 覆盖了四种方案，按“专精程度”从低到高排列：

方案 A：vim-prettier—— Prettier 专用 Vim 插件，安装与用法说明见其仓库 README。

方案 B：Neoformat—— 通用 lint/format 引擎，对 Prettier 有内置支持：

" 用 vim-plug 等插件管理器安装 Plug 'sbdchd/neoformat'

让 Neoformat优先使用项目本地的 Prettier（即node_modules/.bin/prettier而非$PATH中的全局版本）：

let g:neoformat_try_node_exe = 1

在受支持的文件中运行:Neoformat或:Neoformat prettier；保存时自动运行：

autocmd BufWritePre *.js Neoformat

也可以绑定到更频繁的事件上，例如TextChanged（Normal 模式下文本被修改后）与InsertLeave（退出插入模式时）同时触发：

autocmd BufWritePre,TextChanged,InsertLeave *.js Neoformat

不推荐把 Prettier 选项写进.vimrc，建议统一使用配置文件；如必须内联，注意每个空格都要用\转义：

autocmd FileType javascript setlocal formatprg=prettier\ --single-quote\ --trailing-comma\ es5 let g:neoformat_try_formatprg = 1

方案 C：ALE—— 要求 Vim 8 或 Neovim（依赖其异步能力）：

Plug 'dense-analysis/ale'

ALE 会优先使用本地安装的 Prettier，找不到再回退到全局安装。为所用语言启用 Prettier fixer：

let g:ale_fixers = { \ 'javascript': ['prettier'], \ 'css': ['prettier'], \}

注意 ALE 同时有linters和fixers两类工具，若不显式指定 linter，所有可用工具都会被运行，可能得到“格式正确但满屏 lint 报错”的文件。禁用该行为：

let g:ale_linters_explicit = 1

在 JavaScript/CSS 文件中执行:ALEFix运行 Prettier；保存时自动修复：

let g:ale_fix_on_save = 1

内联 Prettier 选项（官方仍建议优先用配置文件）：

let g:ale_javascript_prettier_options = '--single-quote --trailing-comma all'

方案 D：coc-prettier—— 面向 coc.nvim 的 Prettier 扩展，需要 neovim 或 vim 8.1：

Plug 'neoclide/coc.nvim', {'branch': 'release'}

CocInstall coc-prettier

在init.vim或.vimrc中定义格式化命令：

command! -nargs=0 Prettier :call CocAction('runCommand', 'prettier.formatFile')

在coc-settings.json中配置保存时自动格式化的语言：

{ "coc.preferences.formatOnSaveFiletypes": ["css", "markdown"] }

coc-prettier 的配置项与 prettier-vscode 保持一致，用:CocConfig打开coc-settings.json可获得自动补全。

裸方案：手动键位映射。如果不想装任何插件，可以自定义映射直接在当前 buffer 上跑 Prettier CLI：

nnoremap gp :silent %!prettier --stdin-filepath %<CR>

注意该裸方案的两个坑：代码存在语法错误时整个 buffer 会被错误信息替换（按u可撤销恢复）；且光标位置不会被保留。

2.4 Helix

在 Helix 的语言配置（language configuration）中为对应语言指定 formatter 即可，它会优先于任何 language server 生效。具体 Prettier formatter 写法参见 Helix 官方文档的 Formatter Configurations 页面（prettier 小节）。

2.5 Sublime Text

通过 Package Control 安装JsPrettier插件即可获得 Prettier 支持。

2.6 Visual Studio

安装JavaScriptPrettier（JavaScript Prettier）扩展。

2.7 Espresso

安装espresso-prettier插件。

2.8 编辑器不支持 Prettier？用文件监听兜底

对于没有原生集成（或插件不成熟）的编辑器，官方文件监听指南 给出的方案是使用onchange包监听文件变化并自动执行 Prettier：

npx onchange "**/*" -- npx prettier --write --ignore-unknown {{changed}}

或将其固化为package.json中的脚本：

{ "scripts": { "prettier-watch": "onchange \"**/*\" -- prettier --write --ignore-unknown {{changed}}" } }

其中{{changed}}会被替换为实际发生变更的文件列表，--ignore-unknown保证遇到不支持的文件类型时跳过而不是报错。配合 Git hooks 预提交方案（husky + lint-staged）可以形成“编辑器内实时格式化 + 提交前兜底”的双保险。

三、底层剖析：编辑器插件到底调用了 Prettier 的什么

各编辑器插件看似行为各异，但从源码结构看，它们最终都收敛到 Prettier 的同一组公共 API（定义于 src/index.js，文档见 docs/api.md）。理解这组 API 就能看懂任何编辑器集成的本质。

3.1formatWithCursor：保存格式化的同时保住光标位置

编辑器最核心的需求不只是“格式化全文”，而是格式化后光标不能跳位，否则编辑体验会立刻崩坏。Prettier 为此专门提供了prettier.formatWithCursor(source, options)，其内部实现位于 src/main/core.js：

// src/index.js —— format 实际上就是 formatWithCursor 的简化包装 async function format(text, options) { const { formatted } = await formatWithCursor(text, { ...options, cursorOffset: -1, }); return formatted; }

formatWithCursor接收cursorOffset选项表示光标在原文中的位置，返回{ formatted, cursorOffset }中格式化后文本里的新光标位置。从 coreFormat 的源码注释 可以读出其三步算法：

1. 定位：格式化前先从 AST 中找到包含光标的最小区域（一个叶子节点、两节点之间的区间、或节点与文档首尾的区间）；
2. 跟踪：格式化过程中记录该区域被写到哪里；
3. diff 回移：对“原区域文本（光标位置处插入特殊 CURSOR 符号）”与“格式化后区域文本”做仅允许插入/删除的字符级 diff，反推出光标应落的新偏移。

对应示例（来自 API 文档）：

await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" }); // -> { formatted: '1;\n', cursorOffset: 1 }

此外 formatRange 还负责只格式化部分文本（编辑器“格式化选区”能力的基础）：它会把选区向上扩展到行首以还原缩进，始终用lf格式化后再按endOfLine选项还原换行符，并正确平移落在选区内部或之后的光标偏移。

3.2getFileInfo：编辑器判断“该不该格式化”的依据

编辑器扩展在保存/快捷键触发前通常需要先判断：这个文件是否被忽略、能否推断出解析器。这正是prettier.getFileInfo(fileUrlOrPath, options)的职责，返回{ ignored: boolean, inferredParser: string | null }。

从 src/common/get-file-info.js 的实现可以确认其行为细节：

• ignored由.prettierignore/.gitignore规则计算（options.ignorePath与withNodeModules可影响结果）；
• 若未被忽略，inferredParser依次取自：调用方显式传入的options.parser→ 配置文件中的parser选项 → 加载内置插件与options.plugins指定插件后按文件扩展名推断（inferParser）；
• 若文件被忽略，inferredParser恒为null；
• options.resolveConfig: false可跳过配置搜索，用于“只检查是否被忽略”的高频轻量调用。

这也解释了为什么本地安装如此重要：插件通过options.plugins/config?.plugins加载的正是项目本地的解析能力，ignored与inferredParser的判定完全取决于项目目录内的配置与依赖。

3.3 配置解析：resolveConfig与插件共享的搜索器

编辑器插件格式化前需要拿到该文件适用的完整选项，对应prettier.resolveConfig(fileUrlOrPath, options)：从文件所在目录向上逐级搜索配置文件，找到即返回选项对象，找不到返回null。

配置文件的候选列表与优先级在 src/config/prettier-config/config-searcher.js 中硬编码（源码注释明确要求与 docs/configuration.md 保持同步），顺序为：

1. package.json/package.yaml中的"prettier"键；
2. .prettierrc（JSON 或 YAML 语法）；
3. .prettierrc.json/.prettierrc.yml/.prettierrc.yaml/.prettierrc.json5；
4. .prettierrc.js/prettier.config.js/.prettierrc.ts/prettier.config.ts；
5. .prettierrc.mjs/prettier.config.mjs/.prettierrc.mts/prettier.config.mts；
6. .prettierrc.cjs/prettier.config.cjs/.prettierrc.cts/prettier.config.cts；
7. .prettierrc.toml。

Prettier刻意不支持任何全局配置（见 docs/configuration.md），保证项目被复制到另一台机器后格式化行为不变——这对“编辑器集成”尤其关键：无论 VS Code 还是 Vim 插件，格式化结果都只由项目内配置决定，团队内各编辑器之间不会出现差异。

另外两个编辑器集成常用的 API：

• clearConfigCache()：Prettier 为性能会缓存配置/插件加载时的文件系统结构；编辑器集成感知到文件系统变更后应调用它清缓存。从 src/index.js 可见，它会同时清除配置缓存与插件缓存；
• check(source, options)：等价于 CLI 的--check/--list-different（见 src/cli/cli-options.evaluate.js），实现即“格式化一遍再与原文比对”（src/index.js），编辑器插件的“格式是否干净”状态栏指示通常基于它。

3.4 一个完整的“编辑器视角”调用序列

综合以上源码，一次典型的编辑器格式化流程为：

import * as prettier from "prettier"; // 1. 判断文件是否需要处理（被忽略？能推断解析器吗？） const { ignored, inferredParser } = await prettier.getFileInfo(filePath); if (ignored || !inferredParser) { /* 跳过 */ } // 2. 解析该文件适用的配置 const options = await prettier.resolveConfig(filePath); // 3. 带光标地格式化 const { formatted, cursorOffset } = await prettier.formatWithCursor(text, { ...(options ?? {}), filepath: filePath, cursorOffset, });

这也是 docs/api.md 中resolveConfig小节的官方示例模式。

四、小结：编辑器集成的检查清单

• 项目内本地安装精确版本的 Prettier（--save-exact/--exact），让各编辑器插件拾取同一版本；
• 放置.prettierrc（空对象即可），向编辑器与插件宣告“本项目使用 Prettier”；
• 放置.prettierignore，排除生成物（build、coverage 等）；
• 按编辑器选择插件：VS Code 装 “Prettier - Code formatter”；JetBrains 按 WebStorm 指南 勾选 On save / Reformat Code；Vim 按 Vim 指南 选用 vim-prettier / Neoformat / ALE / coc-prettier，并设置try_node_exe类选项确保走本地版本；Sublime/Visual Studio/Espresso/Helix 按对应插件接入；
• 编辑器无集成时，用onchange文件监听脚本兜底（见 docs/watching-files.md）；
• 理解底层 API：getFileInfo决定“要不要格式化”、resolveConfig决定“按什么规则格式化”、formatWithCursor负责“格式化且光标不跳”——这是所有编辑器插件的共同地基（src/index.js、src/main/core.js、src/common/get-file-info.js）。

【免费下载链接】prettierPrettier is an opinionated code formatter.项目地址: https://gitcode.com/gh_mirrors/pr/prettier