Yazi 预览与默认打开配置记录

Yazi 预览与默认打开配置记录

记录时间：2026-06-21 | 更新：2026-06-22（新增 PDF + ONLYOFFICE）

目标

在 Yazi 里实现以下效果：

  1. 选中 Markdown 文件时，右侧预览使用更接近渲染效果的 glow。
  2. Markdown 默认用 Typora 打开，并强制走 GTK 暗色主题。
  3. .docx 文件支持右侧即时预览。
  4. .sql 文件右侧预览使用高对比语法高亮，避免浅灰字段可见性差。

已安装/确认的软件

1
2
3
4
5
6
command -v yazi
command -v ya
command -v glow
command -v typora
command -v bat
command -v pandoc

本机确认结果：

1
2
3
4
5
6
/usr/sbin/yazi
/usr/sbin/ya
/usr/sbin/glow
/home/tingfeng/.local/bin/typora
/usr/bin/bat
/usr/bin/pandoc

安装 Yazi 插件 piper

一开始在 yazi.toml 里直接写：

1
{ url = "*.md", run = "glow -p -" }

会报错：

1
2
Unexpected error during peek: Failed to load plugin from
"/home/tingfeng/.config/yazi/plugins/glow.yazi/main.lua"

原因：Yazi 的 previewers.run 不是直接执行 shell 命令，而是按插件名加载。run = "glow -p -" 会被当成要加载 glow.yazi 插件，但本机并没有这个插件。

正确做法是安装 piper.yazi，通过它把 shell 命令接入预览器：

1
ya pkg add yazi-rs/plugins:piper

安装后会生成：

1
~/.config/yazi/plugins/piper.yazi/main.lua

并且 ~/.config/yazi/package.toml 会记录依赖。

安装 docx 预览插件

安装命令：

1
ya pkg add linxuan-sys/docx-preview

安装后会生成：

1
~/.config/yazi/plugins/docx-preview.yazi/main.lua

这个插件底层调用 pandoc 把 .docx 转成纯文本后显示在右侧预览栏，因此本机必须安装 pandoc。

配置 Markdown 用 glow 预览

编辑：

1
~/.config/yazi/yazi.toml

添加或保留：

1
2
3
4
[plugin]
prepend_previewers = [
  { url = "*.md", run = 'piper -- CLICOLOR_FORCE=1 glow -w=$w -s=dracula "$1"' },
]

说明：

  • piper -- ...：使用 piper.yazi 执行后面的 shell 命令。
  • CLICOLOR_FORCE=1：强制输出彩色内容。
  • glow -w=$w：按 Yazi 预览窗口宽度渲染。
  • -s=dracula：使用对比更高的 dracula 样式。
  • "$1"：当前被预览文件的路径。

为什么不用 bat 预览 Markdown

虽然 bat 的高亮对比度更高，但它更偏向“源码视图”，而不是 Markdown 渲染视图。

如果目标是：

  • 标题层级更直观
  • 列表、引用、强调更接近最终排版
  • 阅读体验更像渲染后的 Markdown

那 glow 更合适。

本次调整里，曾短暂把 .md 预览切到 bat，用于解决标题颜色太浅的问题；最终改回了 glow，并把样式从 dark 调整为 dracula，兼顾排版效果和可见性。

配置 Markdown 默认用 Typora 打开

编辑：

1
~/.config/yazi/yazi.toml

添加：

1
2
3
4
5
6
7
8
9
[opener]
typora = [
  { run = 'env GTK_THEME=Adwaita:dark typora %s', orphan = true, desc = "Open with Typora" },
]

[open]
prepend_rules = [
  { url = "*.md", use = "typora" },
]

说明：

  • [opener] 定义一个名为 typora 的打开方式。
  • env GTK_THEME=Adwaita:dark typora %s 会在打开 Typora 时强制使用 GTK 暗色主题。
  • %s 是 Yazi 的文件路径占位符，不能用 shell 的 "$@"（那是之前的错误写法，会导致文件路径无法正确传入）。
  • orphan = true 让 Typora 独立运行，不阻塞 Yazi。
  • [open].prepend_rules 把 Markdown 文件优先匹配到 typora opener。
  • 选中 .md 文件后，按 Enter 会使用这个默认打开规则。

配置 PDF 默认用 ONLYOFFICE 打开

编辑：

1
~/.config/yazi/yazi.toml

在 [opener] 中添加 ONLYOFFICE 打开方式，并在 [open].prepend_rules 中关联：

