环境准备：WSL2 安装
win10安装Hermes，Hermes 原生不支持 Windows，推荐优先安装Ubuntu虚拟机，再在虚拟机里面安装hermes。

Windows 要先开 WSL2（Windows Subsystem for Linux 2），在 Windows 里开一个 Linux 夹层。 你不是装第二个操作系统，你是给 Windows 加一个插件。

系统要求
Windows11任意版本 / Windows 10 要 ≥ 2004。

启用 WSL2
管理员身份打开 PowerShell，执行

启用 WSL

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

启用虚拟机平台（WSL2 必需）

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
执行完后重启电脑

设置 WSL 默认版本为 2

wsl --set-default-version 2

查看当前状态，确认没有报错,没有报错，说明 WSL2 修复成功

wsl --status
提示需要更新 WSL2 Linux 内核，下载并安装 wsl_update_x64.msi

安装完更新包后，再次执行上面的命令

二、常见安装问题及解决方案
以管理员身份打开 PowerShell，输入命令 wsl --install

问题1：提示无效的install，需要升级wsl

更新wsl异常

wsl --update
正在检查更新…
正在下载更新…
正在安装更新…
这个处理器类型不支持该安装程序包。请与产品供应商联系。
说明当前 Windows 系统架构（32位/64位/ARM）与 WSL2 更新包不匹配，或者 CPU 不支持虚拟化。

下载并安装 wsl_update_x64.msi，双击安装，完成后重启电脑

再执行

wsl --set-default-version 2
wsl --install -d Ubuntu-20.04
install等待部署完成， 重新启动电脑。

问题2：win10安装Ubuntu异常错误代码: 0x80072ee7
正在下载: Ubuntu 20.04 LTS
安装过程中出现错误。分发名称: ‘Ubuntu 20.04 LTS’ 错误代码: 0x80072ee7
提前下载指定版本 Ubuntu 20.04 LTS 或 Ubuntu（默认最新版）安装包。

双击解压后的 ubuntu2004.exe，等待安装完成

安装完后设置 WSL2：

wsl --set-version Ubuntu-20.04 2

查看当前状态，确认没有报错,没有报错，说明 WSL2 修复成功

wsl --status
问题3：ubuntu2004.exe安装异常，WSL2 内核未安装
双击ubuntu2004.exe后 Installing, this may take a few minutes…
WslRegisterDistribution failed with error: 0x800701bc
Error: 0x800701bc WSL 2 ??? https://aka.ms/wsl2kernel

Press any key to continue…
双击下载的 wsl_update_x64.msi 文件

再设置默认 WSL 版本为 2

wsl --set-default-version 2

查看当前状态，确认没有报错,没有报错，说明 WSL2 修复成功

wsl --status
再次双击 ubuntu2004.exe

手动安装 MSI 也报错"处理器类型不支持"说明你的系统或 CPU 确实不支持 WSL2，需要降级到 WSL1（不要使用WSL1，后面有其它组件版本不支持）：

设置默认使用 WSL1

wsl --set-default-version 1
重新双击 ubuntu2004.exe 安装即可。

WSL1 同样可以编译安装 Hermes，只是性能稍差，不影响使用。

问题4：安装完wsl_update_x64.msi后 再双击ubuntu2004.exe 还是异常，CPU 虚拟化未开启
Installing, this may take a few minutes…
WslRegisterDistribution failed with error: 0x80370102
Error: 0x80370102 ???
错误 0x80370102 通常表示 BIOS/UEFI 中 CPU 虚拟化未开启，或者 Windows 虚拟机平台功能未生效。

1.PowerShell 执行以下命令，弹出的窗口看版本号2004（Build 19041）是支持wsl2的。

winver

2.检查 CPU 虚拟化是否开启

打开任务管理器=>点击 性能 标签页=>点击左侧 CPU=>右下角看 “虚拟化” 状态：已启用

3.确认 Windows 功能已启用

PowerShell，重新执行：

启用虚拟机平台（WSL2 必需）

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

启用 Hyper-V（部分系统需要）

dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V /all /norestart
执行完重启电脑，然后再双击 ubuntu2004.exe。

总之还没到安装hermes一步就在wsl和ubuntu系统之间反复的折腾。

终于正常进入ubuntu系统了，进行安装hermes。

三、Hermes 安装问题
问题5： WSL 1 is not supported. Please upgrade to WSL 2
ubuntu中运行npm install -g hermes-web-ui异常 WSL 1 is not supported. Please upgrade to WSL 2 or above.

Could not determine Node.js install directory

之前安装wsl2失败，就用了wsl1来试，结果报以上异常，看来必须用wsl2，就按以上步骤来修复安装wsl2。

安装完成后 WSL2 Ubuntu 中安装 hermes-web-ui

安装 Node.js

sudo apt update
sudo apt install -y nodejs npm

安装 hermes-web-ui

sudo npm install -g hermes-web-ui

启动

hermes-web-ui start
默认版本： node v10.19.0 和 npm6.14.4

再次遇到 Could not determine Node.js install directory 错误，改用以下方式：

mkdir -p ~/.npm-global
npm config set prefix ‘~/.npm-global’
echo ‘export PATH=“$HOME/.npm-global/bin:$PATH”’ >> ~/.bashrc
source ~/.bashrc
npm install -g hermes-web-ui
启动后hermes-web-ui后

在 Ubuntu 终端中执行以下命令查看端口监听情况：

ss -tlnp | grep 8648

或者

netstat -tlnp | grep 8648
问题6：npm install -g hermes-web-ui运行异常，Node.js 版本过低
Rebuilding because directory /usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty/prebuilds/linux-x64 does not exist
gyp ERR! configure error
gyp ERR! stack Error: EACCES: permission denied, mkdir ‘/usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty/build’
gyp ERR! System Linux 4.4.0-19041-Microsoft
gyp ERR! command “/usr/bin/node” “/usr/bin/node-gyp” “rebuild”
gyp ERR! cwd /usr/local/lib/node_modules/hermes-web-ui/node_modules/node-pty
gyp ERR! node -v v10.19.0
gyp ERR! node-gyp -v v6.1.0
gyp ERR! not ok
npm WARN notsup Unsupported engine for hermes-web-ui@0.5.32: wanted: {“node”:“>=23.0.0”} (current: {“node”:“10.19.0”,“npm”:“6.14.4”})

npm WARN notsup Not compatible with your version of node/npm: cliui@8.0.1

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! node-pty@1.1.0 install: node scripts/prebuild.js || node-gyp rebuild
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the node-pty@1.1.0 install script.
npm ERR! ‘Error: EACCES: permission denied, access ‘/usr/local/lib’’
……
两个原因导致失败：

Node.js 版本太老：Ubuntu 20.04 默认源里的 Node.js 是 v10.19.0，但 hermes-web-ui 要求 Node.js >= 23.0.0
权限问题：用 sudo npm install -g 安装会导致系统目录权限混乱
解决方案：用 nvm 安装新版 Node.js

nvm（Node Version Manager）可以安装任意版本的 Node.js，且不需要 sudo。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
再用nvm安装Node.js 23

nvm install 23
再重装hermes-web-ui
npm install -g hermes-web-ui
问题7：nvm安装异常 curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused