Telescope.nvim 如何用 quickfixhistory 选择器浏览并重新打开历史 quickfix 列表

在 Neovim 里连续使用 live_grep、grep_string 或把结果发送到 quickfix 列表时，quickfix 列表会被不断覆盖——前一次搜索的匹配结果很快就被下一次替换掉。telescope.nvim 提供了 builtin.quickfixhistory 选择器，把 neovim 保留在历史里的 quickfix 列表全部列出来，你可以在其中挑选某一条历史列表，再用 builtin.quickfix 重新打开它，或直接打开对应的 quickfix 窗口，逐个回到旧结果的位置。

这篇文章面向已经装好 telescope.nvim 的 Neovim 用户，带你完成一条完整路径：确认插件可用 → 产生若干条 quickfix 历史 → 用 quickfixhistory 浏览这些历史 → 用两种方式重新打开历史列表并跳回具体位置。

前置条件：确认 telescope 已正确安装

telescope.nvim 的运行前提是 README 中列出的要求：

• Neovim >=v0.11.7，且构建时带 LuaJIT（用 :version 检查）；
• 依赖 plenary.nvim。

安装完成后，按 README 的指引执行 :checkhealth telescope，确认各项检查通过。如果想快速验证插件可运行，可以先试一下 :Telescope find_files，能弹出文件选择器即说明安装成功。

quickfixhistory 本身是 builtin 选择器，不需要任何扩展或额外配置即可使用。

先产生几条 quickfix 历史

quickfixhistory 浏览的是 neovim 的 quickfix 历史，所以前提是这个历史里有内容。README 的 Default Mappings 表格给出了两种把结果送进 quickfix 列表（qflist）的默认映射，适用于大多数 picker：

映射	作用
<C-q>（insert 模式）	Send all items not filtered to quickfixlist (qflist)
<M-q>（insert 模式）	Send all selected items to qflist

也就是说，在 live_grep、grep_string 等 picker 中按 <C-q>，当前全部结果就会替换写入 quickfix 列表；重复执行几次不同搜索，quickfix 历史就会累积出多条记录。

doc/telescope.txt 中另外记录了可映射的 actions，适合需要把"发送结果 + 打开列表"做成一步映射的场景：

• actions.send_to_qflist：Send all entries to the quickfix list, replacing the previous entries
• actions.add_to_qflist：Adds all entries to the quickfix list, keeping the previous entries
• actions.open_qflist：Open the quickfix list，文档建议与 send 类 action 组合使用，例如 actions.smart_send_to_qflist + actions.open_qflist

这一步只是为了让历史里有多条列表；如果你此前正常用过 quickfix，可以直接跳到下一节。

打开 quickfixhistory 浏览历史列表

所有 telescope builtin 函数都被包装成了 :Telescope 命令（见 README 的 Vim Commands 一节），支持 Tab 补全，因此直接执行：

:Telescope quickfixhistory

也可以在 Lua 中调用：

require('telescope.builtin').quickfixhistory()

picker 打开后，prompt 标题显示为 Quickfix History。结果列表中每一行是一条历史 quickfix 列表，条目显示为该列表的 title，没有 title 时显示为 Untitled；预览窗口标题为 Quickfix List Preview，会把该列表内所有条目的内容渲染出来（doc/telescope.txt 对 builtin.quickfixhistory 的描述是 "Lists all quickfix lists in your history and open them with builtin.quickfix"）。实现见 builtin/__internal.lua。

quickfixhistory 本身只接受通用的 {opts} 参数（doc/telescope.txt 中 Parameters 一节仅列出 {opts} (table?)），没有 quickfix 专属的配置项。

重新打开某条历史列表

在 Quickfix History 选择器中用 j/k 或 <C-n>/<C-p> 移动到目标列表后，有两种重新打开的方式：

方式一：<cr> 用 builtin.quickfix 重新打开（默认选择动作）

按 <CR> 后，telescope 关闭当前 picker，以选中列表的编号（nr）调用 builtin.quickfix，在 Quickfix 标题的新 picker 里列出该历史列表的全部条目；再按 <CR> 即跳转到对应位置（builtin.quickfix 的文档描述："Lists items in the quickfix list, jumps to location on <cr>"）。

builtin.quickfix 支持以下可选参数（来自 doc/telescope.txt）：

require('telescope.builtin').quickfix {
  show_line = true,  -- (boolean, 默认 true) show results text
  trim_text = false, -- (boolean, 默认 false) trim results text
  nr = 2,            -- (number) specify the quickfix list number
}

其中 nr 指定要查看哪一条 quickfix 列表，适合你已知目标列表编号时直接打开，而不必再走一遍历史选择器。

方式二：<C-q> 直接打开 quickfix 窗口

在 Quickfix History picker 中按 <C-q>，telescope 会关闭 picker，切换到选中编号的历史列表并执行 botright copen，即在底部直接打开该历史列表的 quickfix 窗口，之后用 Neovim 原生的 quickfix 导航键在条目间跳转。这一分支对应 README 对 builtin.quickfixhistory 的描述："open them with builtin.quickfix or quickfix window"；内部实现见 builtin/__internal.lua。

两种方式的选择依据：想继续模糊过滤、用 telescope 的预览窗看条目时用 <CR>；只想快速在窗口里滚动旧结果时用 <C-q>。

验证方式与已知限制

判断这条路径是否工作正常，可以按文档中实际给出的现象核对：

1. 执行 :Telescope quickfixhistory，弹出 prompt 标题为 Quickfix History 的 picker，说明选择器本身可用；
2. 在结果列表中选择某一条，预览窗显示 Quickfix List Preview 并列出该条目的内容；
3. 若目标 quickfix 列表实际为空，builtin.quickfix 不会打开 picker，而是以 INFO 级别显示 No quickfix items 提示（见 builtin/__internal.lua），这是正常行为而非报错。

需要留意的限制：

• 历史深度上限：neovim 对 quickfix 历史只保留有限条目。doc/telescope.txt 写明 "It seems that neovim only keeps the full history for 10 lists"，源码中的注释也写明 "(n)vim keeps at most 10 quickfix lists in full"（builtin/__internal.lua）。也就是说，超过这个范围后最旧的历史列表拿不到完整内容，不要指望能翻到任意久以前的列表。
• 条目显示依赖 title：历史列表没有 title 时在列表中显示为 Untitled，此时只能靠预览窗里的条目内容来辨认它对应哪次搜索。
• builtin.quickfixhistory 只接受通用 opts，无法对"历史列表"这一层做 quickfix 专属的显示配置；show_line、trim_text 这些参数作用于打开列表后的 builtin.quickfix 一层。

完整参数与行为细节可继续查阅 doc/telescope.txt 中 *telescope.builtin.quickfixhistory()* 和 *telescope.builtin.quickfix()* 两个标签小节。