使用 EditorConfig 建立可攜式自訂編輯器設定Create portable, custom editor settings with EditorConfig

您可以將 EditorConfig 檔案新增至您的專案或程式碼基底,以針對程式碼基底中的所有人,強制執行一致的編碼樣式。You can add an EditorConfig file to your project or codebase to enforce consistent coding styles for everyone that works in the codebase. EditorConfig 設定優先於全域 Visual Studio 文字編輯器設定。EditorConfig settings take precedence over global Visual Studio text editor settings. 這表示您可以自訂每個程式碼基底,以使用該專案專屬的文字編輯器設定。This means that you can tailor each codebase to use text editor settings that are specific to that project. 您仍然可以在 Visual Studio 的 [選項] 對話方塊中設定自己的個人編輯器喜好設定。You can still set your own personal editor preferences in the Visual Studio Options dialog box. 每當您使用沒有 .editorconfig 檔案的程式碼基底時,或 .editorconfig 檔案不覆寫特定設定時,就會套用那些設定。Those settings apply whenever you're working in a codebase without an .editorconfig file, or when the .editorconfig file doesn't override a particular setting. 縮排樣式—定位點或空格,即為這類喜好設定的範例之一。An example of such a preference is indent style—tabs or spaces.

許多程式碼編輯器和 IDE,包括 Visual Studio,都支援 EditorConfig 設定。EditorConfig settings are supported by numerous code editors and IDEs, including Visual Studio. 它是隨附於程式碼的可攜式元件,甚至可以強制規範 Visual Studio 之外的編碼樣式。It's a portable component that travels with your code, and can enforce coding styles even outside of Visual Studio.

當您將 EditorConfig 檔案新增至 Visual Studio 中的專案時,會根據 EditorConfig 設定將新的程式程式碼格式化。When you add an EditorConfig file to your project in Visual Studio, new lines of code are formatted according to the EditorConfig settings. 除非您執行下列其中一個命令,否則不會變更現有程式碼的格式:The formatting of existing code is not changed unless you run one of the following commands:

  • 程式 代碼清除 (ctrl + Kctrl + E) ,它會套用任何空白字元設定,例如縮排樣式和選取的程式碼樣式設定,例如如何排序指示詞 usingCode Cleanup (Ctrl+K, Ctrl+E), which applies any white space settings, such as indent style, and selected code style settings, such as how to sort using directives.
  • 編輯 >Advanced >將檔 格式化 (或 ctrl + Kctrl + D (預設設定檔) 中),此設定檔只會套用空白字元設定,例如縮排樣式。Edit > Advanced > Format Document (or Ctrl+K, Ctrl+D in the default profile), which only applies white space settings, such as indent style.

當您將 EditorConfig 檔案新增至 Visual Studio 中的專案時,會根據 EditorConfig 設定將新的程式程式碼格式化。When you add an EditorConfig file to your project in Visual Studio, new lines of code are formatted according to the EditorConfig settings. 除非您將檔案格式化 (在 Edit > Advanced > 預設設定檔) 中編輯 Advanced format 檔ctrl + Kctrl + D ,否則不會變更現有程式碼的格式。The formatting of existing code is not changed unless you format the document (Edit > Advanced > Format Document or Ctrl+K, Ctrl+D in the default profile). 除非您已設定格式檔以 執行額外的程式碼清除,否則檔的格式設定只會影響泛空白字元設定,例如縮排樣式。Formatting the document only affects white space settings, such as indent style, unless you've configured Format Document to perform additional code cleanup.

您可在 [格式化] 選項頁面定義您希望 將文件格式化 套用哪些 EditorConfig 設定。You can define which EditorConfig settings you want Format Document to apply on the Formatting options page.

注意

本主題適用於 Windows 上的 Visual Studio。This topic applies to Visual Studio on Windows. 針對 Visual Studio for Mac,請參閱 Visual Studio for Mac 中的 EditorConfigFor Visual Studio for Mac, see EditorConfig in Visual Studio for Mac.

程式碼一致性Code consistency

EditorConfig 檔案中的設定可讓您在程式碼基底中維持一致的編碼樣式及設定,例如縮排樣式、Tab 跳位寬度、行結尾字元、編碼等等,而不論您使用的編輯器或 IDE 為何。Settings in EditorConfig files enable you to maintain consistent coding styles and settings in a codebase, such as indent style, tab width, end of line characters, encoding, and more, regardless of the editor or IDE you use. 例如,當以 C++ 撰寫程式碼時,如果您的程式碼基底慣例偏好縮排一律包含五個空白字元、文件使用 UTF-8 編碼方式,且每一行的結尾一律為 CR/LF,您可以設定 .editorconfig 檔案來做到這點。For example, when coding in C#, if your codebase has a convention to prefer that indents always consist of five space characters, documents use UTF-8 encoding, and each line always ends with a CR/LF, you can configure an .editorconfig file to do that.

