GBKtoUTF-8图形化工具可零命令行批量修复QoderWake项目中GBK编码的.cpp、.h等文件乱码问题，支持智能识别、自动备份、UTF-8无BOM输出。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
一、使用GBKtoUTF-8图形化工具批量转换
当您面对大量QoderWake项目中混用GBK编码的源文件（如.cpp、.h、.txt）在UTF-8环境（如Qt Creator/Linux构建系统）下显示乱码时，图形化工具可实现零命令行干预的精准识别与批量修复。该工具内置智能编码探测引擎，能区分BOM存在与否、规避误判为ASCII或ISO-8859-1的情况。
1、访问项目仓库地址，执行命令：git clone https://gitcode.com/gh_mirrors/gb/GBKtoUTF-8.git，或直接下载ZIP包并解压至不含中文与空格的路径（例如：D:\QoderWake_Encoding_Fix）。
2、进入解压目录，根据系统环境选择可执行文件：GBKtoUTF-8_with-runtime.exe（推荐Windows 7/8.1未装.NET用户） 或 GBKtoUTF-8.exe（已安装.NET 6运行时的Windows 10/11用户）。
3、双击启动程序，切换至“文件夹模式”标签页，点击“选择源文件夹”，定位到QoderWake工程根目录下的src或include子目录；再点击“选择输出目录”，指定新路径（如D:\QoderWake_UTF8）以避免覆盖原始文件。
4、勾选“仅处理GBK编码文件”和“自动备份原始文件”选项，点击右下角“开始转换”按钮；进度条完成后，界面提示“全部完成”，此时新目录中所有文件均已转为UTF-8无BOM格式。
二、通过Python脚本自动化修复单文件及递归目录
适用于CI/CD流程集成或需嵌入构建前检查环节的场景。脚本基于chardet库动态识别真实编码，避免硬编码导致的误转换；采用“先解码为Unicode字符串、再以UTF-8写入”的安全范式，确保中文字符不丢失、不截断。
1、确保已安装Python 3.6+及依赖库：pip install chardet。
2、新建文件convert_gbk_to_utf8.py，粘贴以下代码：
import os, chardet
def detect_and_convert(file_path):
with open(file_path, 'rb') as f:
raw = f.read()
enc = chardet.detect(raw)['encoding']
if enc and enc.lower() in ['gbk', 'gb2312', 'gb18030', 'cp936']:
try:
text = raw.decode(enc)
with open(file_path, 'w', encoding='utf-8') as f_out:
f_out.write(text)
print(f"✓ {file_path} → UTF-8")
except (UnicodeDecodeError, UnicodeEncodeError):
print(f"✗ {file_path} 转换失败（含非法字节）")
for root, _, files in os.walk('QoderWake'):
for f in files:
if f.endswith(('.cpp', '.h', '.txt', '.ui')):
detect_and_convert(os.path.join(root, f))
3、将该脚本置于QoderWake工程同级目录，终端执行：python convert_gbk_to_utf8.py。
三、Qt Creator内强制统一源码文件编码设置
针对QoderWake工程在Qt Creator中编辑时控件文本、qDebug输出仍出现乱码的问题，根源常在于IDE未按UTF-8解析GBK保存的源文件。此方法不修改文件内容，而是让编辑器与编译器协同采用一致编码策略，消除读取阶段偏差。
1、打开Qt Creator，进入菜单栏：工具 → 选项 → 文本编辑器 → 行为。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
2、在“默认编码”下拉框中，选择：UTF-8 without BOM；勾选“在需要时添加BOM”选项保持禁用状态。
3、点击“确定”保存后，关闭并重新打开QoderWake项目；对任一.cpp或.h文件右键 → “另存为”，在弹出对话框底部确认编码显示为“UTF-8”，点击保存覆盖原文件（此时实际完成一次手动重编码）。
4、在对应源文件顶部第一行插入预处理器指令：#pragma execution_character_set("utf-8")（仅限MSVC编译器有效），或在main()函数开头添加：QTextCodec::setCodecForLocale(QTextCodec::codecForName("UTF-8"));。
四、Linux/macOS环境下使用iconv命令行批量转换
适用于服务器端部署QoderWake或CI流水线中无GUI环境的场景。iconv是POSIX标准工具，无需额外安装，在Ubuntu/CentOS/macOS Terminal中均可直接调用，支持通配符匹配与错误跳过机制。
1、打开终端，进入QoderWake工程根目录，执行：find . -name "*.cpp" -o -name "*.h" -o -name "*.txt" | while read f; do iconv -f GBK -t UTF-8 "$f" -o "${f}.utf8" && mv "${f}.utf8" "$f"; done。
2、若遇到无法识别的字节（如老旧GB2312扩展字符），添加容错参数：iconv -f GBK -t UTF-8//IGNORE "$f" -o "${f}.utf8"，忽略非法序列继续转换。
3、验证转换结果：随机选取一个文件，执行：file -i filename.cpp，输出中应包含charset=utf-8字样。
五、在Qt源码中显式声明字符串编码避免运行时乱码
即使文件已转为UTF-8，若QoderWake中仍使用QString::fromLocal8Bit()或隐式构造方式加载中文字符串，Windows平台会按系统活动代码页（GBK）解析，导致界面显示为“锟斤拷”。此方法从代码层切断错误解码链路。
1、查找所有含中文字符串字面量的代码行，例如：label->setText("配置参数");。
2、将其替换为显式UTF-8构造形式：label->setText(QString::fromUtf8("配置参数")); 或更优的编译期方案：label->setText(QStringLiteral("配置参数"));。
3、对qDebug输出中的中文，统一改用：qDebug() ，而非直接传入裸字符串。
4、若工程含资源文件（.qrc），右键.qrc文件 → “Open With” → “Qt Resource Editor”，确认其XML声明中encoding="UTF-8"存在且生效。
