yazi.toml

[mgr]

ratio

按比例设置管理器布局，为一个包含 3 个元素的数组。例如：

  • [1, 4, 3]：父目录占 1/8 宽度，当前目录占 4/8 宽度，预览区占 3/8 宽度

将某个值设为 0 可以隐藏对应面板，但至少必须有一个面板可见（非零）。

sort_by

文件排序方式。

  • "none"：不排序
  • "mtime"：按最后修改时间排序
  • "btime"：按创建时间排序
  • "extension"：按文件扩展名排序
  • "alphabetical"：按字母顺序排序，例如 1.md < 10.md < 2.md
  • "natural"：按自然顺序排序，例如 1.md < 2.md < 10.md
  • "size"：按文件大小排序
  • "random"：随机排序

sort_sensitive

是否区分大小写排序。

  • true：区分大小写
  • false：不区分大小写

sort_reverse

是否倒序显示文件。

  • true：倒序
  • false：正常顺序

sort_dir_first

是否优先显示目录。

  • true：目录优先
  • false：正常顺序

sort_translit

在排序时对文件名做音译转换（transliterate），例如将 Â 替换为 A，将 Æ 替换为 AE 等。仅在 sort_by = "natural" 时可用。

这对于包含匈牙利语字符的文件很有用。

  • true：启用
  • false：禁用

linemode

行模式：在文件列表每一行的右侧显示与文件相关的信息。

  • "none"：不启用行模式
  • "size"：显示文件的字节大小。注意，目前目录大小仅会在 sort_by = "size" 时被计算，未来可能会改变。
  • "btime"：显示文件创建时间
  • "mtime"：显示文件最后修改时间
  • "permissions"：显示文件权限，仅在 Unix-like 系统上可用
  • "owner"：显示文件所有者，仅在 Unix-like 系统上可用

你也可以指定任意一个长度为 1 到 20 个字符的字符串，并通过 UI plugin 扩展它。这意味着你可以像下面这样，通过 plugin system 实现自己的 linemode：

  1. # ~/.config/yazi/yazi.toml
  2. [mgr]
  3. linemode = "size_and_mtime"
  1. -- ~/.config/yazi/init.lua
  2. function Linemode:size_and_mtime()
  3.     local time = math.floor(self._file.cha.mtime or 0)
  4.     if time == 0 then
  5.         time = ""
  6.     elseif os.date("%Y", time) == os.date("%Y") then
  7.         time = os.date("%b %d %H:%M", time)
  8.     else
  9.         time = os.date("%b %d  %Y", time)
  10.     end
  12.     local size = self._file:size()
  13.     return string.format("%s %s", size and ya.readable_size(size) or "-", time)
  14. end

show_hidden

显示隐藏文件。

  • true：显示
  • false：不显示

show_symlink

在文件名后显示符号链接所指向的路径。

  • true：显示
  • false：不显示

scrolloff

在文件列表中移动光标时，光标上方和下方始终保留的文件数量。

如果该值大于屏幕高度的一半（例如 200），光标会保持居中。

mouse_events

一个字符串数组，表示 plugin system 可接收的鼠标事件类型，可用值包括：

  • "click"：鼠标点击
  • "scroll"：鼠标垂直滚动
  • "touch"：鼠标水平滚动
  • "move"：鼠标移动
  • "drag"：鼠标拖拽（某些终端不支持）

如果数组为空，则禁用鼠标。

通常你不需要修改它，除非你所使用的插件要求启用某种特定事件。

title_format

终端标题格式，是一个字符串，可用的占位符如下：

  • {cwd} - 当前工作目录

如果你不希望 Yazi 自动更新标题，可以将其设置为空字符串（""）。

[preview]

wrap

在代码预览中是否折行显示长行。

  • "yes"：启用自动换行
  • "no"：禁用自动换行

tab_size

一个制表符字符（\t）所占的空格宽度。

max_width

图片预览的最大宽度。修改后需要运行 yazi --clear-cache 才会生效。

该值也会用于图片预加载；值越大，生成的图片缓存越大，会消耗更多 CPU。

max_height

图片预览的最大高度。修改后需要运行 yazi --clear-cache 才会生效。

该值也会用于图片预加载；值越大，生成的图片缓存越大，会消耗更多 CPU。

cache_dir

默认使用系统缓存目录，缓存文件会在系统重启后自动消失。

如果你希望缓存更持久，可以手动将缓存目录指定为一个绝对路径。

image_delay

在开始向终端发送图片预览数据之前，至少等待指定的毫秒数。

这样做是为了缓解某些 terminal emulator 在用户快速滚动文件列表时，来不及渲染 Yazi 发送的图片而造成的卡顿。

更多信息见： https://github.com/sxyazi/yazi/pull/1512

image_filter

图片缩小时使用的滤镜，可用值包括：

  • "nearest" - Nearest Neighbor
  • "triangle" - Linear Triangle
  • "catmull-rom" - Catmull-Rom
  • "lanczos3" - Lanczos with window 3

它们按从快到慢、从低质量到高质量排列。其中 Lanczos3 画质最好，但速度也最慢。

示例和基准测试见： https://docs.rs/image/0.24.8/image/imageops/enum.FilterType.html#examples

image_quality

图片预缓存质量，取值范围为 50-90。

值越大，图像质量越好，但速度越慢、CPU 消耗越高，同时会生成更大的缓存文件，占用更多存储空间。

ueberzug_scale / ueberzug_offset

  • ueberzug_scale（Float）：Ueberzug 图片缩放比例，scale > 1 表示放大，scale < 1 表示缩小。例如 0.5 表示缩小到一半。
  • ueberzug_offset（[x, y, width, height]）：Ueberzug 图片偏移量，以单元格为单位。例如 [0.5, 0.5, -0.5, -0.5] 表示图片在两个方向都偏移半个单元格，同时宽高各减少半个单元格。

这对于解决 Überzug++ 图片尺寸计算的一个 bug 很有帮助。

如果你的显示器缩放因子为 2.0，并且运行在 Hyprland 的 Wayland 环境下，你可能需要设置 ueberzug_scale: 0.5，并根据你的实际情况调整 ueberzug_offset 的值，以修正这个问题。

[opener]

配置可在 [open] 中使用的 opener，例如：

  1. [opener]
  2. play = [
  3.     { run = "mpv %s", orphan = true, for = "unix" },
  4.     { run = '"C:\Program Files\mpv.exe" %s', orphan = true, for = "windows" }
  5. ]
  6. edit = [
  7.     { run = "$EDITOR %s", block = true, for = "unix" },
  8.     { run = "%EDITOR% %s", block = true, for = "windows" },
  9. ]
  10. open = [
  11.     { run = "xdg-open %s", desc = "Open" },
  12. ]
  13. # ...

可用选项如下：

  • run：用于打开所选文件的命令，支持以下格式化参数：

    • %s：所有已选文件的路径
    • %S：所有已选文件的 URL
    • %sN：第 N 个已选文件的路径，例如 %s1、%s2 等
    • %SN：第 N 个已选文件的 URL，例如 %S1、%S2 等
    • %d：所有已选文件所在目录的路径
    • %D：所有已选文件所在目录的 URL
    • %dN：第 N 个已选文件所在目录的路径，例如 %d1、%d2 等
    • %DN：第 N 个已选文件所在目录的 URL，例如 %D1、%D2 等
    • %%：转义后的 % 字符本身
  • block：以阻塞方式打开。设置后，Yazi 会隐藏到 secondary screen，并在 main screen 显示该程序，直到程序退出。在此期间它可以接收 I/O 信号，这对交互式程序很有用。
  • orphan：即使 Yazi 已退出，也保持该进程继续运行。指定后，该进程会从任务调度系统中分离。
  • desc：opener 的描述，会显示在交互式组件中，例如 “Open with” 和帮助菜单。

  • for：该 opener 仅在指定系统上可用；如果不指定，则在所有系统上都可用。可用值：

    • linux：Linux
    • macos：macOS
    • windows：Windows
    • android：Android（Termux）
    • unix：Linux、macOS 和 Android

