Java调用Python程序时的中文编码问题排查与解决方案

Java调用Python程序时的中文编码问题排查与解决方案

最近在开发过程中遇到了一个关于Java调用Python程序时中文输出乱码的问题，经过一番排查和调试，终于找到了解决方案。在这里进行一下简单记录。

🧩问题描述

我使用Java程序通过cmd调用Python程序，并设置了以下环境变量：

• PYTHONIOENCODING=utf8 - 这个环境变量的作用是告诉Python解释器标准输入、输出和错误流的默认编码为UTF-8。
• PYTHONUNBUFFERED=1 - 这个环境变量的作用是禁用Python的输出缓冲，使输出能够实时显示。

然而，当Python程序输出中文时，Java程序读取到的却是乱码。例如，Python程序输出的中文测试123在Java中显示为���IJ���。

🔍问题排查过程

1. 检查Python默认编码

我在Python程序中添加了以下调试代码：

print(sys.getdefaultencoding())  # 输出 utf-8

输出结果为utf8，这表明 Python 的默认编码确实已经设置为 UTF-8，与环境变量的设置一致。但为什么仍然会出现乱码呢？

2. 进一步分析输出编码

通过打印sys.stdout.encoding，我发现：

print(sys.stdout.encoding)  # 输出 gbk

输出结果为gbk。这就解释了为什么会出现乱码：虽然 Python 的默认编码是 UTF-8，但标准输出流的编码却是 GBK，导致中文无法正确显示。

3. 编码不匹配问题确认

通过使用这个猜测编码的工具，我确认了问题是 “gbk encoding utf-8 decoding”，即 Python 以 GBK 编码输出，而 Java 却以 UTF-8 解码，导致乱码。

为防止链接失效，下面给出简单检测脚本源代码。

# -*- coding: utf-8 -*-
test_str = "这是编码测试fontTest👿"


def print_test(encoding,decoding):
    print("{} encoding {} decoding".format(encoding,decoding))
    # 对于encoding过程中出现的字符串，用？替代
    # 对于decoding过程中出现的字符串，用�(U+FFFD)替代
    print(test_str.encode(encoding,errors='replace').decode(decoding,errors='replace'))


print("UTF-8编码被错误用其他编码解释")
print_test('utf-8','gbk')
print_test('utf-8','utf-16le')
print_test('utf-8','utf-16be')
print_test('utf-8','big5')
print_test('utf-8','euc-jp')
print_test('utf-8','ascii')

print("其他编码被错误用UTF-8解释")
print_test('gbk','utf-8')
print_test('utf-16le','utf-8')
print_test('utf-16be','utf-8')
print_test('big5','utf-8')
print_test('euc-jp','utf-8')
print_test('ascii','utf-8')

print("GBK编码被错误用其他编码解释")
print_test('gbk','utf-8')
print_test('gbk','utf-16le')
print_test('gbk','utf-16be')
print_test('gbk','big5')
print_test('gbk','euc-jp')
print_test('gbk','ascii')

📌 关键概念解析

📚 sys.getdefaultencoding() vs sys.stdout.encoding

方法	含义	默认值
sys.getdefaultencoding()	返回的是 Python 解释器内部使用的默认字符串编码，通常由环境变量PYTHONIOENCODING控制。	通常为 utf-8
sys.stdout.encoding	返回的是标准输出流的编码，这个编码取决于操作系统和终端设置，可能与 Python 默认编码不一致，直接影响print()函数输出内容的编码。	Windows 下为 gbk，Linux 下为 utf-8

结论：即使默认编码是 UTF-8，如果标准输出流的编码不是 UTF-8，打印出来的内容仍然会以错误编码解码，导致乱码。

尽管设置了环境变量PYTHONIOENCODING=utf8，但是stdout的编码方式仍然是gbk，可能的原因是某些终端（如 Windows 的 CMD）或 IDE（如 PyCharm）可能强制使用系统默认编码（如 gbk），优先级高于 PYTHONIOENCODING。

✅ 解决方案

重包装stdout

import sys
import io
# 添加到程序最开始处
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

这行代码的作用是将标准输出流重新包装，强制使用 UTF-8 编码。具体来说：

• sys.stdout.buffer 是标准输出的底层二进制缓冲区。
• io.TextIOWrapper() 是一个文本包装器，用于将二进制流转换为文本流。
• encoding='utf-8' 指定了文本流的编码方式。

这个操作会影响所有后续的 print()、stdout 输出，确保其以 UTF-8 格式写入标准输出。

需要注意的是，这种方式只影响标准输出（stdout），对文件写入操作没有影响。如果你需要控制文件的编码，应该在打开文件时指定编码参数，例如：open('file.txt', 'w', encoding='utf-8')。

缓冲区问题

在最初实现上述解决方案后，我发现 Python 的输出不再实时显示，而是等到程序执行完毕后才一次性输出。这是因为重新包装标准输出流后，环境变量PYTHONUNBUFFERED=1的设置失效了。

测试代码为：

for i in range(10):
    time.sleep(1)
    print(time.strftime("%Y-%m-%d %H:%M:%S", time.localtime()))

添加write_through=True参数可以解决这个问题：

sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', write_through=True)

• write_through=True
  • 表示每次写入都直接刷新缓冲区，不再等待缓冲填满或程序结束。
  • 相当于禁用了缓冲行为，等效于 PYTHONUNBUFFERED=1 的功能。

Python 版本要求：

• write_through 参数从 Python 3.7 开始引入。
• 若使用更低版本，请考虑升级或手动调用 flush()。

为什么重设stdout会导致环境变量失效： 当重新赋值 sys.stdout 时，创建了一个新的 TextIOWrapper 对象，它不会继承原始标准输出流的设置，包括通过环境变量 PYTHONUNBUFFERED 设置的无缓冲模式。这就是为什么重新包装标准输出后需要显式指定 write_through=True。