VX 故障排除指南

快速诊断：从 vx doctor 开始进行诊断。使用 vx --debug <command> 获取详细日志。使用 vx cache clean 清除损坏的状态。检查退出码（2=工具未找到，3=安装失败，4=版本未找到，5=网络错误）。

常见问题

安装失败

工具下载失败

症状：Failed to download <tool>: network error 或 Connection refused

解决方案：

# 启用 CDN 加速（中国用户）
vx config set cdn_acceleration true

# 使用镜像源
vx install node --mirror https://npmmirror.com/mirrors/node

# 以详细输出重试
vx install node --verbose --debug

# 清理缓存后重试
vx cache clean
vx install node

校验和不匹配

症状：Checksum mismatch: expected X, got Y

解决方案：

# 清除损坏的下载文件
vx cache clean

# 强制重新安装以获取全新下载
vx install node@22 --force

权限被拒绝

症状：Permission denied 或 Access is denied

解决方案：

# 检查 VX_HOME 的权限
ls -la ~/.vx

# 修复权限（Unix 系统）
chmod -R u+rw ~/.vx

# 如有必要，以提升权限运行
sudo vx install node  # 不推荐，建议使用用户级安装

版本问题

版本未找到

症状：Version X not found for <tool>

解决方案：

# 列出可用版本
vx versions node

# 使用最新稳定版
vx install node@latest

# 使用 LTS 版本
vx install node@lts

# 检查拼写错误
vx versions node | grep "20"

版本冲突

症状：已安装多个版本，当前激活的版本错误

解决方案：

# 列出已安装的版本
vx list node --installed

# 切换到特定版本
vx switch node@20

# 检查当前激活的版本
vx which node

# 卸载冲突的版本
vx uninstall node@18

PATH 问题

命令未找到

症状：安装后提示 command not found: node

解决方案：

# 验证 vx shim 目录是否在 PATH 中
echo $PATH | grep -o ".vx/bin"

# 将 vx 添加到 PATH（需添加到 shell 配置文件中）
export PATH="$HOME/.vx/bin:$PATH"

# 或直接使用 vx 命令
vx node --version

# 检查 shim 文件是否存在
ls ~/.vx/bin/node

PATH 中版本错误

症状：系统自带版本优先于 vx 安装的版本

解决方案：

# 检查实际使用的可执行文件
which node
vx which node

# 调整 PATH 顺序（vx 应排在前面）
export PATH="$HOME/.vx/bin:$PATH"

# 或显式使用 vx
vx node --version

运行时问题

工具启动崩溃

症状：工具立即退出或崩溃

解决方案：

# 检查工具版本
vx which node
vx node --version

# 重新安装工具
vx install node --force

# 检查缺失依赖
vx doctor

# 使用调试输出尝试
vx node --verbose script.js

缺少依赖项

症状：error while loading shared libraries 或 DLL not found

解决方案：

# 检查依赖（Linux 系统）
ldd $(vx which node)

# 安装系统依赖
# Ubuntu/Debian
sudo apt-get install build-essential libssl-dev

# macOS（通过 Homebrew）
brew install openssl

# Windows —— 通常已打包，检查 PATH

配置问题

vx.toml 未加载

症状：vx.toml 中的设置未生效

解决方案：

# 验证文件位置
ls vx.toml

# 检查语法
vx check

# 验证配置
vx config validate

# 显示有效配置
vx config show

锁文件冲突

症状：vx.lock is out of sync

解决方案：

# 重新生成锁文件
vx lock --update

# 或删除后重建
rm vx.lock
vx lock

诊断命令

系统信息

# 通用诊断
vx doctor

# 系统信息
vx info

# 环境检查
vx check --json

# 显示配置
vx config show

调试模式

# 启用调试日志
vx --debug node --version

# 启用追踪日志
vx --trace node --version

# 详细输出
vx --verbose install node

CI 日志排查（结构化处理）

