/notes/plugin/custom-search-readme
---
date: 2026-04-30 14:15
updated: 2026-06-01 18:00
---
ᅟ<span class="date">Updated: 2026-06-01 18:00</span>
# 📋 Custom Search Plugin for Obsidian
**custom-search** 是一款为大规模笔记库（数千至数万文件）设计的**轻量、快速、精准**的Obsidian搜索增强插件。不建索引，即时搜索。
- 原生搜索 = 每次都在整座图书馆里检索，馆越大越慢。
- Custom Search = 先把几本书拿到桌上，只在这几本里翻。保持渲染。
**🎯 解决哪些痛点？**
- **原生搜索太慢？** → 本插件无索引延迟，通常 0.2-0.5 秒返回結果。
- **范围难控制？** → 支持文件组/组合，可保存、可复用、可作默认。
- **结果不直观？** → 三种显示模式（单行/三行滚动/展开），全局或单条切换，MD渲染。
- **反复搜相同内容？** → 完整搜索历史，快捷键切换，长按弹出列表。
- **需要排序？** → 文件/组/模式三级优先级，拖拽调整。
- **文本中有语法标签、标点？** → 插索时自动过滤。
![[custom-search.png|400]]
---
## 🚀 快速开始
### 安装
1. 下载本项目的 `main.js` 和 `manifest.json` 文件。
2. 在 Obsidian 库的 `.obsidian/plugins/` 目录下，创建一个名为 `custom-search` 的文件夹。
3. 将下载的两个文件放入 `custom-search` 文件夹中。
4. 在 Obsidian 中，进入 `设置` → `第三方插件`，**禁用安全模式**。
5. 在已安装插件列表中，启用 `Custom Search` 插件。
### 基本使用流程
1. **打开搜索面板** — 使用命令或右键菜单，选择`搜索面板`
2. **输入搜索内容** — 手动输入，或从历史下拉中选择（有选中文本时会自动填入）
3. **选择范围** — 使用预定范围，或自定义正则（可加载已有文件组）
4. **执行搜索** — 结果显示在右侧边栏
5. **点击跳转** — 点击结果跳转（Ctrl+点击在新标签页打开）
> 💡 **快速搜索**：选中文本后使用右键`预设范围快搜`，一键执行。
---
## 🔍 搜索方式
| 方式 | 怎么用 | 适用场景 |
|:---|:---|:---|
| **预定范围** | 点击「预定范围」按钮，使用已保存的文件组/组合 | 日常固定范围搜索 |
| **自定义范围** | 在编辑区手写文件名正则（支持包含/排除） | 临时精准控制范围 |
| **原生搜索** | 点击「原生」按钮，或使用「手写查询」 | 复杂条件（AND/OR/元数据） |
> 💡 **快速切换**：前两种方式均可一键转为原生搜索。
---
## 📁 管理文件组与组合（核心功能）
### 文件组 (Group)
一组正则表达式模式的集合，用于定义搜索范围。
**示例**（俱舍论相关文件）：
```
(俱舍论|AKBh)\d+\.md
^kosa\/ju\/
!.+疏22\.md # 排除包含「疏22」的文件
```
### 组合 (Combination)
将多个文件组组合成一个更大的范围。
### 常用操作
- **设为临时默认**：点击「⭐ 设为临时默认预定范围」，之后「预定范围」按钮会显示⭐标记。
- **应用到本次搜索**：点击「🔍 应用为自定义范围」，模式会填充到编辑区，可继续微调。
- **写入手写查询**：点击「✍️ 写入手写搜索查询区」，生成原生搜索语法。
---
## 🖱️ 结果面板与快捷键
| 操作 | 效果 |
|:---|:---|
| 点击结果行 | 跳转并高亮 |
| `Ctrl+点击` | 新标签页打开 |
| 点击左侧序号 | 循环切换该条 A→B→C |
| `↑` / `↓` | 选择上一个/下一个结果 |
| `Enter` | 跳转到选中结果 |
| `Home` / `End` | 第一个/最后一个结果 |
| `Ctrl+←` / `Ctrl+→` | 切换搜索历史 |
| `Ctrl+\` | 显示历史面板 |
| `Escape` | 清除选中焦点 |
### 三种显示模式
| 模式 | 显示方式 | 适用场景 |
|:---|:---|:---|
| **A（单行）** | 只显示匹配行，动态截取 | 快速浏览，节省空间 |
| **B（3行+滚动）** | 匹配行 + 前后各一行，固定高度 | 需要上下文参考 |
| **C（展开）** | 匹配行 + 前后各一行，完全展开 | 需要完整上下文 |
> 文件头悬停显示「«」，可批量切换该文件下所有结果的模式。
---
## ⚙️ 设置项速查表
| 分类 | 设置项 | 默认值 | 说明 |
|:---|:---|:---|:---|
| 搜索 | 默认显示模式 | A | A=单行，B=三行滚动，C=展开 |
| 搜索 | 启用布尔查询 | 关 | 语法 `&` `\|` `!` `( )` |
| 历史 | 最大保存历史数 | 10 | 范围 1-100 |
| 历史 | 历史面板宽度 | 256px | 范围 200-600px |
| 外观 | 多种颜色自定义 | 默认色 | 文件名、匹配行、关键词高亮、按钮等 |
| 优先级 | 启用结果排序 | 关 | 按文件→组间→组内模式排序 |
---
## 💡 提示与技巧
### 正则表达式小贴士
- 路径中的 `/` 需要转义：`^kosa\/ju\/`
- 常用：`\d` 数字，`\.` 点号，`(A|B)` 或
### 排除规则（文件名匹配时）
以 `!` 开头的行为排除规则：
```
!.+疏22\.md # 排除包含「疏22」的文件
!^vibhasa\/others\/ # 排除该路径下所有文件
```
如需匹配以 `!` 开头的模式，使用转义 `\!`。
### 布尔查询语法（内容搜索时）
```
佛性 & 眾生 # 空格 或 & → AND 包含「佛性」且包含「如來藏」
佛性 | 如來藏 # | → OR 包含「佛性」或「如來藏」
佛性 !外道 # ! → NOT 包含「佛性」但不包含「外道」
(佛性|如來藏) 眾生 # ( ) → 分組 包含（佛性或如來藏）且包含「眾生」
```
> ⚠️ 與原生搜索不同：原生用空格表示 OR，本插件空格表示 AND
> 仅当未勾选「无视标签」「忽略变音」，且内容不包含正则特殊字符时生效。
### 忽略变音/标签
- **忽略变音**：`śūnyatā` ↔ `sunyata` 可匹配
- **无视标签**：忽略 HTML 标签、Markdown 语法和标点符号
⚠️ 互斥关系：
「无视标签」「布尔查询」「正则模式」三者互斥。
「忽略变音」与「布尔查询」互斥。
---
## 📊 与原生搜索对比（何时用哪个？）
| 场景 | 推荐使用 |
| ----------------------- | :-----------: |
| **日常关键词查找** | Custom-Search |
| **限定文件名/路径、特定范围** | Custom-Search |
| **排除特定文件（草稿、注解、备份）** | Custom-Search |
| **需要结果排序、渲染** | Custom-Search |
| **笔记库很大（>5000文件）** | Custom-Search |
| **反覆搜索相关主题（善用历史记录）** | Custom-Search |
| **需要排除内容中的关键词（内容 NOT）** | Custom-Search |
| **忽略标签语法及标点** | Custom-Search |
| **变音符号忽略** | Custom-Search |
| **需要跨行 AND 逻辑** | 原生搜索 |
| **搜索范围很宽（全库）** | 原生搜索 |
| **需要多个搜索面板对比** | 原生搜索 |
> 💡 **最佳实践**：Custom-Search 做主力，复杂需求一键转原生。
---
## ❓ 常见问题（FAQ）
**Q: 搜索没结果？**
A: 检查文件名模式是否匹配到文件，关键词是否存在。查看控制台（`Ctrl+Shift+I`）是否有错误提示。
**Q: 排序不生效？**
A: 检查「启用结果排序」是否开启。注意「文件优先级」匹配的文件会成为“优先文件”，不受后续排序规则影响。
**Q: 历史记录/配置保存在哪？**
A: `.obsidian/plugins/custom-search/data.json`。插件更新时会自动备份旧配置。
**Q: 如何恢复默认设置？**
A: 外观 →「重置所有颜色」；优先级 →「重置所有排序设置」；管理界面 →「清除临时默认」。
---
## 🔗 链接
- GitHub 仓库：[arpcn/obsidian-custom-search](https://github.com/arpcn/obsidian-custom-search)
- 问题反馈：[Issues](https://github.com/arpcn/obsidian-custom-search/issues)
---
**总结**：本插件专注于**文件名/路径范围的精准控制**和**大库性能**，覆盖 80% 的日常搜索场景。需要元数据或跨行布尔查询时，一键切到原生搜索即可。二者互补，各取所长。
---
📖 需要完整设置说明、技术细节或详尽更新日志？请查阅[完整手册](custom-search-readme_full)