Windows 中文编码检查清单
> 安全声明：本技能是检查清单与方法指引，所有命令示例均由你在本地自行决定是否执行；技能本身不自动读取、修改、删除你的任何文件，也不收集或外传任何凭据与数据。
适用场景
检查 Windows 中文系统上的 Python 脚本、安装包、subprocess 调用时的编码正确性。
核心规则
系统命令输出用 GBK，用户文件用 UTF-8。
Windows 中文系统（CP936/GBK）的 subprocess 输出默认是 GBK 编码，不是 UTF-8。
检查清单
1. subprocess 调用
检查所有 subprocess.run() 调用：
- ✅ 先尝试
utf-8，失败再尝试gbk— 最佳兼容方案 - ⚠️ 只用
gbk— 现代 Windows (Win10 1903+) 可能输出 UTF-8，会乱码 - ❌ 只用
utf-8— 旧系统输出 GBK 会报错 - ⚠️ 不指定 encoding — 返回 bytes，需要手动解码
# 最佳方案：先 UTF-8 后 GBK（兼容新旧系统）
for encoding in ["utf-8", "gbk"]:
try:
result = subprocess.run(
["where.exe", "python"],
capture_output=True,
text=True,
timeout=5,
encoding=encoding,
)
if result.returncode == 0:
# 解析结果...
break
except UnicodeDecodeError:
continue
# 错误：只用 GBK（现代 Windows 会乱码）
result = subprocess.run(["where.exe", "python"], capture_output=True, encoding="gbk")
2. 文件读写
- ✅
encoding="utf-8"— 读取用户写的配置文件、JSON、YAML、TXT - ✅
encoding="gbk"— 读取 Windows 系统生成的文件（如某些日志） - ⚠️ 不指定 encoding — 会用系统默认编码（GBK），可能导致跨平台问题
# 正确：用户文件用 UTF-8
with open("config.json", encoding="utf-8") as f:
data = json.load(f)
# 不确定编码时的安全写法
try:
with open(path, encoding="utf-8") as f:
content = f.read()
except UnicodeDecodeError:
with open(path, encoding="gbk") as f:
content = f.read()
3. 路径处理
- ✅ 使用
pathlib.Path— 自动处理编码 - ⚠️ 字符串拼接路径 — 确保编码一致
- ❌ 硬编码路径含中文 — 可能在不同编码环境下出错
4. stderr 捕获
Python 的 stderr 在中文 Windows 上是 GBK 编码：
# 正确
result = subprocess.run(
["python", "script.py"],
capture_output=True,
encoding="gbk",
errors="replace" # 无法解码的字符用 ? 替代，避免崩溃
)
常见错误症状
| 症状 | 原因 | 修复 |
|---|---|---|
中文用户名显示为乱码（如 һֻС） |
subprocess 用 UTF-8 读 GBK 输出 | 改用 encoding="gbk" |
UnicodeDecodeError: 'gbk' |
文件是 UTF-8 但用 GBK 读 | 改用 encoding="utf-8" |
PowerShell 输出显示中文为乱码（如 璁板綍、寮€宸?），但无报错 |
PowerShell 默认 GBK 读 UTF-8 文件——静默乱码，不抛异常 | 使用 -Encoding UTF8 参数：Get-Content path -Encoding UTF8 |
UnicodeDecodeError: 'utf-8' |
系统命令输出是 GBK 但用 UTF-8 读 | 改用 encoding="gbk" |
| 中文路径找不到文件 | 路径编码不一致 | 统一用 pathlib.Path |
验证方法
检查脚本时，搜索以下关键词确认编码设置：
grep -n "subprocess" *.py | grep -v "encoding"
grep -n "open(" *.py | grep -v "encoding"
如果没有指定 encoding 的调用，标记为 ⚠️ 待检查。
.bat 文件编码（重要！）
Windows CMD 的 .bat 文件必须用 GBK 编码 + CRLF 换行，否则中文显示乱码、脚本闪退。
问题症状
- .bat 文件双击闪退，无任何输出
- 中文显示为乱码（如
һֻС、锟斤拷） file命令显示UTF-8 text（应该是ISO-8859 text或DOS batch file）
修复方法
# 将 UTF-8 编码的 .bat 文件转为 GBK
with open(path, 'r', encoding='utf-8') as f:
content = f.read()
with open(path, 'w', encoding='gbk') as f:
f.write(content)
生成新 .bat 文件时
# 正确：直接写 GBK 编码
with open('script.bat', 'w', encoding='gbk') as f:
f.write(content)
换行符（CRLF vs LF）
Windows 脚本文件（.bat, .ps1, .cmd）必须用 CRLF 换行。如果用 patch 工具或 write_file 写入，可能混入 LF 换行，导致行为异常。
# 检测并修复
with open(path, 'r', encoding='utf-8-sig') as f:
content = f.read()
if '\n' in content.replace('\r\n', ''):
# 有纯 LF 换行，统一为 CRLF
content = content.replace('\r\n', '\n').replace('\n', '\r\n')
with open(path, 'w', encoding='utf-8-sig', newline='') as f:
f.write(content)
文件类型编码参考
| 文件类型 | 编码 | 换行符 |
|---|---|---|
| .bat / .cmd | GBK | CRLF |
| .ps1 | UTF-8 BOM | CRLF |
| .txt / .md | UTF-8 BOM | CRLF |
| .py | UTF-8 | LF (Python 自动处理) |
| .json / .yaml | UTF-8 | 任意 |
⚠️ setx PATH 截断陷阱（1024 字符限制）
setx PATH "%PATH%;新路径" 有 1024 字符硬限制。当 PATH 超长时（CUDA+Python+Git+LM Studio+Node.js 等很容易超），setx 会静默截断后面的路径，导致其他程序命令丢失。
报错信号：警告: 正保存的数据被裁断到 1024 字符。 但命令仍然"成功"保存了截断后的值。
正确做法：用 PowerShell [Environment]::SetEnvironmentVariable，无字符限制：
powershell -Command "$u=[Environment]::GetEnvironmentVariable('Path','User');if($u -notmatch '新路径'){$u+=';新路径'};[Environment]::SetEnvironmentVariable('Path',$u,'User');Write-Host OK"
setx 改的是用户级 PATH（HKCU），系统级 PATH（HKLM）不受影响。但用户级被截断后，Python、npm、LM Studio 等用户安装的软件路径全丢。
⚠️ 使用须知
本技能是检查清单，不是执行指令。
- 遇到编码问题时，先按清单排查，确认问题后再修复，不要假设一定有问题
- 如果不确定某个调用该用什么编码，问用户确认，不要自行猜测
- 修复前先备份，修复后验证效果
- 此规则仅适用于 Windows 中文系统
- Linux/macOS 默认 UTF-8，不需要特殊处理
- Windows 英文系统可能是 CP1252 编码
- PyInstaller 打包后的行为可能与开发环境不同
