【CMake 】[第九篇] 解决 CMake + Visual Studio 中文乱码问题完整指南

解决 CMake + Visual Studio 中文乱码问题完整指南

前言

在使用 CMake 生成 Visual Studio 工程后，很多开发者会遇到一个常见问题：程序运行时，控制台输出的中文字符显示为乱码。这个问题看似简单，但实际上涉及到文件编码、编译器设置和运行时环境等多个方面。本文将深入分析问题原因，并提供完整的解决方案。

问题现象

当你使用以下命令生成 VS 工程：

bash 复制代码

mkdir build
cd build
cmake ..

然后在 Visual Studio 中编译运行包含中文输出的程序时，可能会看到类似这样的乱码：

复制代码

浣犲ソ锛屼笘鐣岋紒

而不是期望的：

复制代码

你好，世界！

问题根源分析

1. 源代码文件编码问题

UTF-8 vs GBK：现代编辑器（如 VS Code、Visual Studio）默认使用 UTF-8 编码保存文件
编译器默认行为：MSVC 编译器默认使用系统代码页（Windows 中文系统通常是 GBK/GB2312，代码页 936）来解析源文件
编码不匹配：当 UTF-8 编码的源文件被当作 GBK 解析时，中文字符就会变成乱码

2. Windows 控制台编码问题

默认代码页：Windows 控制台默认使用系统代码页（中文系统为 GBK，代码页 936）
输出编码不匹配：如果程序输出 UTF-8 编码的中文字符，但控制台期望 GBK 编码，就会显示乱码

3. Visual Studio 项目字符集设置

MBCS vs Unicode：VS 项目默认使用多字节字符集（MBCS），而不是 UTF-8
编译选项缺失：没有明确告诉编译器使用 UTF-8 编码

完整解决方案

方案一：在 CMakeLists.txt 中设置 UTF-8（推荐）

这是最根本的解决方案，确保编译器正确处理 UTF-8 编码的源文件。

步骤 1：修改 CMakeLists.txt

在 CMakeLists.txt 的项目定义之后添加以下配置：

cmake 复制代码

# CMake 最低版本要求
cmake_minimum_required(VERSION 3.10)

# 项目名称和语言
project(MyProject LANGUAGES CXX)

# ========== 解决中文乱码问题 ==========
# 设置源文件编码为 UTF-8
if(MSVC)
    # 对于 Visual Studio，设置源文件使用 UTF-8 编码
    # /utf-8 选项告诉编译器将源文件和执行字符集都视为 UTF-8
    add_compile_options(/utf-8)
    # 设置执行字符集为 UTF-8（可选，/utf-8 已包含此功能）
    add_compile_definitions(_UTF8_SOURCE)
endif()

# 其他配置...
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 添加可执行文件
add_executable(myapp main.cpp)

关键说明

/utf-8 选项：
- 适用于 Visual Studio 2015 及更高版本
- 同时设置源文件编码和执行字符集为 UTF-8
- 这是 MSVC 推荐的 UTF-8 支持方式
_UTF8_SOURCE 宏：
- 可选，用于明确标识使用 UTF-8 源文件
- 某些库可能会检查此宏

方案二：在代码中设置控制台代码页

即使编译器正确处理了源文件，Windows 控制台仍可能无法正确显示 UTF-8 输出。需要在运行时设置控制台代码页。

步骤 2：修改源代码

在包含中文输出的源文件（通常是 main.cpp）中添加控制台代码页设置：

cpp 复制代码

#include <iostream>
#ifdef _WIN32
#include <windows.h>
#endif

int main() {
#ifdef _WIN32
    // 设置控制台代码页为 UTF-8，解决中文乱码问题
    // 65001 是 UTF-8 的代码页编号
    SetConsoleOutputCP(65001);  // 设置输出代码页
    SetConsoleCP(65001);        // 设置输入代码页
#endif
    
    // 你的代码...
    std::cout << "Hello, World!" << std::endl;
    std::cout << "你好，世界！" << std::endl;
    std::cout << "这是中文输出测试" << std::endl;
    
    return 0;
}

关键说明

SetConsoleOutputCP(65001)：
- 设置控制台输出代码页为 UTF-8
- 影响 std::cout、printf 等输出函数
SetConsoleCP(65001)：
- 设置控制台输入代码页为 UTF-8
- 影响 std::cin、scanf 等输入函数
条件编译：
- 使用 #ifdef _WIN32 确保只在 Windows 平台编译此代码
- 保持跨平台兼容性

方案三：组合使用（最佳实践）

强烈推荐同时使用两种方案，这样可以确保在所有情况下都能正确显示中文：

✅ 编译器正确解析 UTF-8 源文件（方案一）
✅ 运行时控制台正确显示 UTF-8 输出（方案二）

完整示例

CMakeLists.txt

cmake 复制代码

# CMake 最低版本要求
cmake_minimum_required(VERSION 3.10)

