EditorConfig 配置指南

📖 概述

EditorConfig 是一个用于维护跨多个编辑器和 IDE 的一致编码风格的工具。本项目采用标准化的 EditorConfig 配置，确保团队成员在不同开发环境中获得一致的代码格式体验。

🎯 配置目标

• 统一代码风格：确保所有团队成员使用相同的缩进、换行符等格式
• 提高协作效率：减少因格式差异导致的代码审查问题
• 支持多种文件类型：覆盖 Go、JavaScript/TypeScript、YAML、Markdown 等
• 优化 IDE 体验：特别针对 JetBrains 系列 IDE 进行优化

🛠️ 支持的文件类型和标准

Go 语言

[*.go]
indent_style = tab
indent_size = 4

• 遵循 go fmt 官方标准
• 使用 Tab 缩进，缩进大小为 4
• 自动格式化导入语句

JavaScript/TypeScript/MTS

[*.{js,ts,jsx,tsx,mts}]
indent_style = space
indent_size = 2

• 遵循业界标准：2 空格缩进
• 支持 VitePress 的 .mts 配置文件
• 使用单引号，启用分号

YAML 文件

[*.{yml,yaml}]
indent_style = space
indent_size = 2

• 遵循 Kubernetes/Docker 标准
• 2 空格缩进，保持行分隔

JSON 文件

[*.{json,jsonc}]
indent_style = space
indent_size = 2

• 支持标准 JSON 和带注释的 JSONC
• NPM 包管理器标准：2 空格缩进

Markdown 文件

[*.md]
indent_style = space
indent_size = 2
trim_trailing_whitespace = false

• 特殊处理：禁用尾随空格移除（Markdown 语法需要）
• 禁用 JetBrains 代码检查：防止代码块误报错误

其他文件类型

• Protocol Buffers (.proto)：2 空格，遵循 Google 风格指南
• Shell 脚本 (.sh, .bash)：2 空格，POSIX 标准
• Makefile：Tab 缩进（必须使用 Tab）
• Docker：2 空格缩进

🚀 IDE 支持和启用方法

JetBrains 系列 (GoLand, IntelliJ IDEA, WebStorm)

自动启用：

• JetBrains IDE 默认支持 EditorConfig
• 检测到 .editorconfig 文件后自动应用配置

手动检查：

1. File → Settings → Editor → Code Style
2. 确保 Enable EditorConfig support 已勾选

VS Code

自动启用：

• VS Code 内置 EditorConfig 支持
• 无需额外配置

扩展推荐：

{
  "recommendations": ["editorconfig.editorconfig"]
}

Vim/Neovim

安装插件：

Plug 'editorconfig/editorconfig-vim'

其他编辑器

• Sublime Text: 安装 EditorConfig 包
• Atom: 安装 editorconfig 插件
• Emacs: 使用 editorconfig-emacs

📁 文件类型识别配置

特殊文件类型支持

项目配置支持以下特殊文件类型的正确识别：

JSONC (带注释的 JSON)

[*.{json,jsonc}]
indent_style = space
indent_size = 2

MTS (TypeScript 模块)

[*.{js,ts,jsx,tsx,mts}]
# VitePress 配置文件专用
[*.config.{js,ts,mts}]

自动生成文件排除

# 锁文件
[{*.lock,go.sum,package-lock.json,yarn.lock,pnpm-lock.yaml}]
insert_final_newline = unset
trim_trailing_whitespace = unset

# 生成目录
[{node_modules/**,gen/**,dist/**,build/**}]
indent_style = unset

IDE 文件关联配置

JetBrains IDE：

1. File → Settings → Editor → File Types
2. 为特殊扩展名添加正确的文件类型关联：
   • .jsonc → JSON
   • .mts → TypeScript

VS Code：

{
  "files.associations": {
    "*.jsonc": "jsonc",
    "*.mts": "typescript"
  }
}

🔧 配置优先级说明

EditorConfig 遵循以下优先级规则（从低到高）：

1. 全局默认 ([*])
2. 通用文件类型 ([*.yml], [*.js])
3. 特定文件 ([package.json], [go.mod])
4. 特定路径 ([.github/workflows/*.yml])
5. 排除配置 ([node_modules/**])

配置示例

# 通用 YAML 配置
[*.{yml,yaml}]
indent_style = space
indent_size = 2

# GitHub Actions 特定配置（优先级更高）
[.github/workflows/*.{yml,yaml}]
indent_style = space
indent_size = 2

🎨 JetBrains 特殊优化

Markdown 代码检查禁用

[*.md]
# 禁用代码块语言验证，防止误报
ij_markdown_force_one_space_between_words = false
ij_markdown_force_one_space_after_header_symbol = false
ij_any_line_comment_at_first_column = false

Go 语言集成

[*.go]
# 自动运行 go fmt
ij_go_run_go_fmt_on_reformat = true
# 导入语句优化
ij_go_import_sorting = definition
ij_go_move_all_stdlib_imports_in_one_group = true

📋 最佳实践

团队协作

1. 统一 IDE 设置：确保所有团队成员启用 EditorConfig 支持
2. 定期同步：当 .editorconfig 更新时，通知团队重启 IDE
3. 代码审查：在 PR 中检查格式一致性

项目维护

1. 格式化命令：

   # Go 代码格式化
   gofmt -w .
   
   # 检查配置应用
   git diff --check

2. CI/CD 集成：

   - name: Check code formatting
     run: |
       gofmt -l . | grep . && exit 1 || exit 0

新文件类型支持

当项目引入新的文件类型时：

1. 研究最佳实践：查找该语言/工具的官方风格指南
2. 更新配置：在 .editorconfig 中添加相应规则
3. 测试验证：确保配置在主要 IDE 中正常工作
4. 文档更新：更新本指南内容

🔍 故障排除

常见问题

配置不生效：

• 检查 IDE 是否启用 EditorConfig 支持
• 重启 IDE 使配置生效
• 确认 .editorconfig 文件语法正确

格式化冲突：

• 检查是否存在其他格式化工具（如 Prettier）的配置冲突
• 确认配置优先级是否正确设置

特殊文件类型不识别：

• 检查 IDE 的文件类型关联设置
• 考虑安装相应的语言插件

验证配置

# 检查 EditorConfig 配置是否正确应用
editorconfig-checker

# 验证特定文件的配置
editorconfig /path/to/file

📚 参考资料

• EditorConfig 官方文档
• JetBrains EditorConfig 支持
• Go 代码格式规范
• TypeScript 代码风格指南
• YAML 规范

---

💡 提示：本配置遵循各语言生态的主流标准，确保与常用工具（如 go fmt、Prettier 等）的兼容性。