Visual Studio C++ 默认 UTF-8 编码及 *.editorconfig 统一代码格式

转载请注明原文链接：https://www.cnblogs.com/mechanicoder/p/16894144.html

1. 问题由来

背景：团队使用 Visual Studio 进行跨平台项目开发。

遇到的问题：

编码：Windows平台下源代码文件格式可能是 GBK、IBM866、UTF16LE、UTF-8等等，中文字符串、注释等跨平台编译时出现乱码；

转码：Visual Studio 根据源代码内容、系统区域设置（即本地化）自动确定源代码编码格式，含中文字符时存在不确定性；代码中英字符串处理时需要格式来回转换，例如 ANSI->UTF8，无法统一；

规范：由于团队成员个人 Visual Studio 编码格式配置可能不同，例如 switch case 语句中的 case 是否缩进以及缩进量，经常遇到对源代码反复以不同风格进行格式化的情况；（文档格式化快捷键 Ctrl+K,D；选中内容格式化快捷键 Ctrl+K,F）Visual Studio 虽然可以使用团队统一配置，但修改不方便、修改内容无法高效的同步。

2. 解决方法

2.1. 文件编码问题

首先，Visual Studio 代码编辑器支持多种编码格式，这从 Visual Studio 带格式保存文件选项可以看出来。

图1. 源码高级保存选项

关键在于如何让 Visual Studio 始终以 UTF-8 为默认编码格式，而非由 IDE 本地化自动判断，避免手动更改编码格式。该问题在一个回答中找到了靠谱的解决方法（如何配置可以让 Visual Studio 默认以 UTF-8 格式编码且全局有效）。即通过一个可移植、可定制的文本编辑器配置文件 .editorconfig 对编辑器进行配置，以下引用回答内容：

Visual Studio supports EditorConfig files (EditorConfig)

Visual Studio (VS2017 and later) searches for a file named '.editorconfig' in the directory containing your source files, or anywhere above this directory in the hierarchy. This file can be used to direct the editor to use utf-8. I use the following:
[*]
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
indent_style = space
indent_size = 4
The [*] line is a mask and means for all files - the scope of the commands can be reduced using e.g. [*.{h,cpp}]

There are further possibilities, particularly for C# files. Full details can be found at EditorConfig settings - Visual Studio (Windows) | Microsoft Learn

根据 Visual Studio 官方介绍，Visual Studio 启动时将会自动从源码文件所在文件夹开始搜索该文件，直至找到位于顶层目录的文件或没有找到。因此使用时将其放在代码仓库的根目录即可。

图2. 代码目录结构--图片来自 Visual Studio 官网

那么，是否可以自动生成一个 .editorconfig 文件呢？

Visual Studio 支持根据本地设置生成一个 .editorconfig 文件，操作路径为：

Tools / Options / Text Editor / C/C++ / Code Stype / General: Generate .editorconfig file from settings.

图3. 生成 .editorconfig 文件，截图来自 Microsoft Visual Studio Community 2022 (64-bit) - Current Version 17.2.1

得到 .editorconfig 之后就可以进行配置了，例如上述回答中的含义分别时（以下内容是 .editorconfig 的一部分，配置文件支持以 # 开始的注释）：

[*]
end_of_line = lf                    # 行尾 UNIX 格式 LF
charset = utf-8                     # 文件编码字符集为 UTF-8
trim_trailing_whitespace = true     # 删除文件末尾空格
insert_final_newline = true         # 末尾插入新行
indent_style = space                # 以空格代替 tab
indent_size = 4                     # 代替 tab 的空格数量

Visual Studio 支持的特性 VS官网链接，或 editorconfig官网链接。

如何将已有文件转码：实现Python脚本，按原编码读入数据并按 UTF-8 格式写出即可。

注意：配置文件修改后需要重启 Visual Studio，通过文档格式化(Ctrl+K,D)判断配置是否生效，如查看格式化前后的空格数量。

2.2. 编译问题

自动转码后编译时可能遇到各种异常编译的错误或警告（如4819），这些错误是由于 Visual Studio 未按 UTF-8 格式进行编译导致的。既然文本编辑器支持以 UTF-8 编码的源文件，那么编译器也必然支持以 UTF-8 编码格式解析源文件。

这里需要指定编译选项 /utf-8 告诉编译器以 UTF-8 对源文件进行解码，可参考官方文档。

直接通过 Visual Studio 配置项目时，进行如下设置：

图4. 指定 /utf-8 编译选项，截图来自 Microsoft Visual Studio Community 2022 (64-bit) - Current Version 17.2.1

通过 CMake 配置项目时，cmake 脚本指令：

set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /utf-8")

指定 /utf-8 编译选项后，当编译文件或由源文件所包含的头文件非 UTF-8 编码时，将会出现大量如下警告信息，他们可以通过 Visual Studio 禁用警告编号选项关闭。

warning C4828: The file contains a character starting at offset 0x453 that is illegal in the current source character set (codepage 65001).

或通过 cmake 脚本指令：

add_compile_options(/wd4828)

2.3. 其他方法[不建议]

关于编译警告4819的问题，有网友回答（原回答链接）可通过修改系统本地化设置解决，经测试确实可修复，设置路径如下：

控制面板 / 时钟 / 区域 / 区域 / 管理 / 更改系统区域设置，使用Unicode UTF8提供全球语言支持

图5. 更改系统区域设置

这种解决方法存在副作用。本地化是系统全局设置，可能将影响其他应用程序，当然微软自家的应用程序相信都已经做了很好的适配。作者电脑上一款软件中文版就在执行上述设置后出现了乱码，英文版正常。

此外，2.1 中所述的指定编译选项 /utf-8 同样可以解决该警告问题，因此不建议更改系统区域设置。

参考资料

1. How to config visual studio to use UTF-8 as the default encoding for all projects? - Stack Overflow

2. EditorConfig

3. EditorConfig settings - Visual Studio (Windows) | Microsoft Learn

4. /utf-8 (Set source and execution character sets to UTF-8) | Microsoft Learn

5. [Solved]-warning c4819 in Visual Studio C++ 2013 express - utf8 files without bom-C++

6. cmake 添加编译选项的几种方式 - 简书

7. VS CMake 禁止警告 - 心灵捕手 - 博客园