VS Code 运行 Python 终端出现乱码或编码错误的处理方法

一、终端乱码与编码错误的典型现象与底层成因

在 Windows 系统中使用 VS Code 编写并运行 Python 代码时，编码问题通常表现为两种具体形态：

• 现象一：标准输出内容乱码。使用 print("你好，世界") 输出中文时，终端内显示为拼音字符碎片（例如 æµ<8b>è¯<95>）、未知问号菱形、或者中文字符错位（例如 浣犲ソ锛屼笘鐣）。
• 现象二：程序抛出运行时异常。Python 解释器直接终止运行，终端输出类似 UnicodeEncodeError: 'gbk' codec can't encode character '•' in position 0: illegal multibyte sequence 的报错堆栈。

之所以会出现上述故障，根源在于 Windows 系统的历史兼容机制与现代跨平台开发标准的冲突。VS Code 默认创建的代码文件采用变长多字节的 UTF-8 编码；而中文版 Windows 系统的默认 ANSI 代码页为 GBK（代码页 936）。当 Python 脚本在终端启动时，Python 解释器在没有外部环境变量约束的情况下，会主动探测宿主系统的区域设置，将其标准输入输出流（sys.stdout / sys.stdin）默认绑定为系统的 GBK 编码。

这导致了一道严重的“编码断层”：如果 Python 按照 UTF-8 吐出 3 字节的中文字符字节序列，而 VS Code 内置终端仍处于 GBK 的双字节解析模式，终端就会将字节序列强行错位拼凑成不可读的字符；反之，若 Python 试图在输出前把源码中的特殊 Unicode 字符强转为 GBK，一旦字符超出 GBK 字库范围，就会立即触发 UnicodeEncodeError。

二、四步排查法：准确定位编码故障节点

遇到乱码时，盲目在代码里添加各种 encode() 或 decode() 转换往往会破坏数据本身。应当按照清晰的数据链路依次排查以下四个节点：

步骤 1：核验源文件自身的保存编码格式

观察 VS Code 窗口右下角的状态栏。正常情况下，当前打开的 Python 文件编码应显示为 UTF-8。如果显示为 GB2312、GBK 或其他格式，直接点击该状态栏标签，选择“通过编码重新保存”（Save with Encoding），并在搜索栏中选中 UTF-8。

步骤 2：查询终端当前的活动代码页