# 项目名称和语言
project(ChineseOutputDemo LANGUAGES CXX)

# ========== 解决中文乱码问题 ==========
if(MSVC)
    add_compile_options(/utf-8)
    add_compile_definitions(_UTF8_SOURCE)
endif()

# 设置C++标准
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 添加可执行文件
add_executable(demo main.cpp)

main.cpp

cpp 复制代码

#include <iostream>
#include <string>
#ifdef _WIN32
#include <windows.h>
#endif

int main() {
#ifdef _WIN32
    // 设置控制台代码页为 UTF-8
    SetConsoleOutputCP(65001);
    SetConsoleCP(65001);
#endif
    
    // 测试各种中文输出
    std::cout << "========== 中文输出测试 ==========" << std::endl;
    std::cout << "Hello, World!" << std::endl;
    std::cout << "你好，世界！" << std::endl;
    std::cout << "这是中文测试" << std::endl;
    std::cout << "数字：12345" << std::endl;
    std::cout << "混合：Hello 世界 123" << std::endl;
    
    // 测试字符串变量
    std::string chinese = "中文字符串";
    std::cout << "变量输出：" << chinese << std::endl;
    
    std::cout << "==================================" << std::endl;
    
    return 0;
}

应用步骤

1. 修改现有项目

如果你已经有一个使用 CMake 的项目：

打开 CMakeLists.txt，在项目定义后添加 UTF-8 配置
打开 main.cpp （或其他包含中文输出的源文件），在 main() 函数开头添加控制台代码页设置
重新生成 VS 工程 ：
bash 复制代码
```
cd build
cmake ..
```
在 Visual Studio 中重新编译运行

2. 新建项目

创建新项目时，直接使用上述完整示例的代码即可。

验证方法

运行程序后，如果能看到正确的中文输出，说明问题已解决：

复制代码

========== 中文输出测试 ==========
Hello, World!
你好，世界！
这是中文测试
数字：12345
混合：Hello 世界 123
变量输出：中文字符串
==================================

常见问题与注意事项

1. 文件编码设置

问题：即使添加了配置，中文仍然乱码。

解决：确保源代码文件保存为 UTF-8 编码。

Visual Studio：
1. 打开文件
2. 文件 → 高级保存选项
3. 编码选择 "Unicode (UTF-8 with signature) - 代码页 65001" 或 "Unicode (UTF-8 without signature) - 代码页 65001"
VS Code：
1. 右下角点击编码
2. 选择 "通过编码保存"
3. 选择 "UTF-8"

2. 控制台字体问题

问题：设置了代码页但仍然显示乱码或方块。

解决：某些控制台字体不支持中文字符。

右键控制台标题栏 → 属性 → 字体
选择支持中文的字体，如：
- 新宋体
- Consolas（Windows 10+ 支持中文）
- Microsoft YaHei Mono

3. Visual Studio 版本要求

问题：/utf-8 选项不被识别。

解决：/utf-8 选项需要 Visual Studio 2015 或更高版本。

Visual Studio 2015 (MSVC 19.0)
Visual Studio 2017 (MSVC 19.1+)
Visual Studio 2019 (MSVC 19.2+)
Visual Studio 2022 (MSVC 19.3+)

4. 跨平台兼容性

如果项目需要在 Linux/macOS 上编译，代码中的 #ifdef _WIN32 条件编译是必要的：

cpp 复制代码

#ifdef _WIN32
    // Windows 特定代码
    SetConsoleOutputCP(65001);
    SetConsoleCP(65001);
#endif

Linux/macOS 系统默认使用 UTF-8，通常不需要额外设置。

5. 其他输出方式

如果使用其他输出方式（如文件输出、GUI 应用），可能需要不同的处理：

文件输出：确保文件以 UTF-8 编码保存
GUI 应用：Windows API 通常使用 UTF-16，需要转换

替代方案（不推荐）

方案 A：使用 GBK 编码保存源文件

不推荐，因为：

不利于跨平台开发
不符合现代开发规范
与国际标准不符

方案 B：手动转换字符串

不推荐，因为：

增加代码复杂度
维护困难
容易出错

总结

解决 CMake + Visual Studio 中文乱码问题的关键是：

✅ 编译器层面 ：在 CMakeLists.txt 中添加 /utf-8 编译选项
✅ 运行时层面：在代码中设置控制台代码页为 UTF-8
✅ 文件编码：确保源文件保存为 UTF-8 编码
✅ 控制台字体：使用支持中文的字体

通过以上步骤，可以彻底解决中文乱码问题，让程序在任何环境下都能正确显示中文输出。

参考资源

提示：如果按照本文方法仍然无法解决问题，请检查：

Visual Studio 版本是否支持 /utf-8 选项
源文件是否确实保存为 UTF-8 编码
控制台字体是否支持中文字符
是否有其他代码覆盖了控制台代码页设置

希望这篇文章能帮助你彻底解决中文乱码问题！🎉