强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

Vim / Neovim 完全指南 / 15 - Telescope 模糊搜索

“Telescope is not just a fuzzy finder — it’s a framework for building pickers.”

15.1 Telescope 概览

15.1.1 架构

Telescope
├── Pickers(选择器)
│   ├── find_files      → 文件搜索
│   ├── live_grep       → 实时文本搜索
│   ├── buffers         → 缓冲区列表
│   ├── help_tags       → 帮助标签
│   ├── git_files       → Git 文件
│   ├── git_status      → Git 状态
│   ├── lsp_references  → LSP 引用
│   ├── lsp_definitions → LSP 定义
│   └── 自定义 Picker
├── Sorters(排序器)
│   ├── fzf             → FZF 算法
│   └── 内置排序器
└── Previewers(预览器)
    ├── buffer_previewer → 缓冲区预览
    └── terminal_previewer → 终端预览

15.1.2 与其他搜索工具对比

工具 模糊搜索 文件搜索 文本搜索 可扩展 预览
Telescope
fzf.vim ⚠️
CtrlP ⚠️
LeaderF ⚠️

15.2 安装与配置

15.2.1 基本安装

{ "nvim-telescope/telescope.nvim",
    cmd = "Telescope",
    dependencies = {
        "nvim-lua/plenary.nvim",
        { "nvim-telescope/telescope-fzf-native.nvim",
            build = "make",
            config = function()
                require("telescope").load_extension("fzf")
            end,
        },
    },
    keys = {
        { "<leader>ff", "<cmd>Telescope find_files<cr>", desc = "查找文件" },
        { "<leader>fg", "<cmd>Telescope live_grep<cr>", desc = "搜索文本" },
        { "<leader>fb", "<cmd>Telescope buffers<cr>", desc = "缓冲区" },
        { "<leader>fh", "<cmd>Telescope help_tags<cr>", desc = "帮助" },
        { "<leader>fo", "<cmd>Telescope oldfiles<cr>", desc = "最近文件" },
        { "<leader>fw", "<cmd>Telescope grep_string<cr>", desc = "搜索单词" },
        { "<leader>fd", "<cmd>Telescope diagnostics<cr>", desc = "诊断" },
        { "<leader>fs", "<cmd>Telescope lsp_document_symbols<cr>", desc = "文档符号" },
        { "<leader>fr", "<cmd>Telescope resume<cr>", desc = "恢复上次搜索" },
    },
    opts = {
        defaults = {
            prompt_prefix = "  ",
            selection_caret = " ",
            path_display = { "truncate" },
            layout_config = {
                horizontal = { prompt_position = "top", preview_width = 0.55 },
                vertical = { mirror = false },
                width = 0.87,
                height = 0.80,
                preview_cutoff = 120,
            },
            sorting_strategy = "ascending",
            file_ignore_patterns = { "%.git/", "node_modules/", "__pycache__/" },
        },
    },
}

15.3 内置 Picker

15.3.1 文件相关

Picker 命令 用途
find_files Telescope find_files 搜索文件名
git_files Telescope git_files Git 跟踪的文件
oldfiles Telescope oldfiles 最近打开的文件
file_browser 需要扩展 文件浏览器

15.3.2 文本搜索

Picker 命令 用途
live_grep Telescope live_grep 实时搜索文本
grep_string Telescope grep_string 搜索光标下的单词
current_buffer_fuzzy_find 当前缓冲区搜索 模糊搜索当前文件

15.3.3 Git

Picker 命令 用途
git_commits Telescope git_commits 提交历史
git_bcommits Telescope git_bcommits 当前文件提交历史
git_branches Telescope git_branches 分支列表
git_status Telescope git_status 文件变更状态

15.3.4 LSP

Picker 命令 用途
lsp_references 引用 查找引用
lsp_definitions 定义 跳转定义
lsp_implementations 实现 查找实现
lsp_document_symbols 文档符号 大纲
lsp_workspace_symbols 工作区符号 全项目搜索符号
diagnostics 诊断 查看诊断

15.4 Telescope 内操作

