Java 字符编码问题，怎么优雅地解决？
大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。
图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG
我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。
展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！
文章目录
- 前言
- 背景：为什么会出现编码问题？
- 常见场景分析
- 控制台输出乱码
- 文件读写乱码
- 数据库存取乱码
- 解决方案
- 统一使用 UTF-8
- 设置 JVM 参数
- 数据库设置字符集
- 实际案例：乱码排查经验
- 总结
前言
在日常 Java 开发中，字符编码问题是一个非常常见却又特别容易踩坑的地方。尤其是在不同操作系统之间切换，或者从前端传到后端、再到数据库，编码没统一好，中文就会出现“乱码”。很多同学第一次遇到的时候，会被一大堆奇怪的方块符号或者问号整崩溃。
这篇文章就带你一步一步看清楚字符编码的来龙去脉，并结合可运行的代码，看看如何在 Java 项目里彻底解决编码不一致的问题。
背景：为什么会出现编码问题？
其实原因很简单：不同系统、不同软件的默认字符编码不一样。
- Windows 上默认编码是 GBK 或 CP936。
- Linux、Mac 大部分是 UTF-8。
- 数据库可能是 Latin1、GBK 或 UTF-8。
- Tomcat、IDEA 默认也可能不是 UTF-8。
举个例子，如果你的 Java 程序里写了一行中文字符串 "你好"，在 UTF-8 下存储没问题，但如果有人用 GBK 来读取，就会直接炸掉，变成“乱码”。
常见场景分析
控制台输出乱码
在 Windows 的 CMD 下运行 Java 程序时，经常会看到控制台打印中文是乱码。这是因为 Windows 控制台默认用 GBK 编码，但你的 Java 程序里可能用的是 UTF-8。
public class EncodingDemo {public static void main(String[] args) {String msg = "你好，世界";System.out.println(msg);}
}
在 Linux/Mac 控制台上运行，大概率没问题。但在 Windows CMD 里，就会看到一堆奇怪符号。
文件读写乱码
当你从文件里读中文内容时，如果读的时候用的编码和写的时候不一样，也会直接出错。
import java.io.*;public class FileEncodingDemo {public static void main(String[] args) throws Exception {String text = "中文内容测试";// 写入文件，强制使用 UTF-8try (Writer writer = new OutputStreamWriter(new FileOutputStream("test.txt"), "UTF-8")) {writer.write(text);}// 读取文件（错误示范：不指定编码）try (BufferedReader reader = new BufferedReader(new FileReader("test.txt"))) {System.out.println("读到的内容：" + reader.readLine());}// 正确方式：指定 UTF-8try (BufferedReader reader = new BufferedReader(new InputStreamReader(new FileInputStream("test.txt"), "UTF-8"))) {System.out.println("正确读到的内容：" + reader.readLine());}}
}
运行后你会发现，没指定编码时中文是乱码，指定了 UTF-8 之后就正常了。
数据库存取乱码
数据库也是高频出错点，比如 MySQL 默认的 latin1 编码就很坑。假设表结构是这样的：
CREATE TABLE user (id INT PRIMARY KEY AUTO_INCREMENT,name VARCHAR(50)
) DEFAULT CHARSET=latin1;
如果你在 Java 里用 UTF-8 往里面写入 "张三"，再读出来时就会发现已经是乱码。
解决办法是：
- 建库建表时就指定
utf8mb4：
CREATE DATABASE demo DEFAULT CHARSET=utf8mb4;
- JDBC 连接时也要加上编码参数：
spring.datasource.url=jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf-8&serverTimezone=UTC
解决方案
那我们该怎么统一解决这个问题呢？其实有几个常见思路：
统一使用 UTF-8
UTF-8 是现在最通用的编码方式，跨系统兼容性最好。所以最稳妥的做法就是：整个链路都统一成 UTF-8。
包括：源代码文件、编译参数、运行参数、数据库配置、Tomcat 配置。
比如在 Maven 项目里，你可以在 pom.xml 里强制指定源码编码：
<project><properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></properties>
</project>
这样即便在 Windows 上编译，结果也不会变。
设置 JVM 参数
如果你发现运行环境默认编码不是 UTF-8，可以在 JVM 启动时加上参数：
java -Dfile.encoding=UTF-8 -jar app.jar
这会让整个 Java 虚拟机的默认编码改成 UTF-8，很多情况下能一劳永逸。
数据库设置字符集
在 MySQL 里，推荐直接用 utf8mb4，这样连 emoji 表情都能存：
ALTER DATABASE demo CHARACTER SET utf8mb4;
ALTER TABLE user CONVERT TO CHARACTER SET utf8mb4;
同时，Java 里的 JDBC 连接也要显式指定编码，否则还是会出问题。
实际案例：乱码排查经验
我自己就踩过一个坑：在 Windows 下本地开发，数据库是 utf8mb4，项目里也设了 -Dfile.encoding=UTF-8，一切正常。但是代码上线到 Linux 服务器后，日志里的中文全是乱码。排查了半天，最后发现是 日志框架的配置文件没声明 UTF-8，导致写日志文件时被当成系统默认编码。
后来改了一行配置就好了：
<encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"><charset>UTF-8</charset><pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
</encoder>
所以要点就是：不要依赖默认值，凡是涉及到字符集的地方都要显式声明 UTF-8。
总结
Java 的字符编码问题，说白了就是“读和写不一致”。解决它的核心就是统一，特别是统一用 UTF-8。
- 源代码、编译、运行 JVM 都统一 UTF-8。
- 文件读写时显式指定编码。
- 数据库用
utf8mb4并在 JDBC 连接里加上参数。
只要做到这几点，基本就不会再遇到莫名其妙的乱码问题。