您在個人專案上使用的編碼慣例,可能與用於小組專案的不同。Coding conventions you use on your personal projects may differ from those used on your team's projects. 例如,您在編寫程式碼時,可能會偏好縮排時新增定位字元。For example, you might prefer that when you're coding, indenting adds a tab character. 不過,您的小組可能會偏好縮排時新增四個空白字元,而不是定位字元。However, your team might prefer that indenting adds four space characters instead of a tab character. EditorConfig 檔案讓您能擁有每個案例的組態,以解決此問題。EditorConfig files resolve this problem by enabling you to have a configuration for each scenario.

因為設定是包含在程式碼基底的檔案中,所以它們會隨著該程式碼基底四處移動。Because the settings are contained in a file in the codebase, they travel along with that codebase. 只要您在符合 EditorConfig 規範的編輯器中開啟程式碼檔案,便會實作文字編輯器設定。As long as you open the code file in an EditorConfig-compliant editor, the text editor settings are implemented. 如需 EditorConfig 檔案的詳細資訊,請參閱 EditorConfig.org 網站。For more information about EditorConfig files, see the EditorConfig.org website.

注意

由於建置錯誤或警告,目前無法在 CI/CD 管線中強制執行 EditorConfig 中設定的慣例。Conventions that are set in an EditorConfig file cannot currently be enforced in a CI/CD pipeline as build errors or warnings. 任何樣式偏差只會顯示在 Visual Studio 編輯器中和 [錯誤清單] 中。Any style deviations appear only in the Visual Studio editor and Error List.

支援的設定Supported settings

Visual Studio 中的編輯器支援 EditorConfig 屬性的核心集:The editor in Visual Studio supports the core set of EditorConfig properties:

  • indent_styleindent_style
  • indent_sizeindent_size
  • tab_widthtab_width
  • end_of_lineend_of_line
  • 字元集charset
  • trim_trailing_whitespacetrim_trailing_whitespace
  • insert_final_newlineinsert_final_newline
  • rootroot

除了 XML 以外的所有 Visual Studio 支援語言都支援 EditorConfig 編輯器設定。EditorConfig editor settings are supported in all Visual Studio-supported languages except for XML. 此外,EditorConfig 支援程式碼樣式慣例,包括 C# 和 Visual Basic 的語言格式命名 慣例。In addition, EditorConfig supports code style conventions including language, formatting, and naming conventions for C# and Visual Basic.

新增及移除 EditorConfig 檔案Add and remove EditorConfig files

當您將 EditorConfig 檔案新增至專案或程式碼基底之後,您撰寫的任何新程式碼都會根據 EditorConfig 檔案設定格式。When you add an EditorConfig file to your project or codebase, any new lines of code you write are formatted according to the EditorConfig file. 不過,在您格式化檔或執行程式 代碼清除之前,新增 EditorConfig 檔案並不會將現有的樣式轉換為新的樣式。However, adding an EditorConfig file does not convert existing styles to the new ones until you format the document or run Code Cleanup. 例如,如果您在檔案中使用了定位字元設定格式的縮排,而且新增了以空格縮排的 EditorConfig 檔案,縮排字元不會自動轉換為空格。For example, if you have indents in your file that are formatted with tabs and you add an EditorConfig file that indents with spaces, the indent characters are not automatically converted to spaces. 當您將檔案格式化 (編輯 > Advanced > format 檔ctrl + Kctrl + D) 時,EditorConfig 檔案中的空白字元設定會套用至現有的程式程式碼。When you format the document (Edit > Advanced > Format Document or Ctrl+K, Ctrl+D), the white space settings in the EditorConfig file are applied to existing lines of code.

如果您從專案或程式碼基底移除了 EditorConfig 檔案,且想要依照全域編輯器設定為新的程式碼設定格式,就必須關閉並重新開啟任何開啟的程式碼檔案。If you remove an EditorConfig file from your project or codebase and you want new lines of code to be formatted according to the global editor settings, you must close and reopen any open code files.