打开 VS Code 内置终端（快捷键为 Ctrl + `），直接输入查询命令：

chcp

观察命令返回的数字：

• 如果显示 活动代码页: 936，说明当前终端会话正处于 GBK 模式，接收到 UTF-8 流必然乱码。
• 如果显示 活动代码页: 65001，说明当前终端会话已处于标准 UTF-8 模式。

步骤 3：验证 Python 解释器运行时的 stdout 编码

在终端中运行以下单行测试命令，输出当前解释器实际绑定的标准流编码：

python -c "import sys; print('stdout encoding:', sys.stdout.encoding)"

如果输出为 stdout encoding: gbk 或 cp936，则说明 Python 解释器被系统环境变量引导成了 GBK 模式；理想的正常输出应为 stdout encoding: utf-8。

步骤 4：确认代码运行媒介（内置终端 vs 插件输出面板）

必须区分你是通过哪种方式运行 Python 代码的：

• 方式 A（推荐）：在 VS Code 底部内置终端（Terminal: PowerShell / CMD / Git Bash）中直接执行 python main.py。该终端具备完整的 Shell 交互能力。
• 方式 B：通过右键点击编辑区选择“Run Code”（由热门插件 Code Runner 提供）。Code Runner 默认将输出打印在只读的“输出（OUTPUT）”面板中，该面板不属于交互式终端，默认无法响应终端代码页指令，容易出现顽固乱码。

三、根本解决方案：配置 VS Code 与 Python 运行环境

明确了故障诱因后，我们需要通过正规的配置文件与环境参数，将各环节永久锁定在 UTF-8 规范下。

方案 1：在 VS Code 中为终端注入 Python UTF-8 环境变量

这是最彻底且不侵入操作系统的配置方式。打开 VS Code 设置（快捷键 Ctrl + ,），点击右上角的“打开设置(JSON)”图标，在 settings.json 文件中追加以下配置项：

{
    "terminal.integrated.env.windows": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
    },
    "files.encoding": "utf8"
}

参数含义解析：

• PYTHONIOENCODING: "utf-8"：指示 Python 解释器在初始化标准输入、标准输出和标准错误流（stdin/stdout/stderr）时，强制使用 UTF-8 编解码器，忽略系统的默认代码页。
• PYTHONUTF8: "1"：自 Python 3.7 起引入的 PEP 540 UTF-8 模式开关。开启后，解释器在整个生命周期中默认使用 UTF-8，无需依赖系统区域设置。

方案 2：永久配置 VS Code 终端代码页为 65001

为确保终端在启动时自动进入 UTF-8 模式，可以在 settings.json 中为具体的终端 Profile 注入启动参数。

若使用 PowerShell 作为默认终端，添加启动参数：

{
    "terminal.integrated.profiles.windows": {
        "PowerShell": {
            "source": "PowerShell",
            "args": ["-NoExit", "-Command", "chcp 65001 >$null"]
        }
    }
}

若同时需要在 PowerShell 会话自身内部强制标准管道输出为 UTF-8，可以在 PowerShell 的用户配置文件中追加编码规则。在终端运行 notepad $PROFILE，在打开的文本末尾粘贴：

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
chcp 65001 >$null

保存并重启终端即可生效。

方案 3：修正 Code Runner 插件的乱码问题

如果习惯使用 Code Runner 插件的三角运行图标，建议将执行行为重定向至内置终端，以复用上述配置。在 settings.json 中加入：

{
    "code-runner.runInTerminal": true
}

如果依然希望在“输出（OUTPUT）”面板中查看结果，则需要为 Code Runner 的 Python 命令显式添加编码前缀。在 settings.json 中修改 code-runner.executorMap：

{
    "code-runner.executorMap": {
        "python": "set PYTHONIOENCODING=utf8 && python -u"
    }
}

这将在每次拉起 Python 子进程前临时指定环境变量，使输出流强制转为 UTF-8。

方案 4：规范 Python 脚本自身的文件读写代码

除了终端打印外，许多编码错误发生在 Python 读取外部文本或写入日志的过程中。在 Windows 环境下，如果不显式指定编码，内置的 open() 函数会回退到系统本地编码（GBK），一旦读取 UTF-8 编码的文本文件就会抛出 UnicodeDecodeError。

编写文件读写操作时，必须始终显式声明 encoding='utf-8'：

# 规范的文件读取示例
def read_project_data(file_path):
    with open(file_path, mode="r", encoding="utf-8") as f:
        return f.read()

# 规范的文件写入示例
def save_project_log(file_path, message):
    with open(file_path, mode="a", encoding="utf-8") as f:
        f.write(message + "\n")

四、验证效果与常见边界问题速查

完成上述配置后，需要运行测试脚本确认所有环节已正常运转。

验证脚本

在 VS Code 中新建一个名为 test_encoding.py 的文件，输入以下内容并运行：

import sys

def verify_encoding_environment():
    print("========== 编码环境检测结果 ==========")
    print(f"Python 解释器版本: {sys.version.split()[0]}")
    print(f"标准输出 stdout 编码: {sys.stdout.encoding}")
    print(f"标准输入 stdin 编码 : {sys.stdin.encoding}")
    print(f"系统默认编码        : {sys.getdefaultencoding()}")
    print("--------------------------------------")
    print("中文测试：你好，VS Code！")
    print("符号测试：★ ● ▲ ￥ 【】 «»")
    print("======================================")

if __name__ == "__main__":
    verify_encoding_environment()

预期输出效果：

========== 编码环境检测结果 ==========
Python 解释器版本: 3.11.x
标准输出 stdout 编码: utf-8
标准输入 stdin 编码 : utf-8
系统默认编码        : utf-8
--------------------------------------
中文测试：你好，VS Code！
符号测试：★ ● ▲ ￥ 【】 «»
======================================

若输出中的中文与特殊符号无一乱码，且 stdout 准确显示为 utf-8，即表明修复完成。

常见边界情况与补充说明

1. 老旧 Windows 控制台字体问题：部分老版本 Windows 系统的默认命令行字体为“点阵字体”（Raster Fonts），该字体无法绘制复杂的 Unicode 符号。请在 VS Code 设置中检查 terminal.integrated.fontFamily，确保使用的是支持中文的等宽字体（例如 Consolas, 'Courier New', monospace 或 'Cascadia Code'）。
2. 虚拟环境覆盖问题：激活 Conda 或 Python venv 虚拟环境时，部分环境激活脚本可能会重置当前会话的局部环境变量。在 settings.json 中的 terminal.integrated.env.windows 配置会在激活脚本之后重新注入，可有效防止被虚拟环境覆盖。