在 SSH 终端里整理文件，最麻烦的往往是反复切换目录：找到一个日志，还得打开看看；看到一批截图，又要记住路径再复制。Yazi 把目录列表、文件预览和复制移动放在同一个终端界面里，适合经常处理项目文件、下载目录和构建产物的人。
它不会改变 Linux 的文件权限，也不会接管 shell。你仍然用编辑器改代码、用 Git 看差异，只是在打开文件之前，多了一个可以浏览和选择文件的界面。下面从安装开始，把预览依赖、常用按键、退出后的目录切换，以及服务器上容易误操作的地方分别说明。
安装前，先看系统和版本
截至 2026 年 10 月 3 日，Yazi 的最新正式发布版本是 26.9.1。项目仍标注为 public beta，配置和插件接口可能变化。包管理器里的版本不一定与上游同步，安装后可以查看版本：
yazi --version
macOS 使用 Homebrew 安装：
brew install yazi
Arch Linux 使用系统软件源：
sudo pacman -S yazi
其他 Linux 发行版先查看自己的软件源；如果没有适合的包，再去发布页面选择与系统及 CPU 架构对应的预编译文件。不要把 macOS、Linux、Windows 的压缩包混用，也不要只按文件名里的版本号选择。
Yazi 需要 file 命令识别文件类型。精简 VPS 镜像可能没有预装，可以先检查：
file --version
缺少时按发行版安装对应软件包。仅安装 Yazi，并不意味着视频、PDF、压缩包等格式都能预览；这些功能需要另外的工具，后面再按用途补齐。
源码编译不是普通用户的必要步骤。如果确实需要编译，固定一个发布标签，比跟着持续变化的主分支更容易对应文档。26.9.1 的 workspace 声明 Rust 最低版本为 1.95.0，先确认工具链符合要求：
rustc --version
使用 rustup 的环境可以更新稳定工具链，再拉取这一版源码：
rustup update stable
git clone --branch v26.9.1 --depth 1 https://github.com/sxyazi/yazi.git
cd yazi
cargo build --release
编译结束后，二进制在 target/release/ 下。编译成功和把程序加入 PATH 是两回事；不要因为当前 shell 找不到 yazi，就重复编译。包管理器安装一般会处理可执行文件路径。
先在一个普通目录里操作
启动程序：
yazi
可以先选下载目录或测试目录，不要第一次就进入数据库数据目录。界面通常分为父目录、当前文件列表和右侧预览区；光标移动时，预览会随当前文件改变。部分格式需要外部依赖，不能预览时先看具体文件类型。
图中是官方文档的完整边框配置示例，用来说明文件列表与预览区的布局；外观包含定制配置，并非刚安装后的默认主题，也不是本机运行截图。
默认键位可以从下面这张表开始：
| 按键 | 用途 |
|---|---|
j / k |
光标向下 / 向上移动 |
h / l |
返回父目录 / 进入光标所在目录 |
Enter 或 o |
打开选中的文件 |
Space |
选中或取消选中当前项 |
v |
进入可视选择模式 |
Esc |
取消选择 |
y / x |
标记为复制 / 剪切 |
p |
粘贴 |
d |
移入回收站 |
D |
永久删除 |
r |
重命名 |
. |
显示或隐藏隐藏文件 |
q |
退出 |
F1 或 ~ |
查看帮助 |
这里有两处值得记住：l 是进入目录，打开文件用 Enter 或 o；d 和大写 D 的后果不同。远程环境里的回收站也不应当作备份，重要文件仍需要独立保存。
复制文件时，先用空格选中，再按 y，进入目标目录后按 p。移动则把 y 换成 x。默认的 P 可以覆盖目标中已经存在的文件，刚开始使用时尤其要看清大小写。
如果打开文件后没有进入你熟悉的编辑器，要检查文件打开规则和环境里的相关程序。Yazi 的文件选择界面与“用哪个程序打开”是两层配置，不必为此重新安装文件管理器。
让退出后的 shell 跟到目标目录
直接运行 yazi，退出后 shell 仍在启动时的目录。这是因为子进程不能直接修改父 shell 的工作目录。解决方法是让 Yazi 写出最后停留的目录，再由 shell 函数执行 cd。
在 Bash 或 Zsh 的配置文件里加入下面的函数。它采用官方快速入门中的 wrapper，函数名改成 yy，方便与平时的命令区分：
function yy() {
local tmp cwd; tmp="$(mktemp -t "yazi-cwd.XXXXXX")"
command yazi "$@" --cwd-file="$tmp"
IFS= read -r -d '' cwd < "$tmp"
[ "$cwd" != "$PWD" ] && [ -d "$cwd" ] && builtin cd -- "$cwd" || builtin true
command rm -f -- "$tmp"
}
Zsh 放进 ~/.zshrc，Bash 放进 ~/.bashrc。重新打开一个终端，或在对应 shell 中重新加载文件。例如 Zsh：
source ~/.zshrc
Bash 则使用：
source ~/.bashrc
以后用函数启动：
yy
浏览到目标目录后按 q，shell 会切换过去。如果这次只想查看文件、退出后保留原目录，使用大写 Q。Fish、PowerShell 等 shell 的语法不同，应使用各自的 wrapper，不能原样粘贴这个 Bash/Zsh 函数。
搜索工具按用途安装
大目录里逐层翻文件比较费时间。Yazi 可以调用现成工具搜索，不必把所有依赖一次装满。
fd 用于按文件名搜索，ripgrep 用于按内容搜索。默认按 s 搜文件名，按大写 S 搜文件内容；fzf 用于模糊选择，按 z 可以在文件子树里定位。zoxide 提供历史目录跳转，对应大写 Z，这一项还依赖 fzf。
macOS 可以安装这几项：
brew install fd ripgrep fzf zoxide
Arch Linux：
sudo pacman -S fd ripgrep fzf zoxide
官方安装文档要求 fzf 至少为 0.53.0。其他发行版的软件包名称可能不同，不能把 Arch 的安装命令直接放到 Ubuntu 执行。工具装好后，也要区分按名称找文件和扫描文件内容：知道文件名片段时，用名称搜索通常更直接；只有一段报错文字时，才需要内容搜索。
经常访问的目录要先进入 zoxide 的历史记录，跳转才有候选结果。空结果不一定是 Yazi 故障，也可能是这个环境还没有记录可用目录。
图片、PDF 和压缩包为什么有的能看，有的不能
预览有两类条件：一类是把文件转换成可显示的内容，另一类是终端能否显示它。缺少转换工具和终端协议不支持，处理办法不同。
Yazi 安装文档列出的可选工具包括：
| 需要处理的内容 | 对应工具 |
|---|---|
| 视频缩略图 | ffmpeg |
| PDF 预览 | poppler |
| JSON 预览 | jq |
| 压缩包预览、解压 | 非 standalone 版本的 7-Zip |
| SVG 预览 | resvg |
| 字体、HEIC、JPEG XL 预览 | ImageMagick，至少 7.1.1 |
只看日志和源代码的 VPS 不必为视频缩略图安装一整套媒体工具。处理 PDF 的机器则先补 poppler，遇到 JSON 预览问题再确认 jq。这种按文件格式排查的方式，比把“预览不正常”统统归到主题上更容易找到原因。
图片显示还要看本地终端。Kitty、iTerm2 等终端使用不同协议；经过 SSH 或 tmux 时，显示路径可能增加一层。可以先退出 tmux，在相同终端直接启动 Yazi，看看问题是否仍然存在，再根据图片预览文档检查对应环境。Überzug++、Chafa 等方案各有适用条件，不是安装其中一个就能修好所有远程显示问题。
Nerd Font 主要影响图标显示。图标变成方框与 PDF 没有预览，并不是同一种故障。服务器上若主要看文本，先把文字、文件操作和目录跳转用顺，图片显示可以后续再处理。
批量重命名前，先确认选中了哪些文件
按空格选中多个文件，再按 r，Yazi 可以调用编辑器进行批量重命名。需要调整一组截图的前缀、清理下载文件名或整理素材编号时，集中编辑文件名比较方便。选择的是哪些项、编辑器保存了哪些修改，仍要由使用者检查。
不要把“在界面里改名”理解成自动防误操作。先在几个副本上确认操作方式，再处理原文件；Git 仓库里可以先查看状态，但 Git 未跟踪的文件和被忽略的内容未必有恢复记录。把扩展名 .jpeg 改为 .jpg 只会改变文件名，也不会重新编码图片。
复制大目录时可以按 w 查看任务管理器，确认后台任务是否完成或失败。界面能继续浏览，不代表复制已经结束；断开 SSH、删除源文件或清理临时目录之前，先检查任务状态与目标文件。
配置先改自己确实需要的部分
Linux 和 macOS 的用户配置一般位于 ~/.config/yazi/。常见文件分工如下：
~/.config/yazi/
├── yazi.toml 主配置
├── keymap.toml 快捷键
├── theme.toml 主题
└── init.lua Lua 初始化
可以先保留默认配置，仅加入 shell wrapper 和需要的搜索工具。默认按键有冲突，再修改 keymap.toml；需要 Git 状态、挂载管理或特殊格式预览，再选择对应插件。
插件和主题要注意匹配版本。旧教程中的配置字段未必适用于 26.9.1，尤其不要把几个不同年份的配置片段直接合成一份。修改前保存原文件，一次改一项；出现问题时就能区分是按键配置、插件还是外部工具造成的。
在 VPS 上使用时，权限仍然按原来的方式管理
Yazi 用什么账号启动，就拥有那个账号的文件权限。日常浏览项目目录使用普通用户即可，不需要为了方便把整个界面以 root 身份运行。数据库目录、/etc 配置和容器挂载的数据卷也不要当下载目录整理，改名或移动都可能让正在运行的服务找不到文件。
对于远程开发机，可以把项目文件、构建输出和临时下载分别放置。需要长期保存的内容安排备份，临时产物再按规则清理；文件管理器提供操作入口，不能代替备份和回滚方案。
如果正准备购买独立的 Linux 开发环境，可以查看雨云的服务器方案，优惠码为 KuZhuJi。选择时按开发工具的内存需求、磁盘容量和自己的访问地区看具体套餐，Yazi 本身不要求购买特定厂商或特定机型。
若只是偶尔登录服务器执行固定命令，原来的 ls、cd 和 less 已经够用。经常在多个目录里找文件、预览内容和整理素材时，再把 Yazi 加入日常环境；先配好退出后的目录切换，通常比先换主题更有用。