把 Yazi 配置拆开，再接好打开方式。

把文件管理器配顺手，通常不需要先装一排插件。先分清“列表怎样显示”“文件交给谁”“哪一个键触发动作”，配置就能逐层检查。本文按 Yazi 26.9.1 核对示例；已有配置应先确认版本，再迁移字段。

先把配置职责拆开#

Unix 系统通常把用户配置放在 ~/.config/yazi/，Windows 使用 %AppData%\yazi\config\。不存在的用户文件会采用发布版本内置值，所以只写想调整的部分即可。复制整套默认文件会把当时的默认值冻结在自己的配置里，之后升级就更难判断哪些是主动选择。[1]

测试另一套配置时，可以让一次启动使用独立目录。下面只改变该进程的配置来源，不会替换默认目录。Yazi 还支持 vfs.toml 配置虚拟文件系统；普通本地浏览先把前三份 TOML 分清就足够。

YAZI_CONFIG_HOME="$HOME/.config/yazi-test" yazi

用小配置表达浏览习惯#

[mgr] 控制列表。三栏比例依次是父目录、当前目录和预览；[1, 4, 3] 表示把可用宽度分成八份。某栏设为零可以隐藏它，但不能把所有栏都设为零。下例采用自然排序，让 2.md 排在 10.md 前面。

# yazi.toml
[mgr]
ratio = [1, 4, 3]
sort_by = "natural"
sort_dir_first = true
sort_sensitive = false
sort_reverse = false
show_hidden = true
show_symlink = true
linemode = "mtime"
scrolloff = 5

时间排序值是 mtime 和 btime，不能把解释文字“modified”“created”直接当成配置值。linemode 决定列表右侧显示什么，和排序是两件事：显示修改时间不等于按修改时间排序。旧笔记的 [manager]、tab_width 等字段也不应直接塞进当前配置。以对应发行版的 preset 为基线，比拿一份未知年份的配置补丁更可靠。[2]

打开器定义命令和进程关系#

[opener] 给命令组命名。命令组本身不负责文件类型匹配；它说明程序怎样启动、在哪个平台可用，以及 Yazi 是否让出终端。以下示例要求系统已有 Neovim、mpv 和 xdg-open，分别处理编辑、播放和桌面默认应用。

# yazi.toml
[opener]
edit = [
  { run = "nvim %s", block = true, for = "unix", desc = "Edit in Neovim" },
]
play = [
  { run = "mpv %s", orphan = true, for = "unix", desc = "Play in mpv" },
]
desktop = [
  { run = "xdg-open %s1", for = "linux", desc = "Desktop application" },
]

block = true 让交互程序取得终端控制权，直到它退出，再回到 Yazi；终端编辑器应采用这个方式。orphan = true 则让进程脱离 Yazi 的任务调度，Yazi 退出后仍可继续运行。只写 block = false 不等于脱离调度，不能把它理解成完整的“启动后不再管”。[3]

当前接口用 %s 传入全部选中文件路径，%s1 是第一个，%d1 是第一个文件的父目录。Yazi 会按 Shell 语境转义替换的路径；不要把整段 %s 再用双引号包成一个参数。xdg-open 一次接收一个文件，所以示例用 %s1。旧版教程中的 $@ 不是这套格式参数，按当前版本照抄会改变命令含义。

规则决定哪些文件交给谁#

现在才给文件分流。在同一份 yazi.toml 里加上下段：代码文件先用编辑器，HTML 提供桌面应用与编辑器两个选择，媒体走播放器。这里使用 prepend_rules，把规则放到默认规则之前，保留未涉及的压缩包、空文件和其他默认行为。

[open]
prepend_rules = [
  { url = "*.{md,txt,nix,rs,py,js,ts,json,toml,yaml,lua}", use = "edit" },
  { url = "*.html", use = ["desktop", "edit"] },
  { mime = "{audio,video}/*", use = "play" },
  { mime = "image/*", use = "desktop" },
]

url 是 URL 的 glob 匹配字段，mime 按识别到的 MIME 类型匹配，use 引用上面的打开器名称。旧规则里的 name 需要迁移到 url。普通打开执行命中规则提供的第一条可用命令；交互打开会列出规则提供的全部可用命令。HTML 例子因此默认交给桌面应用，也能临时选择编辑器。[4]

不要为了加一条规则就改成 rules = [...]：这会重写整套默认规则。append_rules 用于后置扩展，但其中的通配 fallback 会优先于默认 fallback，不能简单理解为“写在最后就绝对最低优先级”。排错时先检查是否被更早的具体规则命中，再看兜底。

按键是动作入口，不是打开规则#

默认 l 只进入目录，o 或 Enter 才打开文件，O 进入“打开方式”菜单。若想加书签或明确的交互打开键，把绑定写到 keymap.toml，不要放进 yazi.toml。

# keymap.toml
[mgr]
prepend_keymap = [
  { on = ["g", "p"], run = "cd ~/Projects", desc = "Go to projects" },
  { on = ["g", "<Space>"], run = "cd --interactive", desc = "Enter a directory path" },
  { on = "<C-o>", run = "open --interactive", desc = "Choose an opener" },
]

on = ["g", "p"] 是依次按 g、p，不是一个组合键；Ctrl 组合键才写成 <C-o>。Yazi 在当前界面层级寻找第一条匹配绑定，前置表可覆盖默认键，后置表则不能抢走已命中的键。直接设置 keymap 会替换该层整张默认表。主列表属于 [mgr]，输入框、确认弹窗、选择菜单分别属于 [input]、[confirm]、[pick]，因此同一个 j 在不同面板可以做不同的事。[5]

预览与打开是两条路径#

预览成功不表示外部程序能打开，打开成功也不保证终端能显示图片。预览使用 [preview] 的尺寸、换行等参数，再由对应预览器和依赖处理内容；opener 是明确要求启动另一程序时才走的路径。

# yazi.toml
[preview]
wrap = "yes"
tab_size = 4
max_width = 800
max_height = 1000
image_filter = "triangle"
image_quality = 75

改图片最大尺寸后，旧缓存可能还在，当前清理命令是 ya cache clear。图片质量范围是 50–90，滤镜名包括 nearest、triangle、catmull-rom、lanczos3。不要照抄旧笔记里的 sixel_fraction、catmull-roman，或把外部程序名直接当内置 preloader 名。普通使用先保留默认 previewer/preloader 表；换用插件时只增加明确需要的规则。

按版本和调用链排错#

排查“不生效”时，按调用链找问题：版本与配置目录 → TOML 字段 → 当前按键动作 → 命中规则 → 可用打开器 → 外部程序。路径错误、规则错误和程序缺失应分别处理，反复清缓存不会修复写错的字段。

yazi --version
ya --version
ya env
command -v nvim
command -v mpv
command -v xdg-open

ya 与 yazi 应使用相同版本。26.9.1 用 ya env 查看环境和配置信息；本版本启动参数没有 --debug 和 --clear-cache，也没有通过 ya pub dump 获取默认配置的通用承诺。查看默认配置应访问对应版本 preset。文件类型疑问可以按 Tab 打开详情，按键冲突则用 ~ 或 F1 查当前帮助。以上是文档与源码核对结果，不代表某台机器已经完成运行验证。[6]