使用 EditorConfig 创建可移植的自定义编辑器设置

  • 项目

适用范围：yesVisual Studio noVisual Studio for Mac noVisual Studio Code

可以向项目或基本代码添加 EditorConfig 文件，强制对使用该基本代码的所有人实施一致的编码样式。 EditorConfig 设置优先于全局 Visual Studio 文本编辑器设置。 这意味着，可以调整每种基本代码，以使用特定于该项目的文本编辑器设置。 仍然可以在 Visual Studio“选项”对话框中设置个人编辑器首选项。 以下两种情况下将应用这些设置：每当在不具备 .editorconfig 文件的代码库中执行操作时，或者当 .editorconfig 文件不会替代特定设置时 。 此类首选项的示例是缩进样式- 制表符或空格。

许多代码编辑器和 IDE（包括 Visual Studio）都支持 EditorConfig 设置。 它是一种随代码移动的可移植组件，甚至可以在 Visual Studio 外强制实施编码样式。

在 Visual Studio 中将 EditorConfig 文件添加到项目中时，将基于 EditorConfig 设置设置新代码行。 除非运行以下命令之一，否则不会更改现有代码的格式：

  • 代码清理 (Ctrl+K、 Ctrl+E) ，用于应用任何空白设置，例如缩进样式和所选代码样式设置，例如如何对指令进行排序 using 。
  • 编辑>先进>设置文档 (或 CtrlK、默认配置文件中的 Ctrl++D 格式) ，仅应用空格设置，例如缩进样式。

注意

本主题适用于 Visual Studio Windows 版。 对于 Visual Studio for Mac，请参阅Visual Studio for Mac 中的 EditorConfig。

代码一致性

使用 EditorConfig 文件中的设置，可以在代码库中保持一致的编码样式和设置，例如缩进样式、选项卡宽度、行尾字符、编码等，而不考虑使用的编辑器或 IDE。 例如，使用 C# 编码时，如果基本代码约定为始终缩进五个空格字符、文档使用 UTF-8 编码，且每一行始终以 CR/LF 结束，则可以配置 .editorconfig 文件达到此效果。

对个人项目使用的编码约定可能与团队项目中使用的约定不同。 例如，你可能倾向在编码时，缩进操作会添加制表符。 但你的团队可能更倾向使用四个空格字符的缩进，而不是制表符。 EditorConfig 文件通过为每个方案提供配置来解决此问题。

由于代码库中的文件包含设置，因此它们随该代码库一起传输。 只要在符合 EditorConfig 的编辑器中打开代码文件，文本编辑器设置将激活。 有关 EditorConfig 文件的详细信息，请参阅 EditorConfig.org 网站。

注意

在 EditorConfig 文件中设置的约定当前无法在 CI/CD 管道中强制实施为生成错误或警告。 任何样式偏差都仅显示在 Visual Studio 编辑器和“错误列表”中。

支持的设置

Visual Studio 中的编辑器支持 EditorConfig 属性的核心集：

  • indent_style
  • indent_size
  • tab_width
  • end_of_line
  • charset
  • trim_trailing_whitespace
  • insert_final_newline
  • root

除 XML 支持 EditorConfig 编辑器设置外，所有 Visual Studio 支持的语言。 此外，EditorConfig 还支持 代码样式 约定，包括 C# 和 Visual Basic 的语言、 格式设置和 命名 约定。

添加和删除 EditorConfig 文件

向项目或基本代码添加 EditorConfig 文件后，将按照 EditorConfig 文件设置编写的所有新代码行的格式。 但是，在设置文档格式或运行 代码清理之前，添加 EditorConfig 文件不会将现有样式转换为新样式。 例如，如果文件中的缩进格式为选项卡，并且添加带有空格的缩进的 EditorConfig 文件，则缩进字符不会自动转换为空格。 在设置文档格式 (编辑>高级>格式文档 或 Ctrl+K、 Ctrl+D) 时，EditorConfig 文件中的空白设置将应用于现有代码行。

如果从项目或基本代码库中删除 EditorConfig 文件，并想要使用全局编辑器设置设置新代码行的格式，必须关闭并重新打开任何打开的代码文件。

