Yazi 预览与默认打开配置

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

目标

在 Yazi 里实现以下效果：

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

已安装/确认的软件

sh 复制代码

command -v yazi
command -v ya
command -v glow
command -v typora
command -v bat
command -v pandoc

本机确认结果：

复制代码

/usr/sbin/yazi
/usr/sbin/ya
/usr/sbin/glow
/home/tingfeng/.local/bin/typora
/usr/bin/bat
/usr/bin/pandoc

安装 Yazi 插件 piper

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

toml 复制代码

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

会报错：

复制代码

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 命令接入预览器：

sh 复制代码

ya pkg add yazi-rs/plugins:piper

安装后会生成：

复制代码

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

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

安装 docx 预览插件

安装命令：

sh 复制代码

ya pkg add linxuan-sys/docx-preview

安装后会生成：

复制代码

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

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

配置 Markdown 用 glow 预览

编辑：

复制代码

~/.config/yazi/yazi.toml

添加或保留：

toml 复制代码

[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 打开

编辑：

复制代码

~/.config/yazi/yazi.toml

添加：

toml 复制代码

[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 打开

编辑：

复制代码

~/.config/yazi/yazi.toml

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

toml 复制代码

[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，检查：

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

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

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

sh 复制代码

# 查看当前 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。

编辑：

复制代码

~/.config/yazi/yazi.toml

在 [plugin].prepend_previewers 中加入：

toml 复制代码

[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 面板本身带透明效果，预览内容会直接叠在壁纸上，这时问题往往不是"预览失效"，而是"语法主题对比度不够"。

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

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

对应处理方式：

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

判断原则：

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