版本: 基于 Yazi 26.1.x 官方文档整理
更新时间: 2026年3月

终端里敲 ls、cd、rm，文件多了眼花缭乱。想用鼠标？对不起，这是 CLI 世界。

有没有一个工具，能在终端里像 GUI 文件管理器那样操作，还能保持键盘流的高效？

Yazi 就是答案。

📋 目录

  1. 什么是 Yazi
  2. 核心特性一览
  3. 安装指南
  4. 配置基础
  5. 基本使用技巧
  6. 快捷键详解
  7. 插件系统
  8. 性能优化原理
  9. 实用配置示例
  10. 常见问题

什么是 Yazi

Yazi（意为「鸭子」）是一个用 Rust 编写的终端文件管理器，基于非阻塞异步 I/O 设计。定位类似 ranger 和 lf，但性能更强、功能更现代：

  • 全异步架构：所有 I/O 操作异步执行，CPU 任务多线程分散
  • 内置图片预览：支持 Kitty、iTerm2、Sixel 等多种协议
  • 代码高亮：内置语法高亮，无需依赖外部工具
  • 插件系统：Lua 插件扩展，UI、预览器、功能插件都能自定义
  • 包管理器：一键安装/更新插件和主题

项目地址：https://github.com/sxyazi/yazi

核心特性一览

滚动预览

预览各种类型文件，还能在预览区滚动内容：

1
2
3
4
5
6
7
8
# 支持预览的文件类型：
# - 图片（PNG、JPEG、GIF、SVG 等）
# - 视频（通过 ffmpeg 生成缩略图）
# - PDF（通过 poppler）
# - 代码文件（内置语法高亮）
# - JSON（通过 jq 格式化）
# - 目录（显示目录内容）
# - 压缩包（通过 7-Zip）

用 J/K 滚动预览内容，无需打开文件。

可视模式与批量重命名

Vim 风格的可视模式，批量选择文件：

1
2
3
# 按 v 进入可视模式
# 然后用 j/k 选择文件
# 可对选中文件执行：复制、移动、删除、批量重命名

批量重命名时，Yazi 会打开编辑器让你批量修改文件名。

多标签页

类似浏览器，多标签页并行工作：

1
2
3
4
5
# 标签页操作：
# 1-9    快速切换到标签页 1-9
# t      新建标签页
# [ / ]  切换上一个/下一个标签页
# q      关闭当前标签页（最后一个标签页则退出）

搜索集成

集成 fd、rg、fzf、zoxide：

1
2
3
4
5
6
7
8
9
10
11
# 文件名搜索（使用 fd）
# 按 / 进入搜索模式

# 内容搜索（使用 rg）
# 按 s 进入内容搜索

# fzf 快速跳转
# 按 f 使用 fzf 选择文件

# zoxide 历史目录跳转
# 按 z 使用 zoxide 快速导航

任务管理系统

复制、移动等操作由任务系统调度：

1
2
3
4
5
# 任务特性：
# - 实时进度显示
# - 任务可取消
# - 内部优先级分配
# - 异步非阻塞执行

按 w 打开任务管理器查看进度。

增量查找

实时增量查找，显示当前位置和匹配数量：

1
2
3
# 按 f 进入增量查找
# 输入字符实时过滤文件
# 显示匹配数量和当前位置

安装指南

依赖项

必需依赖：

  • file - 文件类型检测

可选依赖（推荐安装）：

1
2
3
4
5
6
7
8
# macOS
brew install ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick

# Arch Linux
sudo pacman -S yazi ffmpeg 7zip jq poppler fd ripgrep fzf zoxide resvg imagemagick

# Ubuntu/Debian
sudo apt install yazi ffmpeg 7zip jq poppler-utils fd-find ripgrep fzf zoxide

包管理器安装

1
2
3
4
5
6
7
8
9
10
11
# macOS
brew install yazi

