解决 hf-cli 安装报错：gbk codec can’t encode character ‘\u2713’ 编码异常完整修复指南

一、报错现象

执行 Hugging Face 官方一键安装命令：

powershell

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

安装末尾校验阶段直接抛出错误，安装流程中断失败：

plaintext

[19:36:47] [ERROR] Installation verification failed: Error: Invalid value. 'gbk' codec can't encode character '\u2713' in position 5: illegal multibyte sequence
[19:36:47] [ERROR] Installation failed: Installation verification failed

二、报错根因拆解

1. \u2713 是 Unicode 对勾符号 ✓，hf-cli 安装脚本在校验完成后，会打印该特殊符号作为成功标识；
2. 国内 Windows 默认控制台编码为 GBK（代码页 936），GBK 字符集不收录这类特殊 Unicode 符号；
3. 程序输出日志、控制台打印时，使用 GBK 编码写入内容，无法转义对勾字符，直接抛出编码异常，导致安装校验判定失败、整体安装回滚。

简单说：系统编码不兼容脚本里的特殊对勾符号。

三、四种分层修复方案（从临时应急到永久根治）

方案 1：当前终端临时切换 UTF-8（最快，推荐安装前执行）

打开 PowerShell，先执行两行编码切换命令，再运行安装脚本，仅当前窗口生效：

powershell

# 控制台输出编码切换为UTF-8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
# 强制Python/子进程IO使用UTF-8，规避日志编码报错
$env:PYTHONIOENCODING="utf-8"

# 再执行hf-cli一键安装命令
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

优势：无需重启、不修改系统配置，单次安装专用；

局限：关闭终端后编码配置失效，下次重装仍需重新执行。

方案 2：修改本地安装脚本，删除特殊符号（规避编码冲突）

不想修改系统编码环境，可下载脚本到本地、剔除对勾符号后手动安装：

1. 下载官方安装脚本到本地

powershell

irm https://hf.co/cli/install.ps1 -OutFile hf-install.ps1

2. 使用记事本打开 hf-install.ps1，全局检索关键词：0x2713、✓；
3. 将所有对勾符号替换为普通文字 OK 或直接删除；
4. 修复完成后本地执行安装：

powershell

.\hf-install.ps1

方案 3：全局开启 Windows UTF-8 Beta 支持（一劳永逸根治所有编码报错）

该方案会把系统全局代码页改为 UTF-8，后续 Python、PowerShell、各类工具都不会再出现 GBK 多字节编码错误。

图形化操作步骤

1. Win+R 输入 control 打开控制面板 → 时钟和区域 → 区域；
2. 切换至「管理」标签页，点击「更改系统区域设置」；
3. 勾选选项：Beta 版：使用 Unicode UTF-8 提供全球语言支持；
4. 点击确定，重启电脑即可永久生效。

PowerShell 管理员一键修改注册表

以管理员身份打开 PowerShell，执行命令修改系统代码页注册表：

powershell

# 设置系统默认编码页为UTF-8(65001)
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage" -Name "ACP" -Value 65001
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\Nls\CodePage" -Name "OEMCP" -Value 65001
Write-Host "配置修改完成，重启电脑后全局UTF-8生效"

方案 4：Python 环境专用补充修复

若报错来自 huggingface-hub Python 库校验流程，执行前强制 UTF-8 环境变量：

powershell

$env:PYTHONIOENCODING="utf-8"
# 校验命令示例
python -c "import huggingface_hub;print(huggingface_hub.__version__)"

四、安装成功校验

修复编码问题完成安装后，新开 PowerShell 窗口验证 hf-cli：

powershell

hf version
hf --help

正常输出版本号与帮助文档即代表安装无异常。

五、补充避坑总结

1. 报错只出现在安装校验收尾阶段，并非下载脚本失败，是日志输出编码不兼容；
2. 临时编码适合临时测试、办公受限无法修改系统设置场景；
3. 长期做 AI 模型、Python 开发，强烈推荐开启系统 UTF-8 全局支持，彻底解决中文、特殊符号、日志乱码 / 编码崩溃问题；
4. 线上一键 irm | iex 脚本虽便捷，但遇到编码冲突时，优先下载本地修改符号再执行，可控性更高。