EditorConfig 与 Prettier：统一团队代码风格

.editorconfig 负责跨编辑器统一缩进、换行符、字符集等基础规则；Prettier 负责把支持的代码解析后重新格式化。两者互补而不是二选一：先用 EditorConfig 建立文件级基线，再用 Prettier 统一 JavaScript、TypeScript、CSS、JSON 等代码的具体排版。

目录

• 两者的职责区别
• 推荐的 .editorconfig
• 推荐的 Prettier 配置
• 忽略生成文件
• package.json 脚本
• 与 ESLint 的关系
• 编辑器保存时格式化
• 常见冲突排查
• 参考资料

两者的职责区别

Prettier 会读取项目中的 .editorconfig，并把其中可映射的属性作为配置；更具体的 Prettier 配置会覆盖对应值。因此两个文件中的缩进和行宽最好保持一致，避免开发者困惑。

推荐的 .editorconfig

在仓库根目录创建：

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 2
trim_trailing_whitespace = true
max_line_length = 100

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

root = true 会阻止编辑器继续向父目录寻找配置。Markdown 中行末空格可能用于显式换行，所以通常单独关闭清理。

推荐的 Prettier 配置

项目可以使用 .prettierrc.json：

{
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all"
}

配置文件应提交到 Git。不要依赖开发者电脑上的全局 Prettier 配置；Prettier 官方有意不支持全局配置，以确保仓库复制到另一台电脑后仍产生一致结果。

忽略生成文件

在 .prettierignore 中排除不应格式化的内容：

.next
dist
coverage
node_modules
public/search-index-*.json
package-lock.json

是否忽略 lockfile 取决于包管理器和团队约定。生成文件应优先由生成器维护，不要在每次提交时产生无意义的大范围格式变化。

package.json 脚本

{
  "scripts": {
    "format": "prettier . --write",
    "format:check": "prettier . --check"
  }
}

本地使用 npm run format 自动修复；CI 使用 npm run format:check 只检查、不修改仓库。

与 ESLint 的关系

Prettier 处理排版，ESLint 处理潜在错误和代码质量规则。避免让两者同时争夺引号、缩进、分号等纯格式规则。常见流程是：

1. EditorConfig 保证编辑器基础行为一致。
2. Prettier 负责格式化。
3. ESLint 检查 React Hooks、未使用变量和项目规则。
4. CI 分别执行类型检查、lint 和 format:check。

编辑器保存时格式化

VS Code 可以在项目的 .vscode/settings.json 中设置：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

团队配置应该放在仓库中，并在 README 说明需要的扩展。保存时自动修复很方便，但最终仍要依靠 CI，不能假设每个人都使用同一编辑器。

格式化只解决排版一致性；如果还需要约束提交信息和分支协作，可以继续阅读 Husky、Commitlint 与 Git 工作流指南。

常见冲突排查

• 缩进来回变化：检查 .editorconfig 的 indent_size 是否与 Prettier tabWidth 一致。
• 保存结果与 CLI 不同：确认编辑器插件使用项目本地 Prettier，而不是自带旧版本。
• 某个子目录规则不同：Prettier 从目标文件位置向上寻找配置；EditorConfig 也可能存在嵌套规则。
• Markdown 表格或代码块变化太大：先确认是否应该交给 Prettier，必要时精确加入 ignore。
• CI 一直失败：在本地运行与 CI 相同的 prettier . --check，不要只看编辑器提示。

参考资料

• EditorConfig 官方文档
• Prettier 配置文件文档
• Prettier 忽略文件文档