在调试 GitHub Actions 时，不要直接阅读完整日志。应先查看结构化状态，再进行限定范围搜索，最后使用紧凑模式获取宽泛上下文：

# 不带日志的作业状态
vx gh run view <run-id> --json status,conclusion,jobs --jq '.jobs[] | {name,conclusion}'

# 聚焦失败信息搜索
vx gh run view <run-id> --log | vx rg -n -m 80 "error|failed|panic|Traceback|FAILED|warning"

# 广泛回退 + 紧凑过滤
vx --compact gh run view <run-id> --log

关键词搜索需谨慎解读。通过的测试可能包含如 returns_failure_envelope PASSED 的名称，构建命令也可能包含 --warnings-as-errors 等标志。请确认作业结论及上下文行，避免误判匹配为根本原因。

缓存检查

# 显示缓存路径
vx cache dir

# 显示缓存大小
vx cache info

# 列出缓存项
vx cache list

# 清除缓存
vx cache clean

错误信息参考

常见错误

退出码

恢复流程

完全重置

bash

备份配置

cp -r ~/.vx ~/.vx.backup

清除所有内容

rm -rf ~/.vx

重新安装

vx install node go uv

恢复配置

cp ~/.vx.backup/vx.toml ~/.vx/

### 修复安装

验证并修复

vx doctor --fix

从 vx.toml 重新安装所有工具

vx sync --force

重建 shims

vx shim rebuild

## 获取帮助

### 收集诊断信息

生成诊断报告

vx doctor --output diagnostics.txt

包含在问题报告中

cat diagnostics.txt

### 建议提供的信息

1. vx 版本：`vx --version`
2. 操作系统：`vx info | grep -i os`
3. 出错的命令
4. 错误信息（使用 `--debug` 参数获取）
5. `vx.toml` 内容（如适用）
6. `vx doctor` 输出结果

### 支持渠道

- GitHub 问题页面：https://github.com/loonghao/vx/issues
- 文档地址：https://github.com/loonghao/vx#readme

## AI 代理快速排查指南

当用户报告 vx 问题时，请按以下决策流程进行排查：

1. "command not found: vx"

→ vx 未安装。运行安装脚本。

→ Linux/macOS：curl -fsSL https://raw.githubusercontent.com/loonghao/vx/main/install.sh | bash

→ Windows：powershell -c "irm https://raw.githubusercontent.com/loonghao/vx/main/install.ps1 | iex"

1. "Failed to download" / "network error"（退出码 5）

→ 尝试：vx cache clean && vx install <tool> --verbose

→ 若位于中国：vx config set cdn_acceleration true

→ 检查是否设置了 GITHUB_TOKEN 以避免 API 速率限制

1. "version not found"（退出码 4）

→ 运行：vx versions <tool> 查看可用版本

→ 用户可能输入了错误的版本名称

→ 尝试：vx install <tool>@latest

1. "permission denied"（退出码 6）

→ 检查：ls -la ~/.vx（Unix 系统）或 icacls %USERPROFILE%\.vx（Windows）

→ 修复：chmod -R u+rw ~/.vx

→ 请勿使用 sudo 执行 vx 命令

1. 工具可运行但版本错误

→ 运行：vx which <tool> 查看当前激活的版本

→ 检查：vx.toml 可能指定了其他版本

→ 运行：vx switch <tool>@<version>

1. vx.toml 未被识别（退出码 7）

→ 确保文件位于项目根目录（与 .git 同级）

→ 运行：vx check 验证语法正确性

1. CI 流水线中使用 vx 失败

→ 确保使用 GitHub Action：loonghao/vx@main

→ 添加 github-token 以避免速率限制

→ 使用 cache: 'true' 提升 CI 速度

→ 日志排查顺序：--json --jq，然后是 vx rg，最后是 vx --compact

1. 一般性错误（退出码 1）

→ 运行：vx doctor 获取完整诊断信息

→ 运行：vx --debug <command> 获取详细日志

→ 检查：vx cache clean 清除损坏的状态