將 EditorConfig 檔案新增至專案Add an EditorConfig file to a project

  1. 在 Visual Studio 中開啟專案或解決方案。Open a project or solution in Visual Studio. 選取專案或解決方案節點,視您的 .editorconfig 設定應套用至解決方案中的所有專案或僅只一個專案而定。Select either the project or solution node, depending on whether your .editorconfig settings should apply to all projects in the solution or just one. 您也可以選取專案或解決方案中的資料夾,將 .editorconfig 檔案新增到此資料夾。You can also select a folder in your project or solution to add the .editorconfig file to.

  2. 從功能表列中,選擇 [ Project > 加入新專案] 或按 Ctrl + Shift + AFrom the menu bar, choose Project > Add New Item, or press Ctrl+Shift+A.

    [ 加入新專案 ] 對話方塊隨即開啟。The Add New Item dialog box opens.

  3. 在搜尋方塊中搜尋 editorconfigIn the search box, search for editorconfig.

    搜尋結果中會顯示兩個 editorconfig 檔案 項目範本。Two editorconfig File item templates are shown in the search results.

    Visual Studio 中的 EditorConfig 檔案項目範本

  4. 選取 editorconfig 檔案 (預設值) 範本,以新增已填入兩個核心 EditorConfig 選項 (縮排樣式和大小) 的 EditorConfig 檔案。Select the editorconfig File (default) template to add an EditorConfig file prepopulated with two core EditorConfig options for indent style and size. 或者,選取 editorconfig 檔案 (.NET) 範本,以新增已填入兩個預設 .NET 程式碼樣式、格式和命名慣例的 EditorConfig 檔案。Or, select the editorconfig File (.NET) template to add an EditorConfig file prepopulated with default .NET code style, formatting, and naming conventions.

    .editorconfig 檔案隨即出現在 [方案總管] 中,並在編輯器中開啟。An .editorconfig file appears in Solution Explorer, and it opens in the editor.

    方案總管和編輯器中的 .editorconfig 檔案

  5. 依需要編輯檔案。Edit the file as desired.

新增 EditorConfig 檔案的其他方式Other ways to add an EditorConfig file

將 EditorConfig 檔案新資到您專案的方式有數種:There are a couple other ways you can add an EditorConfig file to your project:

檔案階層和優先順序File hierarchy and precedence

當您將 editorconfig 檔案新增到檔案階層中的資料夾時,其設定會套用到該層級和以下層級的所有適用檔案。When you add an .editorconfig file to a folder in your file hierarchy, its settings apply to all applicable files at that level and below. 您也可以覆寫特定專案、程式碼基底,或程式碼基底組件的 EditorConfig 設定,這樣它就會使用和其他程式碼基底組件不同的慣例。You can also override EditorConfig settings for a particular project, codebase, or part of a codebase, such that it uses different conventions than other parts of the codebase. 當您納入來自其他地方的程式碼,但不想變更其慣例時,這非常有用。This can be useful when you incorporate code from somewhere else, and don’t want to change its conventions.

若要覆寫部分或全部的 EditorConfig 設定,請將 .editorconfig 檔案新增至您想要套用這些覆寫設定的檔案階層層級。To override some or all of the EditorConfig settings, add an .editorconfig file at the level of the file hierarchy you want those overridden settings to apply. 新的 EditorConfig 檔案設定會套用到相同層級和任何子目錄中的檔案。The new EditorConfig file settings apply to files at the same level and any subdirectories.

EditorConfig 階層

如果您想要覆寫部分(而非全部)設定,請只在 editorconfig 檔中指定這些設定。If you want to override some but not all of the settings, specify just those settings in the .editorconfig file. 只有明確列在較低層級檔案中的屬性才會被覆寫。Only those properties that you explicitly list in the lower-level file are overridden. 較高層級 editorconfig 檔案中的其他設定仍會繼續套用。Other settings from higher-level .editorconfig files continue to apply. 如果想要確保「不」套用「任何」較高層級 .editorconfig 檔案的設定到此程式碼基底組件,請在較低層級的 .editorconfig 檔案中新增 root=true 屬性:If you want to ensure that no settings from any higher-level .editorconfig files are applied to this part of the codebase, add the root=true property to the lower-level .editorconfig file:

# top-most EditorConfig file
root = true

EditorConfig 檔案會由上到下讀取。EditorConfig files are read top to bottom. 如果有多個具有相同名稱的屬性,則最近找到具有該名稱的屬性優先。If there are multiple properties with the same name, the most recently found property with that name takes precedence.

編輯 EditorConfig 檔案Edit EditorConfig files

Visual Studio 可透過提供 IntelliSense 完成清單協助您編輯 .editorconfig 檔案。Visual Studio helps you edit .editorconfig files by providing IntelliSense completion lists.

