🧠 一、问题背景
在智能体项目的开发与调试过程中，
我在本地启动 Spring Boot 后端服务时，发现 控制台日志、数据库内容、以及接口返回结果
均出现了严重的中文乱码。
例如，预期输出应为：
你好，请问有什么可以帮您？实际结果却是：
鎮ㄧ鎴戜滑鍙互鍔犳鍙嬪ソ鎬庝箞闂这种典型的"乱码现象"，意味着系统的字符集编码在不同环节间不一致。
初步怀疑的方向包括：
- JVM 默认编码（GBK / UTF-8 不匹配）
- 编辑器保存编码
- 数据库字符集设置
🧩 二、问题定位思路
为了快速锁定问题，我制定了以下排查路径：
🧭 三层定位模型：
1️⃣ 数据库层（PostgreSQL 编码是否为 UTF-8）
2️⃣ JVM 层（Java 运行时编码设置）
3️⃣ 编辑器层（VS Code 保存和执行文件时的编码方式）
🔍 三、排查与验证过程
🗃️ 1. 数据库层验证
执行以下 SQL，确认数据库编码：
ini
SHOW SERVER_ENCODING;结果为：
UTF8✅ PostgreSQL 端正常。
由此排除数据库本身的编码问题。
⚙️ 2. JVM 编码检测
我在主启动类（SmartWebApplication.java）中添加测试语句：
csharp
System.out.println("当前JVM编码：" + System.getProperty("file.encoding"));控制台输出结果为：
当前JVM编码：GBK🚨 问题明确：JVM 默认继承了 Windows 的 GBK 编码 ，
而整个系统（前端 + 数据库 + 配置文件）都是 UTF-8，
这就导致字符在解析阶段被错误解码，最终呈现乱码。
🧰 3. VS Code 编码机制排查
我发现运行 Java 文件时，VS Code 会生成一个临时文件：
tempCodeRunnerFile.java其运行命令大致为：
javac tempCodeRunnerFile.java && java tempCodeRunnerFile这说明我使用的是 Code Runner 插件 来执行 Java。
而 Code Runner 不会读取 .vscode/launch.json 中的 JVM 参数，
始终默认以 GBK 编译并运行。
🔎 换言之，即使源文件是 UTF-8 保存的，执行时依然会被错误解码。
🧩 四、解决方案
经过多轮验证，我最终确定以下解决方案能彻底统一编码环境。
✅ 方案一：禁用 Code Runner 插件
🧯 操作步骤：
- 打开 VS Code → 扩展（Extensions）
- 搜索 "Code Runner"
- 选择「禁用（Disable）」或在 Java 项目中关闭自动执行
Code Runner 的临时执行机制会破坏 Java Debug 的标准启动参数，
禁用后改用「Java: Debug」启动方式更安全。
✅ 方案二：在 launch.json 中强制指定 JVM 编码
在项目根目录的 .vscode/launch.json 中添加如下配置：
json
{
"type": "java",
"name": "Debug SmartAgentApplication",
"request": "launch",
"mainClass": "sparkx.web.SparkXWebApplication",
"projectName": "smart-agent",
"vmArgs": "-Dfile.encoding=UTF-8"
}🧩 此参数会在 JVM 启动时强制采用 UTF-8 编码，
从源头统一系统字符集。
✅ 方案三：统一编辑器与编译编码
在 settings.json 中添加：
json
{
"java.compile.encoding": "UTF-8",
"files.encoding": "utf8"
}📘 这确保了 VS Code 在：
- 文件保存时
- Java 源码编译时
- 控制台日志输出时
均使用统一的 UTF-8 编码。
🔄 五、验证与结果
修改后重新运行程序：
🌍 当前JVM编码：UTF-8验证结果如下：
| 检查项 | 状态 | 说明 |
|---|---|---|
| 数据库字符集 | ✅ UTF8 | PostgreSQL 配置正常 |
| JVM 默认编码 | ✅ UTF-8 | 通过启动参数指定 |
| 源文件保存编码 | ✅ UTF-8 | VS Code 统一设置 |
| 控制台输出 | ✅ 无乱码 | 中文输出正常 |
| 日志与网页响应 | ✅ 正常 | API 返回数据正常显示 |
✨ 中文显示恢复正常，系统全链路编码一致。
🚧 六、附加问题：端口占用导致启动失败
在多次调试过程中，Spring Boot 报错如下：
vbscript
APPLICATION FAILED TO START
Web server failed to start. Port 8989 was already in use.原因是上一次异常退出的实例仍在后台运行。
使用命令排查并释放端口：
r
netstat -ano | findstr 8989
taskkill /PID <进程号> /F重新启动后，服务正常运行。
🧠 七、问题根因分析
🧩 根因总结：
- Windows 默认编码为 GBK；
- JVM 未显式设置
file.encoding时会继承系统默认编码；- Code Runner 执行 Java 时不读取 VS Code 的运行配置；
- 各环节编码不一致导致字符解析异常。
简言之：
"系统中的每一环都在说不同的语言，而 UTF-8 是让它们重新达成共识的标准。"
🧭 八、经验总结与最佳实践
| 问题类型 | 对应解决方案 |
|---|---|
| JVM 默认编码为 GBK | 启动参数加 -Dfile.encoding=UTF-8 |
| VS Code 保存编码不一致 | files.encoding=utf8 |
| 插件执行方式不同 | 禁用 Code Runner |
| 日志乱码排查困难 | 打印 System.getProperty("file.encoding") |
| 启动端口冲突 | netstat + taskkill 释放端口 |
⚙️ 九、长期优化建议
若希望在全局范围内自动使用 UTF-8，可在系统环境变量中添加：
ini
变量名：JAVA_TOOL_OPTIONS
变量值：-Dfile.encoding=UTF-8🧩 此配置将影响所有 Java 进程，无需逐个项目设置。
💡 十、结语
本次智能体项目乱码问题，表面上是"文字显示异常"，
本质是 多层编码不一致 导致的信息解析错误。
通过分层排查与统一配置，
我实现了从 编辑器 → JVM → 日志系统 → 数据库 的编码标准化。