local-file-picker

local-file-picker

基于 Vue 3 + Express 的本地文件 / 目录选择器，通过 Node.js 后端直接读取文件系统，可获取绝对路径。

功能特性

• 📄 选择文件 / 文件夹 — 可多选，返回本地绝对路径
• 📁 新建文件夹 — 弹窗内可直接创建目录，自动选中新文件夹（需后端中间件支持）
• 🔍 全局搜索 — 支持索引搜索（快）和实时遍历降级搜索
• 📍 面包屑导航 — 路径导航，支持快捷访问家目录、桌面、文档等
• 💾 盘符列表 — Windows 多盘符支持
• ✅ 多选 — Ctrl/Cmd + 点击多选
• 默认目录 —— 通过 defaultPath prop 传入默认目录，打开弹窗直接定位
• 地址栏跳转 —— 弹窗顶部可直接输入目录路径回车跳转，支持绝对路径、相对路径、盘符跳转
• ⚡ SQLite 索引 — 后台建立文件索引，全局搜索毫秒级响应

适用于本地工具、内部后台、Electron 应用等场景，不适合部署到公网（服务端直接读取宿主机文件系统）。

预览

Demo 控制台（9 个 prop 实时切换 + 说明文案 + 完整 API 参考表）：

弹窗打开态（选文件夹 + 暗色主题 + 启用新建文件夹）：

安装

npm install local-file-picker

快速上手

第一步：后端挂载中间件

在你的 Express 应用中挂载 file-picker 中间件：

// server.js
import express from 'express';
import cors from 'cors';
import { createFilePickerMiddleware } from 'local-file-picker';

const app = express();
app.use(cors());
app.use(express.json());

// 将所有 /api/fs/* 路由交给中间件处理
app.use('/api', createFilePickerMiddleware());

app.listen(3000, () => console.log('Server running on http://localhost:3000'));

中间件选项

app.use('/api', createFilePickerMiddleware({
  // SQLite 索引数据库路径（默认 ~/.file-picker-index.db）
  dbPath: '/custom/path/index.db',

  // 建立索引时跳过的目录名（Set 或 Array）
  skipDirs: new Set(['node_modules', '.git', 'dist']),

  // 是否强制重建索引（默认读取 FORCE_REINDEX 环境变量）
  forceReindex: false,
}));

第二步：前端使用 Vue 组件

安装后构建产物引入

// main.js 或按需引入
import { FilePickerModal } from 'local-file-picker/client';
import 'local-file-picker/dist/file-picker.css'; // 引入样式

组件用法

<template>
  <button @click="open = true">选择文件</button>

  <FilePickerModal
    :visible="open"
    mode="file"
    api-base="http://localhost:3000/api"
    @close="open = false"
    @confirm="onConfirm"
  />
</template>

<script setup>
import { ref } from 'vue';
import { FilePickerModal } from 'local-file-picker/client';
import 'local-file-picker/dist/file-picker.css';

const open = ref(false);

function onConfirm(paths) {
  // paths 是选中路径的数组，如 ['C:\\Users\\xuze\\Documents\\report.pdf']
  console.log('选中文件:', paths);
  open.value = false;
}
</script>

组件 Props

组件 Events

记住上次的"全局"选择：包自身不落盘（消费方每次启动的 origin 可能变，localStorage 会随之失效）， 由消费方在 globalSearchChange 里存下来、下次打开时通过 defaultGlobalSearch 传回即可：

<FilePickerModal
  :visible="open"
  :default-global-search="globalSearchPref"
  @global-search-change="(v) => (globalSearchPref = v)"
/>

API 接口说明

中间件挂载后提供以下接口（以挂载在 /api 为例）：

本地开发 Demo

git clone https://github.com/xz333221/local-file-picker.git
cd local-file-picker
npm install
npm run dev:server   # 后端 http://localhost:8642
npm run dev:client   # 前端 http://localhost:7891

或一键启动：

npm run dev

构建发布包

npm run build
# 输出 dist/file-picker.mjs 和 dist/file-picker.css

发布到 npm：

npm publish

技术栈

License

MIT © 2026 xuze

快速启动

# 1. 安装后端依赖
cd server && npm install

# 2. 安装前端依赖
cd ../client && npm install

# 3. 启动后端（端口 8642）
cd ../server && npm run dev

# 4. 启动前端（端口 7891）— 另开终端
cd client && npm run dev

然后在浏览器打开 http://localhost:7891

端口说明

API 端点