Zoxide 下载指南：在 macOS、Windows、Linux 上安全快速安装
如果你正在搜索 “zoxide download”，你真正需要的只有两件事：可信的下载源，以及一条不踩坑的安装路径。本指南只讲可执行的步骤，不讲废话：告诉你官方来源、各平台最快的安装命令，以及避免“装上却不能用”的验证与排错方法。
为什么要聚焦 “zoxide download”
- 搜索用户需要清晰、可信的下载路径。非官方镜像或随意脚本可能带来恶意文件或过期版本。
- 搜索引擎青睐能回答 “去哪下、怎么装、如何验证” 的页面。我们逐条覆盖。
- 提前讲透 PATH、初始化和版本问题，可以显著减少“zoxide 不工作”的求助。
只用官方渠道下载
选择这些来源，避免被篡改的二进制：
- GitHub Releases：https://github.com/ajeetdsouza/zoxide/releases
- 官方包管理器（首选）：Homebrew、Scoop、winget、apt、dnf、pacman、cargo
- 避免从来路不明的脚本或镜像站复制命令。
各平台最快安装路径
挑与你系统匹配的命令。如果首选失败，尝试下方备用方案。
macOS
- Homebrew（推荐）：
- 手动（无 Homebrew 时）：从 GitHub Releases 下载 macOS 压缩包，解压后放到
/usr/local/bin，并执行chmod +x /usr/local/bin/zoxide。
Windows
- Scoop（最稳定）：
- winget（新版 Windows 自带）：
- Chocolatey（可选）：
Linux
- Debian/Ubuntu：
- Fedora / RHEL / CentOS：
- Arch / Manjaro：
- Cargo（全平台，需 Rust）：
在改 shell 配置前先验证安装
安装后立即检查：
如果上述命令失败，先解决 PATH，再去改 shell 配置。
初始化 Shell（多数人漏掉的关键步骤）
Zoxide 需要一个 hook 才能学习你的跳转轨迹。把对应片段加入配置文件，然后重载 Shell。
- Bash (~/.bashrc)：
- Zsh (~/.zshrc)：
- Fish (~/.config/fish/config.fish)：
- PowerShell ($PROFILE)：
重载终端并测试：
常见错误与快速修复
- 二进制不在 PATH
- 症状：
zoxide --version失败。 - 解决：确保包管理器的 bin 目录已在 PATH（如
/opt/homebrew/bin、~/.cargo/bin、%USERPROFILE%\scoop\shims等）。
- 未添加 Shell 初始化
- 症状：
z存在但不记录目录。 - 解决：添加上方 init 片段并重启终端。
- 来自非官方的旧版本
- 症状：缺少新参数或异常崩溃。
- 解决：用官方包管理器或 GitHub Releases 重新安装，清理旧的自定义路径副本。
- 公司代理 / SSL 拦截
- 症状：安装命令无法访问 GitHub。
- 解决：为包管理器配置代理（如
git config --global http.proxy ...），然后重试官方命令。
- 冲突的别名
- 症状：
z被其他工具占用。 - 解决：运行
type z查看实际指向，删除旧别名后再重载 Shell。
保持最新（让 “zoxide download” 始终安全）
- Homebrew：
brew upgrade zoxide - Scoop：
scoop update zoxide - winget：
winget upgrade zoxide - Cargo：
cargo install --force zoxide - 随时查看版本：
zoxide --version
速查自检清单
zoxide --version有输出 ✅type z显示来自 zoxide 的函数 ✅z ~能跳回家目录，z -能返回上一目录 ✅zoxide query project返回路径 ✅ 若有一步失败，请用官方渠道重装并重新执行 init 片段。
面向 “zoxide download” 搜索者的 FAQ
- 能离线装吗？ 可以。从 GitHub Releases 下载二进制放入 PATH，再手动添加 init 片段。
- WSL 支持吗？ 支持。在 WSL 内用 Linux 包管理器安装，并在 WSL 的 shell 配置中加入 init。
- 能便携使用吗？ 可以把二进制放在项目目录直接调用，但它仍会写数据库到用户目录，除非设置
_ZO_DATA_DIR。 - 如何卸载？ 用包管理器卸载（如
brew uninstall zoxide），并从 shell 配置移除 init 片段。
接下来做什么
- 访问官方下载页：https://zoxide.org/zh/download
- 添加 init 片段，重载 shell，测试
z、zi和zoxide query。 - 收藏本指南，让团队都有一套安全可重复的 zoxide download 流程。