.editorconfig 檔案中的 IntelliSense

在編輯您的 EditorConfig 檔案後,您必須重新載入程式碼檔,新的設定才會生效。After you've edited your EditorConfig file, you must reload your code files for the new settings to take effect.

如果您編輯許多 .editorconfig 檔案,可能會發現 EditorConfig 語言服務延伸模組很有幫助。If you edit numerous .editorconfig files, you may find the EditorConfig Language Service extension helpful. 這項延伸模組有部分功能包括語法反白顯示、 改善的 IntelliSense、驗證和程式碼格式化。Some of the features of this extension include syntax highlighting, improved IntelliSense, validation, and code formatting.

具有 EditorConfig 語言服務延伸模組的 IntelliSense

範例Example

下列範例顯示 C# 程式碼片段在將 .editorconfig 檔案新增至專案之前和之後的縮排狀態。The following example shows the indent state of a C# code snippet before and after adding an .editorconfig file to the project. Visual Studio 文字編輯器 [選項] 對話方塊的 [定位字元] 設定已設為在按下 Tab 鍵時,產生空白字元。The Tabs setting in the Options dialog box for the Visual Studio text editor is set to produce space characters when you press the Tab key.

文字編輯器定位字元設定

如同預期,在下一行按下 Tab 鍵會透過新增四個額外的空白字元來縮排該行。As expected, pressing the Tab key on the next line indents the line by adding four additional white-space characters.

使用 EditorConfig 前的程式碼

將名為 editorconfig 的新檔案新增至專案,並包含下列內容。Add a new file called .editorconfig to the project, with the following contents. [*.cs] 設定表示這項變更只會套用到此專案中的 C# 程式碼檔案。The [*.cs] setting means that this change applies only to C# code files in the project.

# Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

現在,當您按下 tab 鍵時,就會得到定位字元而不是空格。Now, when you press the Tab key, you get tab characters instead of spaces.

以 TAB 鍵新增定位字元

疑難排解 EditorConfig 設定Troubleshoot EditorConfig settings

如果目錄結構中的任何位置或在專案位置上方有一個 EditorConfig 檔案,Visual Studio 會將該檔案中的編輯器設定套用到您的編輯器。If there is an EditorConfig file anywhere in the directory structure at or above your project's location, Visual Studio applies the editor settings in that file to your editor. 在此情況下,您可能會看到狀態列中出現下列訊息:In this case, you may see the following message in the status bar:

「此檔案類型的使用者偏好由此專案的編碼慣例覆寫。」"User preferences for this file type are overridden by this project's coding conventions."

這表示,如果 [工具 > 選項 > 文字編輯器] 中的任何編輯器設定 (例如,縮排大小和樣式、索引標籤大小或編碼慣例) 是在目錄結構中專案的 EditorConfig 檔中指定,則 EditorConfig 檔中的慣例會覆寫 [選項] 中的設定。This means that if any editor settings in Tools > Options > Text Editor (such as indent size and style, tab size, or coding conventions) are specified in an EditorConfig file at or above the project in the directory structure, the conventions in the EditorConfig file override the settings in Options. 您可以透過切換 [工具] > [選項] > [文字編輯器] 中的 [遵循專案編碼慣例] 選項來控制這個行為。You can control this behavior by toggling the Follow project coding conventions option in Tools > Options > Text Editor. 取消選取此選項會關閉 Visual Studio 的 EditorConfig 支援。Unchecking the option turns off EditorConfig support for Visual Studio.

編碼選項 - 遵循專案編碼慣例

您可以藉由開啟命令提示字元,並從包含專案的磁片根目錄中執行下列命令,在父目錄中尋找任何 editorconfig 檔案:You can find any .editorconfig files in parent directories by opening a command prompt and running the following command from the root of the disk that contains your project:

dir .editorconfig /s

您可以在存放庫根目錄或專案所在目錄的 .editorconfig 檔案中設定 root=true 屬性,以控制 EditorConfig 慣例範圍。You can control the scope of your EditorConfig conventions by setting the root=true property in the .editorconfig file at the root of your repo or in the directory that your project resides. Visual Studio 會在已開啟檔案的目錄和每個父目錄中尋找名為 .editorconfig 的檔案。Visual Studio looks for a file named .editorconfig in the directory of the opened file and in every parent directory. 達到根檔案路徑,或者如果找到 root=true.editorconfig 檔案時,搜尋就會結束。The search ends when it reaches the root filepath, or if an .editorconfig file with root=true is found.

另請參閱See also