Windows下Bash调用Python中文乱码：PYTHONIOENCODING环境变量修复指南

脚本专家

在 Windows 11 环境下，通过 Claude Code（或其他终端工具）的 Bash 执行 Python 脚本时，如果输出包含中文字符，常常显示为问号或乱码。例如：

2. $ python -c "print('测试中文输出')"
3. �����˺Ž�����������

复制代码

英文和符号都能正常显示，唯独中文变成一堆乱码。

原因分析

这是一个典型的编码不匹配问题，涉及三层编码链路：Python stdout → 终端 → 显示。

- Windows 系统默认使用 GBK（CP936）作为系统 locale 编码。
- Python 的 stdout 默认跟随系统编码，通过 locale.getpreferredencoding() 获取，通常是 GBK。
- Claude Code 的 Bash 工具底层是 Git Bash（MSYS2），期望接收 UTF-8 编码的字节流。

问题根因：Python 用 GBK 编码输出中文字符，但终端却按 UTF-8 解释这些字节。例如，“你”的 GBK 编码是 \xc4\xe3，而 UTF-8 解码这两个字节就成了乱码。

解决方案对比

| 方案 | 原理 | 优点 | 缺点 |
|------|------|------|------|
| 设置 PYTHONIOENCODING=utf-8 环境变量 | 强制 Python 使用 UTF-8 编码 stdout | 一劳永逸，不修改代码 | 需要重启终端生效 |
| 每次执行前 chcp 65001 | 切换控制台代码页 | 无需改环境变量 | 每次都要加，对 Git Bash 不一定有效 |
| 脚本内 sys.stdout 重新包装 | Python 内部强制编码 | 精确控制 | 侵入性强，每个脚本都要改 |

推荐使用第一种方案：通过注册表永久设置 PYTHONIOENCODING=utf-8 环境变量。

具体操作步骤

1. 以普通权限打开 PowerShell，执行以下命令写入注册表：

2. New-ItemProperty -Path 'HKCU:\Environment' -Name 'PYTHONIOENCODING' -Value 'utf-8' -PropertyType String -Force

复制代码

验证是否写入成功：

2. [System.Environment]::GetEnvironmentVariable('PYTHONIOENCODING', 'User')
3. # 输出: utf-8

复制代码

注意：这里不使用 [System.Environment]::SetEnvironmentVariable() 是因为实测用户级环境变量在某些环境（如 Claude Code 的 Bash 工具）中不会被新进程继承，直接写注册表 HKCU:\Environment 更可靠。

2. 重启终端或 Claude Code 应用，使环境变量生效。环境变量只在进程启动时读取，已打开的窗口不会自动刷新。

3. 验证：

2. $ python -c "print('你好世界 ✅')"
3. 你好世界 ✅

复制代码

中文正常输出，乱码问题解决。

注意事项

- 该环境变量只对新启动的 Python 进程生效，已经打开的终端窗口中的 Python 进程不会受影响。
- 设置 PYTHONIOENCODING=utf-8 会影响所有 Python 进程的 stdout/stderr 编码。如果你有脚本依赖 GBK 输出（例如写入旧系统读取的文件），需要评估影响。
- 对于 Git Bash / MSYS2 的特殊情况：有时注册表设置后仍不生效，可以尝试在 ~/.bashrc 中添加 export PYTHONIOENCODING=utf-8，但该方式只对交互式 Shell 生效，而 Claude Code 的 Bash 工具运行在非交互模式下，因此注册表方式更可靠。

总结

| 项目 | 内容 |
|------|------|
| 问题 | Windows 下 Bash 调用 Python 输出中文乱码 |
| 根因 | Python 默认 GBK 编码与终端 UTF-8 编码不匹配 |
| 解决 | 注册表设置 PYTHONIOENCODING=utf-8，重启生效 |
| 验证 | python -c "print('你好世界 ✅')" 正常输出 |

通过上述方法，可以一劳永逸地解决 Windows 环境下 Bash 调用 Python 输出中文乱码的问题，避免每次手动调整编码。

热心网友7

感谢分享！这篇帖子非常实用，分析也很透彻。Windows下Python中文编码确实是个老问题，你提到的三层编码链路（Python stdout → 终端 → 显示）说得很清楚，让人一下子理解了根源。 注册表设置 `PYTHONIOENCODING=utf-8` 确实是一劳永逸的办法，尤其对于 Claude Code 这种非交互式 Bash 工具，比改 `~/.bashrc` 可靠得多。我以前遇到过类似问题，折腾半天最后也是改环境变量解决的。不过有个小提醒：设置后如果遇到某些旧脚本输出到文件乱码，可以用 `PYTHONIOENCODING=gbk` 临时覆盖，或者脚本内加 `io.TextIOWrapper` 按需切换。 总之，强推这个方案，逻辑清晰，步骤也容易跟做。感谢！