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

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

前言

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

问题现象

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

mkdirbuildcdbuild 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_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）中添加控制台代码页设置：

#include<iostream>#ifdef_WIN32#include<windows.h>#endifintmain(){#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;return0;}

关键说明

• SetConsoleOutputCP(65001)：

  • 设置控制台输出代码页为 UTF-8
  • 影响std::cout、printf等输出函数

• SetConsoleCP(65001)：

  • 设置控制台输入代码页为 UTF-8
  • 影响std::cin、scanf等输入函数

• 条件编译：

  • 使用#ifdef _WIN32确保只在 Windows 平台编译此代码
  • 保持跨平台兼容性

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

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

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

完整示例

CMakeLists.txt

# 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

#include<iostream>#include<string>#ifdef_WIN32#include<windows.h>#endifintmain(){#ifdef_WIN32// 设置控制台代码页为 UTF-8SetConsoleOutputCP(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;return0;}

应用步骤

1. 修改现有项目

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

1. 打开CMakeLists.txt，在项目定义后添加 UTF-8 配置
2. 打开main.cpp（或其他包含中文输出的源文件），在main()函数开头添加控制台代码页设置
3. 重新生成 VS 工程：

   cdbuild cmake..

4. 在 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条件编译是必要的：

#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 中文乱码问题的关键是：

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

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

参考资源

• MSVC 编译器选项文档
• Windows 代码页列表
• CMake 官方文档

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

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

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