013：Windows 安装——原生 CMD/PowerShell、WSL2 环境与编码问题

013、Windows 安装原生 CMD/PowerShell、WSL2 环境与编码问题一个让我熬夜到凌晨三点的乱码事情是这样的。上个月帮团队搭 CodeX 开发环境同事 Windows 机器上跑codex query 用 Python 写个斐波那契终端里蹦出来一堆锟斤拷锟斤拷。我第一反应是“又是编码问题”但没想到这次坑这么深——CodeX 在 Windows 下的编码处理比我想象的脆弱得多。如果你也遇到过 CodeX 输出中文变成????或者直接报UnicodeEncodeError别急着重装系统。这篇笔记把我在原生 CMD、PowerShell 和 WSL2 三种环境下踩过的坑以及最终怎么填平的一次性说清楚。原生 CMD最古老的坑最深CMD 默认的代码页是 936GBK而 CodeX 返回的 JSON 响应默认是 UTF-8。这两个编码在管道传输时直接打架。典型症状codex list-models输出正常但一旦包含中文描述终端就显示涓枃这种乱码。更坑的是如果你把输出重定向到文件文件里反而是对的——这说明问题出在终端显示层不是 CodeX 本身。我的修复方案别用chcp 65001就完事那只是第一步:: 先切 UTF-8但光这样不够 chcp 65001 nul :: 关键一步设置 CodeX 的环境变量强制它用 UTF-8 输出 set CODEX_OUTPUT_ENCODINGutf-8 :: 然后运行注意这里有个坑——PowerShell 里这样写会报错 codex query 你好世界踩坑记录CMD 下chcp 65001后某些旧版 Windows 10 的字体渲染会出问题中文字符变成方框。解决方案是换字体——在 CMD 标题栏右键 - 属性 - 字体选“Consolas”或“Lucida Console”别用默认的“点阵字体”。我试过“新宋体”也能用但看着别扭。别这样写:: 别把 set 和 codex 写在一行管道会吞掉环境变量 set CODEX_OUTPUT_ENCODINGutf-8 codex query 测试这样写在某些 Windows 版本上set的环境变量不会传递给codex进程。老老实实分两行。PowerShell看似现代实则暗坑更多PowerShell 比 CMD 聪明但聪明反被聪明误。它默认用 UTF-16 LE 编码而 CodeX 的 Python 后端输出 UTF-8两者在管道里互相转换时BOM 头会搞出幺蛾子。我遇到的真实报错codex : 无法处理参数因为参数“query”的值包含无效的 Unicode 字符。排查了半天发现是 PowerShell 把 CodeX 输出的 UTF-8 BOM 当成了参数的一部分。解决方案是禁用 BOM 输出# 设置 CodeX 输出不要 BOM$env:CODEX_OUTPUT_BOM false# 或者更暴力一点强制 PowerShell 用 UTF-8 无 BOM 读取$OutputEncoding[System.Text.UTF8Encoding]::new($false)[Console]::OutputEncoding [System.Text.UTF8Encoding]::new($false)# 然后运行codex query中文测试这里踩过坑$OutputEncoding和[Console]::OutputEncoding是两个不同的东西。前者控制管道输出编码后者控制终端显示编码。我一开始只改了$OutputEncoding结果codex输出到文件正常但终端还是乱码。两个都要改。更优雅的方案我目前在用的在$PROFILE文件里加一段初始化脚本这样每次打开 PowerShell 自动生效# 放在 $PROFILE 里别每次手动敲if($host.Name-eqConsoleHost){$OutputEncoding[System.Text.UTF8Encoding]::new($false)[Console]::OutputEncoding [System.Text.UTF8Encoding]::new($false)$env:CODEX_OUTPUT_BOM false}WSL2最省心的方案但有个隐藏陷阱如果你问我个人推荐哪个环境WSL2 无疑是最省心的。Linux 内核天然 UTF-8CodeX 在 WSL2 里跑几乎不需要额外配置。安装步骤简略版重点说坑# 安装 CodeX假设你已经装了 Python3pipinstallcodex-cli# 直接跑中文没问题codex query用中文解释什么是闭包但是有个隐藏陷阱——WSL2 的 Windows 文件系统互操作。如果你在/mnt/c/下操作文件或者把 CodeX 输出重定向到 Windows 盘编码问题会卷土重来。我踩过的坑# 这样写输出到 Windows 桌面的文件会乱码codex query测试/mnt/c/Users/你的用户名/Desktop/output.txt原因WSL2 访问/mnt/c/时文件系统驱动默认用 Windows 的编码GBK写入。解决方案是显式指定编码# 用 Python 的编码转换或者直接重定向时加 iconvcodex query测试|iconv-futf-8-tgbk/mnt/c/Users/你的用户名/Desktop/output.txt别这样写# 别用 追加到 Windows 文件编码会乱codex query测试/mnt/c/Users/你的用户名/Desktop/output.txt追加模式下如果文件已存在且编码不匹配会直接报错。建议先清空再写。终极方案一个跨环境的启动脚本为了不再每次换机器都重新踩坑我写了个小脚本放在 CodeX 的配置目录下Windows CMD 版codex_env.batecho off chcp 65001 nul set CODEX_OUTPUT_ENCODINGutf-8 set CODEX_OUTPUT_BOMfalse echo CodeX 环境已配置UTF-8 无 BOM codex %*PowerShell 版codex_env.ps1param([Parameter(ValueFromRemainingArguments$true)][string[]]$Arguments)$OutputEncoding[System.Text.UTF8Encoding]::new($false)[Console]::OutputEncoding [System.Text.UTF8Encoding]::new($false)$env:CODEX_OUTPUT_BOM false$env:CODEX_OUTPUT_ENCODING utf-8Write-HostCodeX 环境已配置UTF-8 无 BOM-ForegroundColor Green codex ArgumentsWSL2 版~/.codex_env.sh#!/bin/bashexportCODEX_OUTPUT_ENCODINGutf-8exportCODEX_OUTPUT_BOMfalse# 如果输出到 Windows 盘自动转码aliascodex_wincodex $ | iconv -f utf-8 -t gbkechoCodeX 环境已配置UTF-8 无 BOMWindows 盘自动转码个人经验性建议别在原生 CMD 上死磕。如果你必须用 Windows 原生终端PowerShell 5.1 或 Windows Terminal 是更好的选择。CMD 的编码处理机制太老了修修补补不如直接换。WSL2 是首选但注意文件系统边界。CodeX 本身在 WSL2 里跑得很稳但一旦涉及/mnt/c/的 I/O就要多留个心眼。我现在的做法是所有 CodeX 输出都先写到 WSL2 的/tmp/或~/需要时再用cp或scp复制到 Windows 盘。环境变量比终端设置更可靠。CODEX_OUTPUT_ENCODING和CODEX_OUTPUT_BOM这两个环境变量是 CodeX 官方文档里没写清楚的至少我翻的时候没找到但实测它们能绕过终端编码的干扰直接从源头控制输出格式。遇到乱码先别慌三步排查法第一步codex query test看英文是否正常——如果英文也乱是终端字体问题。第二步codex query 测试 output.txt然后用 Notepad 或 VS Code 打开看——如果文件正常是终端显示问题。第三步echo $OutputEncodingPowerShell或chcpCMD检查当前编码——如果显示 65001 但还乱就是 BOM 问题。最后说句实在话编码问题在 2024 年还不应该成为开发者的绊脚石但现实就是 Windows 和 Linux 的编码历史包袱太重。CodeX 作为一个新兴工具在跨平台编码处理上还有改进空间。如果你遇到我上面没覆盖到的场景欢迎在评论区补充——我每个月会整理一次新的踩坑记录。