1
2
3
4
5
6
7
8
9
[opener]
ONLYOFFICE = [
  { run = 'onlyoffice-desktopeditors %s1', orphan = true, desc = "Open with ONLYOFFICE" },
]

[open]
prepend_rules = [
  { url = "*.pdf", use = "ONLYOFFICE" },
]

说明：

  • ONLYOFFICE 本机安装路径：/usr/sbin/onlyoffice-desktopeditors（实际执行 /opt/onlyoffice/desktopeditors/DesktopEditors）。
  • %s 是 Yazi 的文件路径占位符，不是 shell 的 "$@"。用 "$@" 会导致文件路径无法传入，opener 看起来有但实际打不开文件。
  • orphan = true 让 ONLYOFFICE 独立运行，不阻塞 Yazi。

常见踩坑：opener 定义后仍不生效

如果配置了 [opener] 和 use，但按 Enter 仍用浏览器打开 PDF，检查：

  1. run 中是否误用了 "$@" 而非 %s：Yazi opener 的 run 命令使用 %s / %sN 作为文件路径占位符，"$@" 是 shell 语法，在 Yazi 中不会正确展开。
  2. opener 名称大小写是否一致：use = "ONLYOFFICE" 必须与 [opener] 下的 key ONLYOFFICE 完全一致（TOML key 大小写敏感）。
  3. 确认 opener 定义在 [opener] 段而不是其他地方：use 引用的名字必须对应 [opener] 下的一个 key。

系统级默认应用配置（可选）

如果希望不仅在 Yazi 内，而是在整个桌面环境中都用 ONLYOFFICE 打开 PDF，需要改 xdg-mime：

1
2
3
4
5
# 查看当前 PDF 默认应用
xdg-mime query default application/pdf

# 如果返回的是浏览器（如 com.google.Chrome.desktop），则改为 ONLYOFFICE
xdg-mime default onlyoffice-desktopeditors.desktop application/pdf

ONLYOFFICE 的 desktop 文件位于 /usr/share/applications/onlyoffice-desktopeditors.desktop，其 MimeType 已包含 application/pdf。

编辑：

1
~/.config/yazi/yazi.toml

在 [plugin].prepend_previewers 中加入：

1
2
3
4
5
6
[plugin]
prepend_previewers = [
  { url = "*.docx", run = "docx-preview" },
  { url = "*.sql", run = 'piper -- CLICOLOR_FORCE=1 bat -p --color=always --theme="Monokai Extended Bright" --wrap=never "$1"' },
  { url = "*.md", run = 'piper -- CLICOLOR_FORCE=1 glow -w=$w -s=dracula "$1"' },
]

说明：

  • *.docx：调用 docx-preview 插件，底层依赖 pandoc。
  • *.sql：调用 bat 强制使用高对比主题，解决透明背景下浅灰字段不清楚的问题。
  • Monokai Extended Bright：在当前透明背景和壁纸场景下，对比度比默认主题稳定得多。

透明背景场景下的经验

如果终端或 Yazi 面板本身带透明效果，预览内容会直接叠在壁纸上，这时问题往往不是“预览失效”，而是“语法主题对比度不够”。

本次实际遇到的两个问题：

  1. SQL 预览里部分字段呈浅灰色，可见性差。
  2. Markdown 标题在 glow -s=dark 下颜色偏浅，叠到壁纸上不够清楚。

对应处理方式：

  1. SQL 预览改走 bat，强制指定高对比主题。
  2. Markdown 保留 glow，但把样式从 dark 改成 dracula。

判断原则：

  • 要“更像渲染后的文档排版”，优先 glow
  • 要“更高对比、更像代码高亮”，优先 bat

注意：open 规则必须用 url 或 mime

曾经错误写成：

1
2
3
4
[open]
prepend_rules = [
  { name = "*.md", use = "typora" },
]

会报错：

1
2
TOML parse error at line 8, column 3
at least one of `url` or `mime` must be specified

原因：当前 Yazi 版本的 [open].prepend_rules 不接受 name 字段，必须使用 url 或 mime。

正确写法：

1
2
3
4
[open]
prepend_rules = [
  { url = "*.md", use = "typora" },
]

最终完整 yazi.toml 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
[opener]
typora = [
  { run = 'env GTK_THEME=Adwaita:dark typora %s', orphan = true, desc = "Open with Typora" },
]
ONLYOFFICE = [
  { run = 'onlyoffice-desktopeditors %s1', orphan = true, desc = "Open with ONLYOFFICE" },
]

[open]
prepend_rules = [
  { url = "*.md", use = "typora" },
  { url = "*.pdf", use = "ONLYOFFICE" },
]