[open]

为特定文件设置打开规则。你可以通过 prepend_rules 和 append_rules 在默认规则之前或之后添加规则（详见 配置混合）：

  1. [open]
  2. prepend_rules = [
  3.     { url = "*.json", use = "edit" },
  5.     # 单条规则对应多个 opener
  6.     { url = "*.html", use = [ "open", "edit" ] },
  7. ]
  8. append_rules = [
  9.     { url = "*", use = "my-fallback" },
  10. ]

如果你的 append_rules 中包含通配规则，那么它们总会优先于默认的通配规则，作为 fallback 生效。

或者，你也可以使用 rules 完全重写默认规则：

  1. [open]
  2. rules = [
  3.     { mime = "text/*", use = "edit" },
  4.     { mime = "video/*", use = "play" },
  6.     # { mime = "application/json", use = "edit" },
  7.     { url = "*.json", use = "edit" },
  9.     # 单条规则对应多个 opener
  10.     { url = "*.html", use = [ "open", "edit" ] },
  11. ]

可用规则选项如下：

  • url：用于匹配文件 URL 的 Glob 表达式。默认不区分大小写，在开头加上 \s 可改为区分大小写。
  • mime：用于匹配 mime-type 的 Glob 表达式。默认不区分大小写，在开头加上 \s 可改为区分大小写。
  • use：opener 名称，对应 [opener] 部分 中定义的名字。

有了这些规则之后：

  • 你可以对一个文件执行 spot 操作，用默认的 Tab 键查看它的 mime-type。
  • 如果 use 是一个包含多个 opener 的数组，那么这些 opener 中的所有命令会被合并。open 会运行其中第一条命令；open --interactive 则会在 “open with” 菜单中列出所有这些命令。

[tasks]

micro_workers

最大并发 micro-task 数量。

macro_workers

最大并发 macro-task 数量。

bizarre_retry

发生异常失败（bizarre failure）时的最大重试次数。

suppress_preload

将系统创建的预加载任务从任务列表中排除，不报告它们的进度，也不会在应用退出确认时将它们纳入考虑。

image_alloc

解码单张图片时允许分配的最大内存字节数，0 表示不限制。

image_bound

一个 [width, height] 数组，表示解码单张图片时允许的最大尺寸（像素），0 表示不限制。

[plugin]

fetchers

TODO

你可以通过 prepend_fetchers 和 append_fetchers，在 [plugin] 下默认的 fetchers 前后添加新的 fetcher，详见 配置混合。 单条规则可用的选项如下：

  • id（String）：Fetcher 的 ID
  • url（String）：用于匹配文件 URL 的 Glob 表达式。默认不区分大小写，在开头加上 \s 可改为区分大小写。
  • run（String）：要运行的 Lua plugin 名称
  • if（String）：在满足该条件时执行 fetcher
  • prio（String）：任务优先级，可选 high、normal 或 low

previewers

你可以通过 prepend_previewers 和 append_previewers，在 [plugin] 下默认的 previewers 前后添加新的预览规则，详见 配置混合。 单条规则可用的选项如下：

  • url（String）：用于匹配文件 URL 的 Glob 表达式。默认不区分大小写，在开头加上 \s 可改为区分大小写。
  • mime（String）：用于匹配 mime-type 的 Glob 表达式。默认不区分大小写，在开头加上 \s 可改为区分大小写。
  • run（String）：要运行的 Lua plugin 名称
  1. [plugin]
  2. prepend_previewers = [
  3.     # HEIC previewer
  4.     { mime = "image/heic", run = "heic" },
  5.     # RAF previewer
  6.     { url = "*.raf", run = "raf" },
  7. ]
  9. append_previewers = [
  10.     # 我的 fallback previewer
  11.     { url = "*", run = "binary" },
  12. ]

如果你的 append_previewers 中包含通配型 url 规则（"*" 或 "*/"），那么它们总会优先于默认的通配规则，作为 fallback 生效。

