Yazi 备忘清单

Yazi 是一个使用 Rust 编写的终端文件管理器，支持异步文件操作、预览、Vim 风格快捷键、插件和主题扩展。

$ yazi
$ yazi ~/Projects
$ yazi --help

默认使用三栏视图：父目录、当前目录和预览面板。推荐把它与 shell wrapper 搭配使用，这样退出后可以回到 Yazi 中最后所在目录。

Unix-like 系统配置目录为 ~/.config/yazi/，Windows 配置目录为 %AppData%\yazi\config\。也可以通过 YAZI_CONFIG_HOME 使用自定义配置目录。

# yazi.toml
[mgr]
show_hidden = true

Yazi 已内置默认配置，只需要在自己的配置文件里写入要覆盖的片段。

# yazi.toml
[mgr]
ratio = [1, 4, 3]

ratio 控制父目录、当前目录、预览面板的宽度比例。某一栏设为 0 可隐藏该栏，但至少需要保留一个非零面板。

# keymap.toml
[[mgr.prepend_keymap]]
on = "<C-a>"
run = "toggle_all --state=on"
desc = "Select all files"

[[mgr.append_keymap]]
on = [ "g", "b" ]
run = "cd ~/Books"
desc = "Go to books"

prepend_keymap 优先级高于默认快捷键，append_keymap 优先级低于默认快捷键。若要完全替换默认快捷键，可使用 keymap。

$ ya --help

ya 是 Yazi 的辅助命令，负责插件管理、主题管理和 DDS 消息发布订阅等功能。ya 与 yazi 版本必须一致。

$ ya pkg add owner/my-plugin
$ ya pkg add yazi-rs/plugins:git
$ ya pkg list
$ ya pkg install
$ ya pkg upgrade
$ ya pkg delete yazi-rs/plugins:git

ya pkg 会把插件复制到配置目录，并更新 package.toml 来锁定版本。

# package.toml
[[plugin.deps]]
use = "owner/my-plugin"
rev = "=9a1129c"
hash = "d81b64a39432fcd6224cd75d296e7510"

在 rev 前加 = 可固定插件版本，避免 ya pkg upgrade 自动升级。

# theme.toml
[flavor]
dark = "catppuccin-mocha"
light = "catppuccin-mocha"

Flavor 是可复用的预制主题，通常放在 flavors/ 子目录中，并可由 ya pkg 管理。用户自己的 theme.toml 会覆盖 flavor 的同名配置。

$ yazi --help
$ ya --help

先确认 yazi 和 ya 都在 PATH 中，并且两者版本一致。

$ YAZI_CONFIG_HOME=~/.config/yazi-alt yazi

用独立配置目录启动可以排查现有配置、插件或主题是否导致问题。