3.3忽略机制精准豁免

3.3 忽略机制精准豁免

为什么需要忽略

Prettier 的"格式化所有匹配文件"的策略在大多数情况下是你想要的。但总有例外：第三方生成的代码、自动生成的配置文件、包含特殊格式要求的代码片段、以及迁移过程中的过渡文件——这些你不希望 Prettier 碰。

Prettier 提供了两层忽略机制：文件级别的 .prettierignore 和 代码级别的行内注释。前者控制"哪些文件不处理"，后者控制"文件内哪些代码不处理"。

.prettierignore 文件

.prettierignore 的工作方式跟 .gitignore 一致——每行写一个 glob 模式，匹配到的文件会被 Prettier 跳过。

# .prettierignore

# 构建产物
dist/
build/
.next/

# 依赖目录
node_modules/

# 自动生成的文件
src/generated/
*.generated.ts

# 配置文件（某些工具有严格格式要求）
package-lock.json
yarn.lock

# 第三方代码
vendor/
​

几个注意点：

不需要重复写 .gitignore 的内容。Prettier 默认会参考 .gitignore 中的条目——如果 .gitignore 里有 node_modules/，即使 .prettierignore 里没写，Prettier 也不会处理 node_modules/ 里的文件。

glob 模式是相对于 .prettierignore 文件的位置。如果 .prettierignore 在项目根目录，src/generated/ 匹配的是 ./src/generated/ 目录。如果它在一个子目录里，匹配范围也会相应变化。但在实践中，.prettierignore 几乎总是放在项目根目录。

支持 ! 取反。跟 .gitignore 一样，你可以先用一个宽泛的 glob 排除一大类文件，再用 ! 把其中的特定文件包含回来：

# 忽略所有 generated 文件
*.generated.*

# 但不忽略 config.generated.ts（它需要 Prettier 格式化）
!config.generated.ts
​

匹配的是文件名，不是文件内容。.prettierignore 只决定 Prettier 是否处理某个文件，不能控制文件内的某段代码是否被格式化。文件内的精确控制需要用行内注释。

行内注释：对特定代码的豁免

.prettierignore 的粒度是文件级。如果你只想跳过文件中的一部分代码，需要用行内注释。

Prettier 支持两种行内注释语法：

prettier-ignore

用 // prettier-ignore 注释来跳过紧接着的下一条语句。Prettier 在格式化时遇到这个注释，会跳过它后面的那条语句（保持原样），然后继续格式化后面的代码。

// prettier-ignore
const matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
​

如果没有 prettier-ignore，Prettier 会把这段代码格式化成多行：

const matrix = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
];
​

但在这个场景中，矩阵在单行内的紧凑格式更易读（它表达了"这是一个完整的矩阵"的语义），所以用 prettier-ignore 保持原样是合理的。

prettier-ignore-start / prettier-ignore-end

如果你需要跳过多行代码，可以用 prettier-ignore-start 和 prettier-ignore-end 包裹：

// prettier-ignore-start
const a = {
  name:"Alice",age:30,
  city:"Beijing"
}
const b={name:"Bob",age:25,city:"Shanghai"}
// prettier-ignore-end

// 下面的代码仍然会被格式化
const c = {
  name: "Charlie",
  age: 35,
};
​

CSS/SCSS/HTML 中的行内注释语法略有不同，用对应语言的注释格式：

/* prettier-ignore */
.special-layout {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 1rem;
}
​

<!-- prettier-ignore -->
<div class="special-layout">
  <span>item1</span><span>item2</span><span>item3</span>
</div>
​

使用忽略机制的合理场景

不是所有"格式化后不好看"的情况都应该用忽略来绕过。大部分情况下，Prettier 的格式化决策是合理的，只是你可能还不习惯。只有以下场景值得使用忽略机制：

自动生成的代码。比如 GraphQL schema 自动生成的 TypeScript 类型文件、Protocol Buffers 生成的代码。这些文件在重新生成时会被覆盖，格式化它没有意义。

手工优化的对齐布局。某些表格数据或矩阵数据在紧凑的单行/对齐格式下更易读，但 Prettier 会把它们展开。这种情况用 prettier-ignore 保持紧凑布局是合理的。

迁移过渡期。在一个大规模项目中引入 Prettier 时，可能有少量文件因为历史原因无法一次性格式化（比如正在被另一个团队同时修改）。先把它们加进 .prettierignore，等稳定后再移除并格式化。

格式敏感的测试文件。某些快照测试（snapshot test）中包含代码字符串，Prettier 格式化会改变测试输出。这种情况需要把相关测试文件加进 .prettierignore，或者用行内注释精确跳过。

图 3-3：忽略机制选择路径

滥用忽略的风险

每个 prettier-ignore 注释都是对"统一格式"这个目标的偏离。偶尔用没问题，但如果项目中散布了大量的 prettier-ignore，说明 Prettier 的格式决策和团队的实际需求之间存在系统性偏差。这时应该重新审视配置，而不是到处加忽略注释。

一个健康的项目中，prettier-ignore 的数量应该很少——几十个文件中可能只有零星几个。如果你发现自己频繁地想加 prettier-ignore，先把想加的那个代码片段记录下来，看看它们是否有共性——也许是某个配置项需要调整，而不是用忽略来绕过。

忽略机制的最佳实践

1. .prettierignore 只放真正需要忽略的目录，不要放可能偶尔有用的目录。"保险起见先忽略"的心态会导致越来越多的文件脱离格式化保护。

2. 每个 prettier-ignore 注释旁边加一个简短的理由说明。半年后回头看，你能知道为什么这里需要忽略，而不是面对一个裸注释猜测原因。

// prettier-ignore — 保持矩阵紧凑格式，展开后不易读
const matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
​

3. 定期清理不再需要的忽略。比如自动生成的文件后来改成了手动维护，.prettierignore 里的条目就应该移除。