{"id":50731393,"url":"https://github.com/beixiyo/vv-explorer.nvim","last_synced_at":"2026-06-10T09:01:17.033Z","repository":{"id":353739414,"uuid":"1220666677","full_name":"beixiyo/vv-explorer.nvim","owner":"beixiyo","description":"VSCode-style file explorer for Neovim, no nui / plenary deps. VSCode 风格文件树（无 nui / plenary 依赖）","archived":false,"fork":false,"pushed_at":"2026-05-29T02:05:02.000Z","size":364,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T12:41:55.375Z","etag":null,"topics":["explorer","file-explorer","file-tree","lua","neovim","neovim-plugin","nvim","nvim-plugin"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beixiyo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-25T07:04:49.000Z","updated_at":"2026-05-29T02:05:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beixiyo/vv-explorer.nvim","commit_stats":null,"previous_names":["beixiyo/vv-explorer.nvim"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/beixiyo/vv-explorer.nvim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-explorer.nvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-explorer.nvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-explorer.nvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-explorer.nvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beixiyo","download_url":"https://codeload.github.com/beixiyo/vv-explorer.nvim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beixiyo%2Fvv-explorer.nvim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34144680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["explorer","file-explorer","file-tree","lua","neovim","neovim-plugin","nvim","nvim-plugin"],"created_at":"2026-06-10T09:01:15.833Z","updated_at":"2026-06-10T09:01:17.012Z","avatar_url":"https://github.com/beixiyo.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003evv-explorer.nvim\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eVSCode 风的 Neovim 文件树 — 实时预览、fd 异步过滤、回收站、零第三方依赖\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Neovim-0.10+-57A143?style=flat-square\u0026logo=neovim\u0026logoColor=white\" alt=\"Requires Neovim 0.10+\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Lua-2C2D72?style=flat-square\u0026logo=lua\u0026logoColor=white\" alt=\"Lua\" /\u003e\n\u003c/p\u003e\n\n---\n\n## 为什么要这个插件\n\n| | neo-tree / nvim-tree | vv-explorer |\n|---|---|---|\n| **实时预览** | 需要额外配置或不支持 | `j`/`k` 移动即时切换文件预览，`\u003cCR\u003e` 固定 |\n| **过滤体验** | 无 / 基础 | fd 异步索引 + 三模式（fuzzy / glob / regex）+ 逐字高亮 + 祖先链保持 |\n| **空目录折叠** | neo-tree 支持 | 支持，`a/b/c/` 单链合并显示 |\n| **回收站** | 依赖额外插件 | 内置，支持恢复、大小警告、面板 UI |\n| **依赖** | plenary / nui | 零第三方依赖，仅需 `vv-utils.nvim`（共享库） |\n| **多 source** | buffers / git_status / ... | 只做文件树，全 repo picker 交给 Telescope / fzf |\n\n## 安装\n\n```lua\n{\n  'beixiyo/vv-explorer.nvim',\n  dependencies = {\n    'beixiyo/vv-utils.nvim',\n    'beixiyo/vv-icons.nvim',\n    -- 可选：彩色文件图标\n    { 'echasnovski/mini.icons', opts = {} },\n  },\n  keys = { '\u003cleader\u003ee', '\u003cleader\u003eE' },\n  ---@type VVExplorerConfig\n  opts = {},\n}\n```\n\n## 配置\n\n所有选项及默认值：\n\n```lua\n---@type VVExplorerConfig\nopts = {\n  position = 'left',           -- 'left' | 'right'\n  width = 32,                  -- 窗口宽度\n  hidden = false,              -- 显示 dotfile（'.' 键切换）\n  group_empty_dirs = true,     -- 单链目录合并\n  preview = true,              -- VSCode 风单击预览\n  watch = true,                -- libuv fs_event 自动刷新\n  select_move_down = true,     -- Tab 多选后自动将光标下移一行\n  cwd = nil,                   -- 根目录（nil = vim.fn.getcwd()）\n  icon_rules = {},             -- 自定义图标规则\n\n  filter = {\n    custom = {},               -- 永久隐藏 glob，如 { 'node_modules', '.DS_Store' }\n    max_results = 1000,        -- 最大搜索结果数，避免渲染卡死\n    debounce_threshold = 5000, -- 文件数达到此阈值时开始动态防抖（以下 0ms）\n    debounce_max_ms = 500,     -- 防抖延迟的最高封顶值（毫秒）\n  },\n\n  git = {\n    enabled = true,            -- 异步 git status 索引（非 git 仓库自动 no-op）\n    show_ignored = false,      -- 显示 .gitignore 命中的路径（'I' 键切换）\n  },\n\n  diagnostics = {\n    enabled = true,            -- LSP 诊断行尾符号（E/W/I/H）\n  },\n\n  binary = {\n    intercept = true,          -- 拦截二进制文件：不在 nvim 打开，改用系统默认程序\n    extensions = {             -- 视为二进制的扩展名集合（小写 key）\n      -- 默认含：图片（png/jpg/gif/webp/…）、视频（mp4/mkv/mov/…）、\n      -- 音频（mp3/wav/flac/…）、压缩包（zip/tar/gz/7z/…）、\n      -- 编译产物（exe/dll/so/o/…）、字体（ttf/otf/woff/…）、\n      -- 二进制文档（pdf/docx/xlsx/pptx/…）、数据库（sqlite/db）\n    },\n  },\n\n  trash = {\n    enabled = true,            -- 删除时移入回收站而非真删\n    max_items = 5000,          -- 回收站最大条目数，超出自动清理最旧的\n    warn_size_mb = 500,        -- 打开 explorer 时若超过此大小则弹警告\n    scan_on_open = true,       -- 启动时异步扫描回收站大小\n  },\n\n  global_mappings = {          -- 设 false 禁用全部全局键位\n    toggle = '\u003cleader\u003eE',      -- 打开/关闭文件树（简单 Toggle）\n    reveal = '\u003cleader\u003ee',      -- 定位当前文件（若已打开且聚焦则 Toggle）\n  },\n\n  mappings = { ... },          -- 树内 buffer 键位（见下方键位表）\n}\n```\n\n### 过滤（`/` 键触发）\n\n需要 [`fd`](https://github.com/sharkdp/fd) 外部命令。三种搜索模式通过 `\u003cS-Tab\u003e` 切换：\n\n| 模式 | 引擎 | 说明 |\n|------|------|------|\n| **fuzzy** | `vim.fn.matchfuzzypos` | 逐字位置高亮（默认） |\n| **glob** | `vim.glob.to_lpeg` | 不含 `/` 时自动跨段（`*.lua` ≡ `**/*.lua`） |\n| **regex** | `string.find` | Lua pattern |\n\n### 回收站\n\n删除的文件移入 `~/.local/share/vv-explorer/trash/`，附带元数据（原始路径、时间、大小）用于恢复。按 `T` 或 `:VVExplorerTrash` 打开回收站面板\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| `trash.enabled` | `true` | `false` = 真删（不走回收站） |\n| `trash.max_items` | `5000` | 超出时自动清理最旧条目 |\n| `trash.warn_size_mb` | `500` | 打开 explorer 时异步扫描，超过则弹通知 |\n| `trash.scan_on_open` | `true` | 是否启用启动时扫描 |\n\n设 `trash = false` 可完全禁用回收站\n\n### 二进制文件拦截\n\n默认开启。`\u003cCR\u003e`/`l`/`\u003cC-x\u003e`/`\u003cC-v\u003e` 遇到二进制文件时，不在 nvim 内 `:edit`，改用系统默认程序打开；预览（`preview = true`）也会跳过二进制文件\n\n```lua\n-- 放行图片（未来 nvim 原生支持图片预览时）\nopts = {\n  binary = {\n    extensions = {\n      png = false, jpg = false, jpeg = false,\n      gif = false, webp = false, avif = false,\n    },\n  },\n}\n\n-- 完全关闭拦截\nopts = { binary = { intercept = false } }\n\n-- 增加自定义扩展名\nopts = { binary = { extensions = { sketch = true } } }\n```\n\n`extensions` 走 `vim.tbl_deep_extend`，只需写要覆盖的 key，不必重写整张表\n\n### 执行文件（`X` 键）\n\n按文件类型决定如何执行：**shebang \u003e 扩展名优先级**（命令解析走 `vv-utils.exec.resolve`，取首个 `executable()` 的运行器）。默认 `confirm = true` 会先弹确认框显示将运行的命令\n\n```lua\nopts = {\n  execute = {\n    enabled = true,\n    confirm = true,           -- 执行前确认（显示命令）；设 false 跳过\n    -- 自定义运行器：默认开原生分屏终端；可改成浮动终端等\n    run = function(cmd, ctx)  -- ctx = { path, cwd, runner }\n      require('tools.term').run(cmd, ctx.cwd)\n    end,\n    -- 透传给 vv-utils.exec.resolve：增减扩展名 / 改优先级\n    opts = {\n      runners = {\n        ts = { { 'bun', 'run' }, { 'tsx' } },  -- ts 优先 bun，其次 tsx\n        rb = { { 'ruby' } },\n      },\n    },\n  },\n}\n```\n\n默认覆盖 `sh/bash/zsh/fish · ts/tsx/mts/cts · js/mjs/cjs · py · lua · rb · pl · php`，以及任何带可用 shebang 的文件\n\n### 自定义图标规则\n\n```lua\nicon_rules = {\n  { glob = '**/*.{test,spec}.{ts,tsx}', icon = '', hl = 'DiagnosticOk' },\n  { glob = '.env*',                     icon = '', hl = 'WarningMsg' },\n  { pattern = '^README',                icon = '', hl = 'Title', scope = 'file' },\n}\n```\n\n`scope`：`'file'` / `'directory'` / `'any'`（默认）。优先级：icon_rules \u003e mini.icons \u003e 内置默认\n\n## 键位\n\n### 树内\n\n| 键 | 动作 | 说明 |\n|----|------|------|\n| `\u003cCR\u003e` / `l` | `open` | 打开文件 / 切换目录展开 |\n| 单击 | 展开/收起目录 | 文件不动，走预览 |\n| 右键 | `yank_abs_path` | 复制绝对路径到剪贴板 |\n| `h` | `close_node` | 关闭目录 / 跳到父目录 |\n| `]` | `cd_to` | 进入：把光标目录设为根 |\n| `[` | `cd_up` | 返回上级 |\n| `/` | `start_filter` | 打开过滤提示框 |\n| `\u003cEsc\u003e` | `escape` | 清 filter → 清选区 + 剪贴板标记（一起清）→ 关树 |\n| `q` | `__quit` | 清 filter 或关树 |\n| `.` / `\u003cM-.\u003e` | `toggle_hidden` | 切换 dotfile 显隐 |\n| `I` / `\u003cM-i\u003e` | `toggle_gitignored` | 切换 gitignored 显隐 |\n| `R` | `refresh` | 强制刷新 |\n| `Y` | `yank_abs_path` | 复制绝对路径（多选时复制所有） |\n| `\u003cC-x\u003e` | `open_split` | 水平分屏打开 |\n| `\u003cC-v\u003e` | `open_vsplit` | 垂直分屏打开 |\n| `o` / `gx` | `system_open` | 系统工具打开：目录→文件管理器，文件→默认程序 |\n| `X` | `execute` | 按文件类型执行（确认后跑在终端） |\n| `a` | `create` | 新建文件（尾随 `/` 为目录） |\n| `d` | `delete` | 删除 / 移入回收站（带确认） |\n| `r` | `rename` | 重命名 |\n| `y` | `copy_mark` | 标记复制 |\n| `x` | `cut_mark` | 标记剪切 |\n| `p` | `paste` | 粘贴到光标目录 |\n| 拖拽 | — | 从文件管理器拖文件/文件夹进来复制（详见下方「拖拽落点」） |\n| `\u003cTab\u003e` | `toggle_select` | 切换多选 |\n| `T` | `trash_panel` | 打开回收站面板 |\n| `\u003cC-e\u003e` / `\u003cC-y\u003e` | 滚动预览 | 滚动主窗口预览 |\n| `g?` | `help` | 键位帮助浮窗 |\n\n### 拖拽落点（drag-and-drop）\n\n从系统文件管理器（Finder 等）把**文件 / 文件夹**拖进 explorer 窗口即复制进来。支持多选、文件夹（递归复制）\n\n两种模式，**按环境自动选择**：\n\n| 环境 | 行为 |\n|------|------|\n| **kitty ≥ 0.47 且 nvim 不挂 tmux** | VSCode 风：按**鼠标松手的落点目录**复制，拖拽经过时**实时高亮**目标目录行（走 kitty DnD 协议 OSC 72） |\n| **tmux / 其它终端** | 自动降级：复制到**键盘光标所在目录**、无高亮（走 bracketed paste）。tmux 不透传入站 OSC 72，这是 tmux 的限制，非本插件可绕过 |\n\n- **安全**：目标已存在同名文件/目录时**自动改名** `xxx (copy)` / `xxx (copy 2)`，**绝不覆盖或删除**任何已存在内容\n- **为何落点需脱 tmux**：落点坐标由终端经 OSC 72 上报，tmux 作为中间终端模拟器不转发该入站序列（kitty DnD 协议留有 `i=` 多路复用器字段，需 tmux 侧实现，目前尚无）。无坐标时退回光标目录方案\n- 关闭落点协议、只保留粘贴回退：`require('vv-utils.drop').setup({ kitty_dnd = false })`\n\n### 过滤提示框\n\n| 键 | 动作 |\n|----|------|\n| `\u003cS-Tab\u003e` | 切换搜索模式（fuzzy → glob → regex） |\n| `\u003cC-n\u003e` / `\u003cC-p\u003e` | 跳到下/上一个匹配 |\n| `\u003cC-x\u003e` / `\u003cC-v\u003e` | 以 split / vsplit 打开匹配 |\n| `\u003cCR\u003e` | 提交（跳到首个匹配） |\n| `\u003cEsc\u003e` / `q` | 取消过滤 |\n\n### 回收站面板\n\n| 键 | 动作 |\n|----|------|\n| `r` / `\u003cCR\u003e` | 恢复到原路径 |\n| `d` | 永久删除条目 |\n| `D` | 清空回收站（带确认） |\n| `q` / `\u003cEsc\u003e` | 关闭 |\n\n## 命令\n\n| 命令 | 说明 |\n|------|------|\n| `:VVExplorerToggle` | 打开/关闭文件树 |\n| `:VVExplorerOpen` | 打开文件树 |\n| `:VVExplorerClose` | 关闭文件树 |\n| `:VVExplorerReveal` | 在树里定位当前文件 |\n| `:VVExplorerFocus` | 聚焦到树窗口 |\n| `:VVExplorerTrash` | 打开回收站面板 |\n\n## 依赖\n\n- **必须**：[vv-utils.nvim](https://github.com/beixiyo/vv-utils.nvim) — 共享 fs/git/UI 工具库\n- **必须**：[vv-icons.nvim](https://github.com/beixiyo/vv-icons.nvim) — 共享图标注册表\n- **可选**：[mini.icons](https://github.com/echasnovski/mini.icons) — 彩色文件/目录图标\n- **可选**：[fd](https://github.com/sharkdp/fd) — 仅 `/` 过滤功能需要\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeixiyo%2Fvv-explorer.nvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeixiyo%2Fvv-explorer.nvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeixiyo%2Fvv-explorer.nvim/lists"}