zoxide - 智能目录跳转
技能脚本入口
本技能附带两套等价包装脚本（Unix .sh + Windows PowerShell .ps1），提供友好子命令入口与安装自检，免去记忆原始参数。
macOS / Linux（bash）：
bash scripts/zoxide-skill.sh <subcommand> [args...]
# 查看完整用法与示例
bash scripts/zoxide-skill.sh help
Windows（PowerShell）：
.\scripts\zoxide-skill.ps1 <subcommand> [args...]
# 若被执行策略拦截，用下面这种调用绕过：
powershell -ExecutionPolicy Bypass -File scripts\zoxide-skill.ps1 <subcommand> [args...]
可用子命令： add、remove、query、query-list、query-interactive、query-score、import、export、prune、db-path、init、init-cmd
脚本选择规则： macOS / Linux 用 .sh；Windows 用 .ps1。两者子命令完全一致。
> 脚本仅作便捷封装，最终调用系统的 zoxide 二进制；运行前请确保已安装对应工具（安装方式见下文各节）。说明：SkillHub 不支持 .cmd / .bat 文件类型，故不附带 Windows cmd 版；无 PowerShell 的环境可用 Git Bash 运行 .sh 版。个别依赖 Unix 管道工具的子命令（如 gron 的 sed / fzf）在 Windows 下建议用 Git Bash 运行 .sh 版。
这是什么
zoxide (ajeetdsouza/zoxide, 38.7k ⭐) 是一个更智能的 cd 命令替代品。它学习你的导航习惯，基于 frecency (频率 + 最近度) 对目录排名，支持模糊匹配。单二进制 (Rust)，零配置开箱即用。
- GitHub: https://github.com/ajeetdsouza/zoxide
- 文档: https://github.com/ajeetdsouza/zoxide#readme
- 兼容 bash、zsh、fish、powershell、elvish、nu、cmd
何时使用我
当用户出现以下意图时加载此技能：
- "zoxide"、"z 命令"、"智能 cd"、"快速跳转目录"
- "cd 太慢"、"目录跳转神器"、"frecency"
- "模糊匹配路径"、"不用输全路径"
- "替代 cd"、"autojump 替代品"、"z.lua 替代品"
- "目录历史管理"、"跳转统计"
核心能力
1. 基础用法 (替代 cd)
# 初始化后直接用 z 代替 cd
z foo # 跳转到匹配 "foo" 的最高分目录
z foo bar # 匹配同时包含 "foo" 和 "bar" 的目录
z /exact/path # 精确路径仍可用 (fallback 到 cd)
# 交互式选择 (配合 fzf)
zi # 打开 fzf 选择历史目录
2. 模糊匹配 (核心优势)
# 假设历史有：
# /home/user/projects/my-awesome-project
# /home/user/projects/another-project
# /home/user/work/client-project
z my-pro # -> /home/user/projects/my-awesome-project
z awesome # -> /home/user/projects/my-awesome-project
z proj # -> 得分最高的 project 目录
z wo cl # -> /home/user/work/client-project (多词匹配)
3. 目录管理
# 添加当前目录到数据库
zoxide add $(pwd)
# 删除目录记录
zoxide remove /path/to/dir
# 查询目录得分
zoxide query foo
zoxide query -l foo # 列出所有匹配及得分
zoxide query -i foo # 交互式选择 (需 fzf)
# 导入现有数据库 (从 autojump/z.lua)
zoxide import --from=autojump ~/.local/share/autojump/autojump.txt
zoxide import --from=z ~/.z_data
4. Shell 集成 (必需步骤)
# Bash (~/.bashrc)
eval "$(zoxide init bash)"
# Zsh (~/.zshrc)
eval "$(zoxide init zsh)"
# Fish (~/.config/fish/config.fish)
zoxide init fish | source
# PowerShell (\$PROFILE)
zoxide init powershell | Out-String | Invoke-Expression
# Nu Shell
zoxide init nu | save ~/.config/nu/zoxide.nu
# Elvish
zoxide init elvish | slurp
# Cmd (Windows)
zoxide init cmd > "%USERPROFILE%\zoxide_init.cmd"
# 然后在注册表或 AutoRun 运行
5. 别名与自定义
# 常用别名 (init 时自动设置，可自定义)
alias z='__zoxide_z' # 普通跳转
alias zi='__zoxide_zi' # 交互式选择
alias zq='__zoxide_zq' # 查询并 cd (非交互)
# 自定义命令名
eval "$(zoxide init bash --cmd j)" # 用 j 代替 z
6. 高级查询
# 仅匹配路径尾部
zoxide query --exact foo
# 仅匹配路径包含
zoxide query --contains foo
# 仅列出 (不 cd)
zoxide query -l foo
# 显示得分细节
zoxide query -s foo
# 输出: 分数 路径
# 12.5 /home/user/projects/foo-bar
7. 数据库维护
# 查看数据库位置
zoxide query --db
# 导出数据库 (备份/迁移)
zoxide export > zoxide_backup.txt
# 清理不存在的路径
zoxide prune
# 重置数据库 (慎用)
rm "\$(zoxide query --db)"
典型工作流示例
场景 1：日常开发目录跳转
# 1. 正常工作，zoxide 自动记录
cd ~/projects/frontend-app
cd ~/projects/backend-api
cd ~/work/client-acme/docs
# 2. 后续直接模糊跳转
z front # -> ~/projects/frontend-app
z back # -> ~/projects/backend-api
z acme # -> ~/work/client-acme/docs
z cli do # -> ~/projects/backend-api (docs 包含 cli)
场景 2：配合 fzf 交互式选择
# 1. 安装 fzf
# 2. 使用 zi 打开选择器
zi
# 界面显示所有历史目录，按 frecency 排序
# 输入模糊过滤，回车 cd 过去
场景 3：多项目并行开发
# 快速在多个项目间切换
z proj-a # 项目 A
z proj-b # 项目 B
z proj-c # 项目 C
# 配合 tmux/sessionizer
# 可写脚本：zoxide query -l | fzf | xargs tmux new-session -c
场景 4：从 autojump/z.lua 迁移
# 1. 导入旧数据
zoxide import --from=autojump ~/.local/share/autojump/autojump.txt
# 2. 或从 z.lua
zoxide import --from=z ~/.z_data
# 3. 验证
zoxide query -l | head -20
场景 5：脚本中使用
# 在脚本中获取目录路径 (不 cd)
PROJECT_DIR=\$(zoxide query --exact my-project)
cd "\$PROJECT_DIR" && ./build.sh
# 或用于生成菜单
zoxide query -l | fzf --prompt="Jump to: " | read -r dir && cd "\$dir"
配置选项 (环境变量)
| 变量 | 默认值 | 说明 |
|---|---|---|
| _ZO_DATA_DIR | ~/.local/share/zoxide | 数据库目录 |
| _ZO_MAXAGE | 10000 | 最大记录条目 (超出触发清理) |
| _ZO_RESOLVE_SYMLINKS | 1 | 解析符号链接 |
| _ZO_EXCLUDE_DIRS | 空 | 排除目录模式 (如 /tmp/*) |
| _ZO_FZF_OPTS | --height 40% | fzf 选项 |
# 示例配置 (~/.bashrc/zshrc)
export _ZO_EXCLUDE_DIRS="/tmp/:/var/tmp/:\$HOME/.cache/*"
export _ZO_FZF_OPTS="--height 50% --reverse --bind=ctrl-k:up,ctrl-j:down"
eval "\$(zoxide init bash)"
与同类工具对比
| 工具 | 语言 | 算法 | 维护状态 | 特色 |
|---|---|---|---|---|
| zoxide | Rust | frecency | 活跃 | 单二进制、多 shell、模糊匹配 |
| autojump | Python | frecency | 低维护 | 老牌、依赖 Python |
| z.lua | Lua | frecency | 维护中 | 嵌入 Lua、速度快 |
| z.sh | Bash | frecency | 低维护 | 纯 Bash、零依赖 |
| fasd | Bash | frecency | 停止 | 文件+目录、功能多 |
安装方式
# macOS (Homebrew)
brew install zoxide
# Linux (包管理器)
apt install zoxide # Debian/Ubuntu 22.04+
dnf install zoxide # Fedora
pacman -S zoxide # Arch
apk add zoxide # Alpine
# Cargo (最新版)
cargo install zoxide --locked
# 二进制下载 (GitHub Releases)
# 单文件，解压到 PATH 目录
# Docker
docker run --rm -it -v "\${HOME}/.local/share/zoxide:/root/.local/share/zoxide" ghcr.io/ajeetdsouza/zoxide z foo
故障排查
| 问题 | 解决方案 |
|---|---|
| "command not found: z" | 检查 `eval "\$(zoxide init bash)"` 在 shell 配置中 |
| 跳转不对 | 运行 `zoxide query foo` 看得分，用 `zoxide remove` 清理错误记录 |
| 符号链接问题 | 设置 `export _ZO_RESOLVE_SYMLINKS=0` 禁用解析 |
| fzf 不工作 | 确认安装 fzf，检查 _ZO_FZF_OPTS |
| 数据库损坏 | `rm "\$(zoxide query --db)"` 重置，或从备份恢复 |
| 权限错误 | 确保数据库目录可写 ~/.local/share/zoxide |
进阶技巧
与 direnv 结合
# .envrc 中
eval "\$(zoxide init bash)"
# 进入项目自动激活环境，同时记录目录
与 tmux sessionizer 结合
# ~/.tmux.conf
bind-key f run-shell "tmux neww ~/.local/bin/tmux-sessionizer"
# ~/.local/bin/tmux-sessionizer
#!/bin/bash
selected=\$(zoxide query -l | fzf)
[[\$ -n \$selected ]] && tmux new-session -c "\$selected" -s "\$(basename "\$selected")"
同步多机器
# 导出
zoxide export | gpg -c > zoxide_backup.gpg
# 导入 (另一台机器)
gpg -d zoxide_backup.gpg | zoxide import
相关技能
- fzf - 模糊查找器 (zi 依赖 fzf)
- fd - 快速查找文件 (配合目录跳转)
- lsd - 现代 ls 替代 (跳转后列目录)
- yazi - 终端文件管理器 (可视化导航)
- zellij - 终端复用器 (会话管理)
技能版本: 1.0.0 | 作者: asdw741111 | 适用平台: OpenCode, Claude Code, Cursor, Codex CLI, Windsurf, Gemini CLI
