zoxide 无法正常工作 - 故障排除指南

如果 zoxide 已安装但表现异常，本指南可以帮助你诊断并修复问题。

常见问题

问题 1：zoxide 命令无法识别

症状：

• z 命令 not found
• zi 命令 not found
• 终端提示 “command not found”

解决方案：

1. 确认初始化写入配置文件：

2. 重新加载配置：

3. 检查二进制是否存在：

问题 2：zoxide 不会学习目录

症状：

• z 一直找不到目录
• 访问历史没有增加

解决方案：

1. 检查数据库位置：

2. 确认权限：

3. 查看环境变量：

4. 手动添加目录测试：

问题 3：性能很慢

症状：

• z 命令响应慢
• CPU 占用高

解决方案：

1. 排除大型目录：

2. 检查数据库大小：

3. 清理旧记录：

4. 缩短最大年龄：

问题 4：跳转到错误目录

症状：

• z project 去了错误目录
• 多个匹配但选中了错误的

解决方案：

1. 使用交互模式：

2. 先列出匹配：

3. 更具体的关键词：

4. 提高频率： 经常使用目标目录，zoxide 会按频率排序。

问题 5：Shell 集成未生效

症状：

• z 能运行但不会切目录
• 没有自动记录目录

解决方案：

1. 确认初始化正确：

2. 确认 Shell 受支持： bash、zsh、fish、PowerShell
3. 手动检查 hook：

诊断步骤

运行这些命令快速定位问题：

平台相关问题

Linux：权限不足

macOS：Homebrew 路径未添加

Windows：PowerShell 执行策略

重置 zoxide

获取帮助

1. 查看 官方文档
2. 搜索 GitHub issues
3. 确认版本是最新的
4. 检查系统兼容性

预防提示

1. 保持更新：

2. 定期维护： 检查数据库大小，排除不必要的目录。
3. 改动后立刻测试： 新终端验证 z 和 zi。

相关文章

• zoxide command not found
• 安装指南
• 高级配置