15.4.1 默认快捷键

按键 模式 功能
<C-n> / <Down> Insert/Normal 下一项
<C-p> / <Up> Insert/Normal 上一项
<CR> Insert/Normal 选择
<C-x> Insert/Normal 水平分割打开
<C-v> Insert/Normal 垂直分割打开
<C-t> Insert/Normal 标签页打开
<C-u> Insert 清空搜索
<C-w> Insert 删除前一个词
<Esc> Insert 回到 Normal
q Normal 关闭
<Tab> Normal 切换选中
<S-Tab> Normal 反向切换选中
<C-q> Normal 发送到 quickfix

15.4.2 多选

" 在 Telescope 中多选文件并批量操作
<Tab>       " 选择/取消选择
<S-Tab>     " 反向选择
<C-q>       " 将所有选中项发送到 quickfix
" 然后使用 :cdo 批量操作

15.5 Telescope 扩展

15.5.1 常用扩展

-- fzf-native(更快的排序)
{ "nvim-telescope/telescope-fzf-native.nvim", build = "make" }

-- file-browser(文件管理)
{ "nvim-telescope/telescope-file-browser.nvim" }

-- ui-select(替换 vim.ui.select)
{ "nvim-telescope/telescope-ui-select.nvim" }

-- 加载扩展
require("telescope").load_extension("fzf")
require("telescope").load_extension("file_browser")
require("telescope").load_extension("ui_select")

15.5.2 ui-select

-- 用 Telescope 替换 vim.ui.select 选择菜单
require("telescope").setup({
    extensions = {
        ["ui-select"] = {
            require("telescope.themes").get_dropdown({}),
        },
    },
})
require("telescope").load_extension("ui_select")

15.6 自定义 Picker

local pickers = require("telescope.pickers")
local finders = require("telescope.finders")
local conf = require("telescope.config").values
local actions = require("telescope.actions")
local action_state = require("telescope.actions.state")

-- 自定义 Picker:搜索 Neovim 配置文件
local function config_files()
    pickers.new({}, {
        prompt_title = "Config Files",
        finder = finders.new_oneshot_job(
            { "find", vim.fn.stdpath("config"), "-type", "f" },
            {}
        ),
        sorter = conf.generic_sorter({}),
        attach_mappings = function(prompt_bufnr, map)
            actions.select_default:replace(function()
                local selection = action_state.get_selected_entry()
                actions.close(prompt_bufnr)
                vim.cmd("edit " .. selection[1])
            end)
            return true
        end,
    }):find()
end

vim.keymap.set("n", "<leader>fc", config_files, { desc = "配置文件" })

15.7 主题(Theme)

-- 使用 dropdown 主题
vim.keymap.set("n", "<leader>ff", function()
    require("telescope.builtin").find_files({
        theme = "dropdown",
        previewer = false,
    })
end, { desc = "查找文件" })

-- 使用 ivy 主题
vim.keymap.set("n", "<leader>fg", function()
    require("telescope.builtin").live_grep({
        theme = "ivy",
    })
end, { desc = "搜索文本" })

15.8 ripgrep 配置

defaults = {
    vimgrep_arguments = {
        "rg",
        "--color=never",
        "--no-heading",
        "--with-filename",
        "--line-number",
        "--column",
        "--smart-case",
        "--hidden",        -- 搜索隐藏文件
        "--glob=!.git/",   -- 排除 .git
    },
},

15.9 业务场景

场景 Picker
打开文件 find_files / git_files
搜索代码 live_grep
搜索单词 grep_string
查看引用 lsp_references
跳转定义 lsp_definitions
浏览符号 lsp_document_symbols
查看诊断 diagnostics
浏览提交 git_commits
切换分支 git_branches
最近文件 oldfiles

15.10 总结

概念 要点
Picker 搜索行为的封装
Finder 数据源(job/静态/动态)
Sorter 排序算法
Previewer 预览窗口
扩展 fzf, file-browser, ui-select

下一步第 16 章 - Git 集成 → 在 Neovim 中高效使用 Git。


扩展阅读