# Arch Linux
sudo pacman -S yazi

# Nix
nix-env -iA nixpkgs.yazi

# Cargo（需要 Rust 环境）
cargo install --locked yazi

手动下载

从 Release 页面 下载预编译二进制：

1
2
3
4
# Linux / macOS
tar -xvf yazi*.tar.gz
chmod +x yazi
mv yazi ~/.local/bin/

启动方式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 直接启动
yazi

# 启动并退出时输出当前目录（适合 shell 集成）
yazi --cwd-file=/tmp/yazi-cwd

# Shell 集成（添加到 shell 配置）
# Bash (~/.bashrc)
function y() {
    tmp="$(mktemp -t "yazi-cwd.XXXXXX")"
    yazi --cwd-file="$tmp"
    cwd="$(cat "$tmp")"
    if [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        cd "$cwd"
    fi
    rm -f "$tmp"
}

# Fish (~/.config/fish/functions/y.fish)
function y
    set tmp (mktemp -t "yazi-cwd.XXXXXX")
    yazi --cwd-file=$tmp
    set cwd (cat $tmp)
    if [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]
        cd $cwd
    end
    rm -f $tmp
end

配置基础

配置文件位置

1
2
3
4
5
6
7
8
9
10
# Unix-like 系统
~/.config/yazi/
├── yazi.toml      # 主配置
├── keymap.toml    # 快捷键配置
├── theme.toml     # 主题配置
├── init.lua       # Lua 初始化脚本
└── plugins/       # 插件目录
    └── foo.yazi/
        ├── main.lua
        └── README.md

生成默认配置

1
2
3
4
5
# Yazi 会自动使用默认配置
# 如需自定义，创建配置文件即可

# 示例：创建 yazi.toml
mkdir -p ~/.config/yazi

主配置 yazi.toml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# ~/.config/yazi/yazi.toml

[mgr]
# 布局比例：[父目录, 当前目录, 预览]
ratio = [1, 4, 3]

# 排序方式
sort_by = "natural"        # none, mtime, btime, extension, alphabetical, natural, size, random
sort_sensitive = false     # 是否区分大小写
sort_reverse = false       # 反向排序
sort_dir_first = true      # 目录优先

# 显示隐藏文件
show_hidden = false
show_symlink = true

# 滚动偏移（光标上下保留的文件数）
scrolloff = 5

# 行模式（右侧显示的信息）
linemode = "none"          # none, size, btime, mtime, permissions, owner

[preview]
# 预览设置
wrap = "no"                # 代码预览换行
tab_size = 4               # Tab 宽度
max_width = 600            # 图片预览最大宽度
max_height = 900           # 图片预览最大高度

[opener]
# 文件打开器配置
edit = [
    { run = 'nvim "$@"', block = true, desc = "nvim" },
]
open = [
    { run = 'open "$@"', desc = "macOS open" },
]

[open]
# 文件类型与打开器映射
rules = [
    { mime = "text/*", use = "edit" },
    { mime = "image/*", use = "open" },
    { name = "*.md", use = "edit" },
]

基本使用技巧

首次启动

1
2
yazi      # 启动
yy        # 如果配置了 shell 函数 y

启动后看到三栏布局：

  • 左栏：父目录
  • 中栏：当前目录（主操作区）
  • 右栏：文件预览

基本导航

1
2
3
4
5
6
7
8
9
10
11
# Vim 风格导航
j / k      # 下/上移动光标
h / l      # 进入父目录/进入子目录
gg / G     # 顶部/底部

# 快速跳转
数字 + G   # 跳转到指定行（如 5G 跳到第 5 行）

# 翻页
Ctrl+d / Ctrl+u  # 下翻半页/上翻半页
Ctrl+f / Ctrl+b  # 下翻一页/上翻一页

文件操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 选择文件
Space      # 选择/取消当前文件
v          # 进入可视模式（批量选择）
V          # 退出可视模式
Ctrl+a     # 选择所有文件
Ctrl+r     # 反选

# 复制/移动/删除
y          # 复制（yank）
x          # 剪切
p          # 粘贴
d          # 删除到回收站
D          # 永久删除

# 创建/重命名
a          # 新建文件
r          # 重命名
;          # 新建目录

搜索与跳转

1
2
3
4
5
6
7
8
9
10
11
# 增量查找
f          # 进入查找模式，输入字符实时过滤

# 文件搜索（使用 fd）
/          # 搜索文件名
s          # 搜索文件内容（使用 rg）

# fzf/zoxide 集成
f          # fzf 快速跳转（按两次）
z          # zoxide 历史目录跳转
Z          # zoxide 子目录跳转

打开文件

1
2
3
4
5
6
Enter      # 用默认程序打开
o          # 打开方式选择器
O          # 用指定打开器打开

# 编辑器
e          # 用 $EDITOR 打开

快捷键详解

快捷键配置 keymap.toml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# ~/.config/yazi/keymap.toml

[mgr]
prepend_keymap = [
    # 添加自定义快捷键（优先级高于默认）
    { on = "<C-a>", run = "select_all", desc = "选择所有文件" },
]

append_keymap = [
    # 添加快捷键（优先级低于默认）
    { on = ["g", "h"], run = "cd ~", desc = "跳转到 Home" },
]

# 完全自定义（覆盖默认）
keymap = [
    { on = "j", run = "arrow 1", desc = "向下移动" },
    { on = "k", run = "arrow -1", desc = "向上移动" },
]

快捷键语法

1
2
3
4
5
6
7
8
9
10
11
12
13
# 单键
{ on = "j", run = "arrow 1" }

# 组合键
{ on = "<C-a>", run = "select_all" }     # Ctrl + a
{ on = "<S-a>", run = "action" }         # Shift + a
{ on = "<A-a>", run = "action" }         # Alt + a

# 序列键
{ on = ["g", "h"], run = "cd ~" }        # 先 g 后 h

# 多动作
{ on = "x", run = ["yank", "remove"], desc = "剪切" }

常用快捷键表

快捷键 动作 说明
j/k arrow 下/上移动
h/l leave/enter 父目录/子目录
gg/G 顶部/底部
Space select 选择文件
v visual 可视模式
y/x/p yank/cut/paste 复制/剪切/粘贴
d/D remove 删除到回收站/永久删除
a/r create/rename 新建/重命名
Enter open 打开文件
o open –chooser 选择打开方式
/ search fd 搜索文件名
s search rg 搜索内容
f find 增量查找
z/Z zoxide 历史目录跳转
t tab_create 新建标签页
1-9 tab_switch 切换标签页
q quit 退出
w tasks_show 任务管理器
? help 帮助菜单
. toggle_hidden 显示隐藏文件
Ctrl+s shell 执行 shell 命令

插件系统

插件结构

1
2
3
4
5
~/.config/yazi/plugins/
└── my-plugin.yazi/
    ├── main.lua      # 入口文件
    ├── README.md     # 文档
    └── LICENSE       # 许可证

使用插件

功能插件（绑定快捷键）：

1
2
3
4
5
# ~/.config/yazi/keymap.toml
[[mgr.prepend_keymap]]
on = "T"
run = "plugin toggle-pane max-preview"
desc = "最大化预览面板"

预览器插件：

1
2
3
4
5
# ~/.config/yazi/yazi.toml
[plugin]
prepend_previewers = [
    { name = "*.md", run = "glow" },  # Markdown 渲染
]

官方插件

Yazi 提供官方插件仓库：yazi-rs/plugins

1
2
3
4
5
6
7
8
# 使用包管理器安装
ya pack -a yazi-rs/plugins:git         # Git 集成
ya pack -a yazi-rs/plugins:mount       # 挂载管理
ya pack -a yazi-rs/plugins:chmod       # 权限修改
ya pack -a yazi-rs/plugins:full-border # 边框美化

# 或手动克隆
git clone https://github.com/yazi-rs/plugins ~/.config/yazi/plugins

插件示例

1
2
3
4
5
6
7
8
9
10
11
12
13
-- ~/.config/yazi/plugins/test.yazi/main.lua
return {
    entry = function(self, job)
        -- job.args 获取参数
        ya.dbg(job.args[1])
        
        -- 获取当前文件
        local hovered = cx.active.current.hovered
        if hovered then
            ya.dbg("当前文件: " .. hovered.url)
        end
    end,
}

初始化脚本 init.lua

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
-- ~/.config/yazi/init.lua

-- 设置插件配置
require("full-border"):setup {
    type = "rounded",  -- 边框样式
}

-- 自定义 linemode
function Linemode:size_and_mtime()
    local time = math.floor(self._file.cha.mtime or 0)
    local size = self._file:size()
    return string.format("%s %s", 
        size and ya.readable_size(size) or "-",
        time > 0 and os.date("%b %d %H:%M", time) or ""
    )
end

性能优化原理

Yazi 为什么快？几个关键设计：

全异步架构

所有 I/O 操作都是异步的：

1
2
3
4
5
6
# 异步任务类型：
# - 目录加载
# - 文件预览
# - 图片处理
# - 代码高亮
# - 任务调度

使用 Tokio 作为异步运行时，CPU 任务多线程分散。

分块加载

大目录（如 10 万文件）不会一次性加载：

1
2
3
4
# 分块加载策略：
# - 只加载当前页面的文件
# - 后台预加载后续页面
# - 滚动时动态加载

对比 ls 和 eza 必须加载全部文件，Yazi 响应更快。

预加载机制

预加载器异步处理耗时任务：

1
2
3
4
5
6
# 内置预加载器：
# - Mimetype: 批量计算文件类型
# - Image: 两阶段处理（预处理 + 实时缩放）
# - Video: ffmpeg 提取缩略图
# - PDF: poppler 渲染
# - Directory size: 懒计算（仅按大小排序时）

预加载只处理当前页面的文件，节省资源。

可丢弃任务

切换文件时，未完成的预览任务直接丢弃：

1
2
3
4
# 任务丢弃策略：
# - I/O 任务：Tokio abort
# - CPU 任务：Atomic ticket 检查
# - Lua 任务：定期检查取消标志

避免资源浪费在不再需要的任务上。

内置代码高亮

不需要外部工具如 bat：

1
2
3
4
# 代码高亮优化：
# - 只高亮可见行数
# - 多线程分散处理
# - 外部工具（如 jq）读取后立即终止

其他依赖 bat 的工具需要等待整个文件高亮完成。

实用配置示例

🚀 开发者推荐配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# ~/.config/yazi/yazi.toml

[mgr]
ratio = [1, 4, 4]
sort_by = "natural"
sort_dir_first = true
show_hidden = true
linemode = "size_and_mtime"

[preview]
max_width = 1000
max_height = 1000

[[plugin.prepend_previewers]]
name = "*.md"
run = "glow"
1
2
3
4
5
6
7
8
9
10
11
-- ~/.config/yazi/init.lua
require("full-border"):setup()

function Linemode:size_and_mtime()
    local time = math.floor(self._file.cha.mtime or 0)
    local size = self._file:size()
    return string.format("%s %s",
        size and ya.readable_size(size) or "-",
        time > 0 and os.date("%m/%d %H:%M", time) or ""
    )
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# ~/.config/yazi/keymap.toml
[[mgr.prepend_keymap]]
on = ["g", "h"]
run = "cd ~"
desc = "跳转到 Home"

[[mgr.prepend_keymap]]
on = ["g", "c"]
run = "cd ~/.config"
desc = "跳转到配置目录"

[[mgr.prepend_keymap]]
on = ["g", "d"]
run = "cd ~/Downloads"
desc = "跳转到下载目录"

🎨 主题配置

1
2
3
4
5
6
7
8
9
# ~/.config/yazi/theme.toml

[flavor]
use = "catppuccin-mocha"  # 使用内置主题

# 或自定义颜色
[mgr]
active = { fg = "#cdd6f4", bg = "#1e1e2e" }
hovered = { fg = "#f38ba8", bg = "#313244" }

🔧 快速跳转配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# ~/.config/yazi/keymap.toml

[[mgr.prepend_keymap]]
on = ["g", "r"]
run = "cd /"
desc = "跳转到根目录"

[[mgr.prepend_keymap]]
on = ["g", "w"]
run = "cd ~/Work"
desc = "跳转到工作目录"

[[mgr.prepend_keymap]]
on = ["g", "p"]
run = "cd ~/Projects"
desc = "跳转到项目目录"

常见问题

Q: 图片预览不显示？

A: 检查终端是否支持图片协议：

终端 协议 支持状态
Kitty Kitty Unicode ✅ 内置
iTerm2 Inline Images ✅ 内置
WezTerm Inline Images ✅ 内置
Ghostty Kitty Unicode ✅ 内置
Konsole Kitty Old ✅ 内置
foot Sixel ✅ 内置
Windows Terminal Sixel ✅ 内置（>= v1.22）

确保安装了 ffmpeg（视频预览）和 imagemagick（某些图片格式）。

Q: 如何自定义文件打开方式？

A: 配置 yazi.toml 的 [opener] 和 [open]：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
[opener]
edit = [
    { run = 'nvim "$@"', block = true },
]
image = [
    { run = 'open "$@"', orphan = true },  # macOS
]

[[open.rules]]
mime = "image/*"
use = "image"

[[open.rules]]
name = "*.json"
use = "edit"

Q: 快捷键和 Vim 冲突？

A: Yazi 默认使用 Vim 风格，不冲突。如需自定义：

1
2
3
4
5
# ~/.config/yazi/keymap.toml
[[mgr.prepend_keymap]]
on = "<C-j>"
run = "arrow 1"
desc = "向下移动（Ctrl+j）"

Q: 如何显示隐藏文件？

A: 按 . 切换，或在配置中设置：

1
2
[mgr]
show_hidden = true

Q: 退出后如何跳转到当前目录？

A: 使用 shell 集成（见安装指南的 Shell 集成部分）。

Q: 如何批量重命名？

A:

  1. v 进入可视模式
  2. j/k 选择多个文件
  3. r 批量重命名
  4. 编辑器中修改文件名
  5. 保存退出

与其他文件管理器对比

维度 Yazi ranger lf
语言 Rust Python Go
异步架构 ✅ 全异步 ❌ 部分
图片预览 ✅ 内置多协议 需配置 需配置
代码高亮 ✅ 内置 需要 bat 需要 bat
插件系统 ✅ Lua Python 外部命令
包管理器 ✅ 内置 ❌ ❌
性能 极快 较慢 快
配置复杂度 TOML（简单） Python（复杂） 简单

总结

Yazi 是现代终端文件管理器，核心优势：

优势 说明
性能强悍 全异步 + 分块加载 + 预加载
功能丰富 图片预览、代码高亮、多标签页
扩展灵活 Lua 插件系统 + 包管理器
上手简单 Vim 风格快捷键 + 清晰配置

推荐场景：

  1. 日常文件管理：替代 ls/cd/rm 组合
  2. 远程服务器：SSH 下高效操作文件
  3. 开发工作流：快速浏览项目文件
  4. 批量操作：可视模式批量处理

延伸阅读

💡 提示: 如果你是 ranger 用户，迁移很简单。Yazi 的快捷键风格类似，配置更直观。可以先从默认配置体验，再逐步自定义。