[plugin]
prepend_previewers = [
  { url = "*.docx", run = "docx-preview" },
  { url = "*.sql", run = 'piper -- CLICOLOR_FORCE=1 bat -p --color=always --theme="Monokai Extended Bright" --wrap=never "$1"' },
  { url = "*.md", run = 'piper -- CLICOLOR_FORCE=1 glow -w=$w -s=dracula "$1"' },
]

修改配置后，如果 Yazi 已经打开，需要退出并重新进入 Yazi 才能生效。

Shell wrapper：退出 yazi 时自动切换到对应目录

Yazi 内置 --cwd-file 参数，退出时将当前路径写入指定文件，配合 shell 函数可实现：按 q 退出并切换目录，按 Q 退出不切换。

yazi.toml 无需任何额外配置，只需在各 shell 配置文件中添加 wrapper 函数：

bash（~/.bashrc）

1
2
3
4
5
6
7
8
y() {
  local tmp="$(mktemp -t "yazi-cwd.XXXXXX")"
  yazi "$@" --cwd-file="$tmp"
  if cwd="$(cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
    builtin cd -- "$cwd"
  fi
  rm -f -- "$tmp"
}

zsh（~/.zshrc）

1
2
3
4
5
6
7
8
9
y() {
    local tmp=$(mktemp -t "yazi-cwd.XXXXXX")
    yazi "$@" --cwd-file="$tmp"
    local cwd=$(cat "$tmp")
    if [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        builtin cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}

fish（~/.config/fish/config.fish）

1
2
3
4
5
6
7
8
function y
    set tmp (mktemp -t "yazi-cwd.XXXXXX")
    yazi $argv --cwd-file="$tmp"
    if read -z cwd < "$tmp"; and [ -n "$cwd" ]; and [ "$cwd" != "$PWD" ]
        builtin cd -- "$cwd"
    end
    rm -f -- "$tmp"
end

注意

  • yazi 内置的 q 退出会写入 --cwd-file，Q 退出则不写入，因此 wrapper 中按 q 会切换目录，按 Q 留在原地。
  • --cwd-file 是 yazi 内置功能，不需要在 yazi.toml 中做任何配置。
  • %s / %s1 是 Yazi opener 的占位符（见上文 opener 配置），与 shell 变量 $@ / $argv 是两回事，不可混用。

快捷键：在当前目录打开 Thunar

在 yazi 中按 Ctrl+E 打开 Thunar 文件管理器（当前所在目录），通过 keymap.toml 实现：

1
~/.config/yazi/keymap.toml
1
2
3
4
[[mgr.prepend_keymap]]
on = ["<C-e>"]
run = "shell 'thunar -q; thunar .' --orphan"
desc = "Open Thunar here"
  • [[mgr.prepend_keymap]]：yazi section header 必须用缩写 mgr，不是 manager
  • on = ["<C-e>"]：绑定到 Ctrl+E，含角括号
  • shell 'thunar -q; thunar .'：先关闭旧实例再打开，避免 Thunar 恢复上次的标签页导致多标签
  • --orphan：Thunar 独立运行，不阻塞 yazi

终端中快速打开 Thunar（dk 别名）

不想用快捷键的话，可以在终端直接输入 dk 回车，在当前目录打开 Thunar：

Shell 配置文件 写法
bash ~/.bashrc alias dk='thunar -q; thunar . &>/dev/null & disown'
zsh ~/.zshrc alias dk='thunar -q; thunar . &>/dev/null &!'
fish ~/.config/fish/config.fish function dk + nohup thunar .（见下方）

fish 用 abbr 会有后台作业完成提示，改用函数 + nohup + disown 可彻底消除：

1
2
3
4
5
function dk
    thunar -q 2>/dev/null
    nohup thunar . >/dev/null 2>&1 &
    disown
end

为什么需要 thunar -q + 关闭标签恢复

Thunar 默认会恢复上次关闭时的标签页，导致 thunar . 打开时出现多个标签页。两步解决：

1
2
3
4
5
# 1. 禁用标签页恢复（一劳永逸）
xfconf-query -c thunar -p /last-restore-tabs -s false

# 2. 每次打开前先关闭旧实例（防止已运行的 Thunar 积累窗口）
thunar -q; thunar .

两步配合确保每次只打开当前目录这一个标签页。

Linux > 效率工具
#Yazi #Typora #文件管理
Yazi 预览与默认打开配置记录
https://tingfeng347.github.io/2026/04/10/Yazi 预览与默认打开配置记录/
作者
Tingfeng
发布于
2026年4月10日
许可协议