Yazi 内置了这些 previewer plugins：

  • folder：连接 Yazi 文件系统与预览层
  • code：连接内置代码高亮与预览层，提供异步并发渲染
  • json：连接 jq 与预览层，提供异步并发渲染
  • noop：不执行任何操作
  • image：内置图片预览的表现层，提供混合预览能力
  • video：连接 ffmpeg 与预览层，提供混合预览能力
  • pdf：连接 pdftoppm 与预览层，提供混合预览能力
  • archive：连接 7-Zip 与预览层，提供混合预览和并发渲染能力

如果你想创建自己的 previewer，请参见 Previewer API。

preloaders

你可以通过 prepend_preloaders 和 append_preloaders，在 [plugin] 下默认的 preloaders 前后添加新的预加载规则，详见 配置混合。 单条规则可用的选项如下：

  • url（String）：用于匹配文件 URL 的 Glob 表达式。默认不区分大小写，在开头加上 \s 可改为区分大小写。
  • mime（String）：用于匹配 mime-type 的 Glob 表达式。默认不区分大小写，在开头加上 \s 可改为区分大小写。

  • cond（String）：条件表达式——只有满足该条件并且满足 url 或 mime 之一的规则才会被应用。例如 A & B 表示 A 且 B，A | !B 表示 A 或非 B。可用因子如下：

    • mime：该文件具有 mime-type
  • run（String）：要运行的 Lua plugin 名称
  • prio（String）：预加载优先级，可选 low、normal 或 high。如果未指定，默认是 normal
  1. [plugin]
  2. prepend_preloaders = [
  3.     # HEIC preloader
  4.     { mime = "image/heic", run = "heic" },
  5. ]

Yazi 内置了这些 preloader plugins：

  • mime：分块预加载文件的 mime-type
  • noop：不执行任何操作
  • image：预加载并缓存图片
  • video：预加载并缓存视频
  • pdf：预加载并缓存 PDF

如果你想创建自己的 preloader，请参见 Preloader API。

[input]

cursor_blink

控制光标是否闪烁。

  • true：闪烁
  • false：不闪烁

你可以自定义每个输入框的标题和位置。可用的输入框包括：cd、create、rename、filter、find、search 和 shell。 要修改它们的配置，使用“名称 + 下划线 + 选项名”的形式，例如 cd_origin。

位置由两部分组成：Origin 和 Offset。

Origin 是输入框左上角的原点，Offset 是相对于该原点的偏移增量。两者共同决定输入框在屏幕上的区域。

Origin

可用值见 Origin。

Offset

Offset 是一个 4 元组：(x, y, width, height)。

Placeholder

某些输入框有特殊占位符，显示时会被替换为实际内容：

  • cd_title: String

    cd --interactive 输入框的标题，用于输入目标路径。

  • create_title: [String, String]

    一个 2 元组：第一个用于 create 输入框标题，第二个用于 create --dir 操作。

  • rename_title: String

    rename 输入框的标题，用于输入新名称。

  • filter_title: String

    filter 输入框的标题，用于输入关键字。

  • find_title: [String, String]

    一个 2 元组：第一个用于 find，第二个用于 find --previous。

  • search_title: String

    • {n}：当前 search 引擎的名称。

  • shell_title: [String, String]

    一个 2 元组：第一个用于 shell --interactive，第二个用于 shell --interactive --block。

[confirm]

与 [input] 部分相同。可用项包括：trash、delete、overwrite 和 quit。

[pick]

与 [input] 部分相同。可用 selector：open。

[which]

sort_by

候选项排序方式。

  • "none"：不排序
  • "key"：按按键排序
  • "desc"：按描述排序

sort_sensitive

是否区分大小写排序。

  • true：区分大小写
  • false：不区分大小写

sort_reverse

是否倒序显示候选项。

  • true：倒序
  • false：正常顺序

sort_translit

在排序时对文件名做音译转换，即将 Â 替换为 A，将 Æ 替换为 AE 等。

这对于包含匈牙利语字符的文件很有用。

  • true：启用
  • false：禁用

如果你继续发下一段，我会保持这一版术语统一，比如固定使用“预加载 / 预览器 / opener / fallback / mime-type / plugin”等风格。