将 EditorConfig 文件添加到项目

  1. 在 Visual Studio 中打开项目或解决方案。 根据要应用 .editorconfig 设置的对象（是解决方案中的所有项目还是其中一个项目），选择项目或解决方案节点。 还可在项目或解决方案中选择一个文件夹，向其添加 .editorconfig 文件。

  2. 从菜单栏中，选择“项目”>“添加新项”，或按 Ctrl+Shift+A 。

    此时将打开“添加新项”对话框。

  3. 在搜索框中，搜索“editorconfig”。

    搜索结果将显示两个 editorconfig 文件项模板。

    显示 Visual Studio 中的 EditorConfig 文件项模板的屏幕截图。

  4. 选择“editorconfig 文件(默认)”模板，添加使用针对缩进样式和尺寸的两个核心 EditorConfig 选项预填充的 EditorConfig 文件。 或者，选择“editorconfig 文件(.NET)”模板，添加使用默认的 .NET 代码样式、格式设置和命名约定预填充的 EditorConfig 文件。

    解决方案资源管理器中随即显示一个 .editorconfig 文件，且文件在编辑器中打开。

    显示解决方案资源管理器和编辑器中的 .editorconfig 文件的屏幕截图。

  5. 根据需要编辑文件。

添加 EditorConfig 文件的其他方式

可通过多种其他方法将 EditorConfig 文件添加到项目中：

文件层次结构和优先级

如果将 .editorconfig 文件添加到文件层次结构中的某文件夹，则其设置将应用于该级别及更低级别的所有适用文件。 还可替代特定项目、代码库或部分代码库的 EditorConfig 设置，以使其使用与代码库其他部分不同的约定。 当要包含其他地方的代码而不想更改其约定时，这会很有用。

若要替代部分或全部 EditorConfig 设置，请在要应用这些替代设置的文件层次结构级别添加 .editorconfig 文件。 新的 EditorConfig 文件设置应用于同级目录和任何子目录中的文件。

显示 EditorConfig 层次结构的屏幕截图。

如果要重写某些设置，但并非所有设置，只需在 .editorconfig 文件中指定这些设置。 仅替代较低级别文件中显式列出的属性。 更高级别 .editorconfig 文件中的其他设置会继续应用。

如果想要确保任何更高级别的 .editorconfig 文件中的任何设置都未应用于代码库的这一部分，请将该 root=true 属性添加到较低级别的 .editorconfig 文件：

# top-most EditorConfig file
root = true

从上到下读取 EditorConfig 文件。 如果有多个具有相同名称的属性，则最近找到的具有该名称的属性具有优先权。

编辑 EditorConfig 文件

Visual Studio 提供 IntelliSense 完成列表，帮助你编辑 .editorconfig 文件。

显示 .editorconfig 文件中 IntelliSense 的屏幕截图。

编辑 EditorConfig 文件后，必须重载代码文件，新设置才会生效。

如果编辑许多 .editorconfig 文件，你可能会发现 EditorConfig 语言服务扩展 很有用。 该扩展的一些功能包括语法高亮显示、改进的 IntelliSense、验证和代码格式。

显示带有 EditorConfig 语言服务扩展的 IntelliSense 的屏幕截图。

示例

以下示例演示将 .editorconfig 文件添加到项目之前和之后 C# 代码片段的缩进状态。 Visual Studio 文本编辑器“选项”对话框中的“Tab”设置设置为按 Tab 键时可生成空格字符。

显示“文本编辑器”选项卡设置的屏幕截图。

按预期，按下一行的 Tab 键会通过添加另外四个空格字符来缩进该行。

显示使用 EditorConfig 之前代码的屏幕截图。

将具有以下内容的名为 .editorconfig 的新文件添加到项目。 [*.cs] 设置意味着此更改仅应用于项目中的 C# 代码文件。

# Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

现在按 Tab 键时，会获得制表符而不是空格。

显示 Tab 键添加制表符的屏幕截图。

EditorConfig 设置疑难解答

如果在目录结构中处于或高于你项目所在位置的任何位置存在 EditorConfig 文件，则 Visual Studio 会将该文件中的编辑器设置应用于编辑器。 在这种情况下，你可能会在状态栏中看到以下消息：

User preferences for this file type are overridden by this project's coding conventions.

这意味着如果目录结构中与项目位于相同位置或在项目之上的某个 EditorConfig 文件中指定了“工具”>“选项”>“文本编辑器”中的任何编辑器设置（如缩进尺寸和样式、制表符大小或编码约定），则 EditorConfig 文件中的约定会替代“选项”中的设置 。 可以通过在“工具”>“选项”>“文本编辑器”中切换“遵循项目编码约定”选项来控制此行为。 取消选中该选项会关闭 Visual Studio 的 EditorConfig 支持。

显示工具选项的屏幕截图 - 遵循项目编码约定。

还可以通过打开命令提示符并从包含项目的磁盘的根目录运行以下命令，在父目录中查找任何 .editorconfig 文件：

dir .editorconfig /s

可以通过在存储库的根目录或项目所在目录的 .editorconfig 文件中设置 root=true 属性，控制 EditorConfig 约定的范围。 Visual Studio 会在打开的文件的目录和每个父目录中查找名为 .editorconfig 的文件。 到达根文件路径时或找到具有 root=true 的 .editorconfig 文件时搜索结束。

请参阅