tech
UnicodeEncodeError
# 在 Windows 运行 `hermes` 命令时提示 UnicodeEncodeError,怎么解决?
有朋友在 Windows 上成功安装了 Hermes Agent,但执行任何命令都报错:
```bash
hermes setup
```
如果你看到的报错和下面这段一致,那就是同一个问题:
```
UnicodeEncodeError: 'gbk' codec can't encode character '\u2695' in position 0: illegal multibyte sequence
```
先说结论:**Hermes 安装成功了,但 Windows 的默认编码(GBK)不支持输出 Unicode 字符(比如 ⚕ 🩺)。**
## 为什么会这样
Windows 中文版默认使用 GBK 编码,而 Hermes 在输出时使用了 Unicode emoji(如 ⚕ 🩺 🐍 等)。GBK 编码不认识这些字符,所以就报错了。
这个问题在很多 Python CLI 工具上都可能出现,不只是 Hermes。
## 解决方法
**方法一:临时设置环境变量(推荐,立即生效)**
在 PowerShell 中执行命令前,先设置编码:
```powershell
$env:PYTHONIOENCODING="utf-8"
hermes setup
```
**方法二:永久设置环境变量**
打开"系统属性 → 环境变量 → 用户变量 → 新建":
- 变量名:`PYTHONIOENCODING`
- 变量值:`utf-8`
保存后重新打开 PowerShell,以后就不需要每次都设置了。
**方法三:修改代码页(辅助方案)**
在 PowerShell 中设置 UTF-8 代码页:
```powershell
chcp 65001
```
然后运行 hermes 命令。但这个方法有时候不生效,建议优先用方法一或方法二。
## 验证是否解决
设置环境变量后,运行:
```powershell
$env:PYTHONIOENCODING="utf-8"
hermes doctor
```
如果正常输出诊断信息,说明问题解决了。
## 补充排查
如果设置编码后仍然报错,检查这几点:
1. **PowerShell 是否最新?** 建议用 Windows Terminal 或新版 PowerShell 7+
2. **是否使用了旧版 cmd?** cmd 的编码问题更严重,建议换 PowerShell
3. **字体是否支持 Unicode?** Windows Terminal 默认支持,旧版控制台可能需要换字体