参考

Fuse.js 构造方式、全部选项与默认值、实例方法、静态 API、结果结构、扩展/逻辑搜索语法 速查。版本基线 Fuse.js 7.x（7.4.2）。默认值取自源码 Config。

一、构造与查询

写法	用途
new Fuse(list, options?)	创建实例（list 为字符串/对象数组）
new Fuse(list, options, index)	传入预建索引（第三参）
fuse.search(pattern)	查询，返回结果数组
fuse.search(pattern, { limit })	限制返回条数
fuse.search(expression)	逻辑搜索（传 $and/$or 对象）

import Fuse from "fuse.js"
const fuse = new Fuse(books, { keys: ["title", "author"] })
fuse.search("jon")

二、基础选项

选项	默认	说明
keys	[]	要搜索的字段（对象数组必填；字符串数组不需要）
isCaseSensitive	false	是否区分大小写
ignoreDiacritics	false	是否忽略变音符号（café≈cafe）
includeScore	false	结果是否含 score
includeMatches	false	结果是否含 matches（高亮区间）
minMatchCharLength	1	只纳入长度超过该值的匹配片段
shouldSort	true	是否按 score 排序
findAllMatches	false	完美匹配后是否继续扫完收集全部片段

三、模糊匹配选项

选项	默认	说明
threshold	0.6	score 上限闸门，越小越严格（0=完美，1=匹配一切）
location	0	期望匹配出现的大致位置
distance	100	匹配离 location 多远可接受；越大位置惩罚越轻
ignoreLocation	false	true 则忽略 location/distance，任意位置可匹配

默认位置窗口 ≈ threshold × distance（0.6×100=60 字符）。长文本靠后匹配不上 → 开 ignoreLocation。

四、高级选项

选项	默认	说明
useExtendedSearch	false	启用 unix 风格扩展搜索语法
getFn	内置取值	自定义按路径从对象取值（可做转换）
sortFn	内置	自定义结果排序（需 shouldSort: true）
ignoreFieldNorm	false	true 则 score 忽略字段长度归一
fieldNormWeight	1	字段长度归一的影响力（越大越强调短字段命中）

五、keys 三种写法

keys: [
  "title", // 顶层字段
  "author.firstName", // 嵌套：点号路径
  ["author", "first.name"], // 嵌套：数组路径（键名含字面点号时必用）
  ["tags", "value"], // 数组内对象字段
  { name: "title", weight: 0.7 }, // 加权（未指定 weight 默认 1）
]

六、实例方法

方法	用途
search(pattern, opts?)	查询；返回结果数组（无匹配为 []）
add(doc)	新增一条并更新索引
remove(predicate)	按谓词删除，返回被删项数组
removeAt(idx)	按下标删除，返回被删项
setCollection(docs, index?)	整体替换集合
getIndex()	取内部索引对象

七、静态 API

成员	用途
Fuse.createIndex(keys, list)	预建索引（传给 new Fuse 第三参）
Fuse.parseIndex(json)	把序列化的索引还原为索引对象
index.toJSON()	序列化索引（配合 parseIndex）
Fuse.version	版本号

八、结果结构

{
  item,        // 命中的原始数据项
  refIndex,    // 在原始 list 中的下标
  score,       // 0 完美 ~ 1 不匹配（需 includeScore）
  matches: [   // 需 includeMatches
    {
      indices, // 命中的 [start,end] 闭区间数组，如 [[4,9]]
      value,   // 被命中的原文
      key,     // 命中的字段名（多字段时）
    },
  ],
}

⚠️ score：0 最匹配、1 最不匹配，越小越相关。indices 是闭区间，切片取到 end + 1。

九、扩展搜索语法（需 useExtendedSearch）

写法	含义
jscript	模糊匹配
=scheme	精确相等
'python	包含匹配
!ruby	不包含（排除）
^java / !^java	前缀 / 反前缀
.js$ / !.js$	后缀 / 反后缀
空格 / |	AND（都满足）/ OR（任一组满足）

十、逻辑搜索

fuse.search({ $and: [{ author: "abc" }, { title: "xyz" }] })
fuse.search({ $or: [{ author: "abc" }, { author: "def" }] })
// 键名含字面点号：
fuse.search({ $and: [{ $path: ["author", "first.name"], $val: "jon" }] })

十一、构建产物

产物	体积（min+gzip）	含
完整版（fuse.mjs / fuse.cjs）	约 8.6 KB	全部特性
basic 版（fuse.basic.min.mjs）	约 6.8 KB	仅核心模糊搜索
worker 版（fuse.worker.mjs）	—	配合 Web Worker

---

API 查完，回 指南 · 基础 看 keys 与调参，或 指南 · 专家 看算法与工程化。