Typesense怎么用 轻量级搜索引擎教程

Typesense是一个开源的轻量级搜索引擎，部署简单、搜索速度快，适合做网站搜索和电商商品检索。它通过集合（Collection）组织数据，文档写入后即可查询，还支持拼写容错、筛选和排序。下面用 Docker 和 HTTP API 演示从启动服务到完成一次商品搜索的流程，适合先在本机搭建体验，再按业务需要部署到服务器。

第一步：安装Typesense

先确认电脑已安装 Docker，然后在终端创建数据目录，避免容器重启后索引文件丢失：mkdir -p typesense-data。接着启动容器并映射默认 API 端口 8108：docker run -p 8108:8108 -v “$(pwd)/typesense-data:/data” typesense/typesense:30.2 –data-dir /data –api-key=change-this-key。初学时可在本机测试，正式环境请换成足够复杂的密钥，并妥善保存。

容器启动后，另开一个终端检查服务是否就绪：curl http://localhost:8108/health。如果返回表示健康的状态信息，就可以继续操作；若连接失败，先查看容器日志，确认端口映射和启动参数无误。示例里的 change-this-key 是演示值，后续每次请求都要把它换成启动服务时设置的 API 密钥。

第二步：创建集合和写入数据

在 Typesense 里，一组字段相似的文档放在一个集合中。先创建名为 products 的集合，并定义商品名称、类别、价格和库存字段。执行下面请求时，把密钥替换为自己的值；price 用数值类型，便于之后筛选和排序，库存也使用数值，字段类型应与写入的数据保持一致。

创建集合可以用 curl 发送 JSON：curl -X POST http://localhost:8108/collections -H ‘Content-Type: application/json’ -H ‘X-TYPESENSE-API-KEY: change-this-key’ -d ‘{“name”:”products”,”fields”:[{“name”:”name”,”type”:”string”},{“name”:”category”,”type”:”string”,”facet”:true},{“name”:”price”,”type”:”float”},{“name”:”in_stock”,”type”:”bool”}]}’。这里 category 开启 facet，后续可按类别汇总或筛选；建集合成功后，服务会返回集合定义。

接下来添加一条商品文档。每条记录都需要唯一的 id，下面用 p001；其他字段名称和数据类型必须与集合定义一致。把请求发到 documents 端点即可写入，成功时会返回已创建的文档信息。实际导入大量商品时，可使用批量导入接口，并检查每行的处理结果，避免个别格式错误被忽略。

curl -X POST http://localhost:8108/collections/products/documents -H ‘Content-Type: application/json’ -H ‘X-TYPESENSE-API-KEY: change-this-key’ -d ‘{“id”:”p001″,”name”:”轻便通勤双肩包”,”category”:”背包”,”price”:299.0,”in_stock”:true}’。再用类似方式写入其他商品，就完成了最小数据集。商品图片地址等只用于结果展示、不参与搜索或筛选的内容，可以作为额外字段存储，避免不必要地建立索引。

配置字段和搜索参数

设计字段时，先区分哪些内容要全文搜索、哪些用于过滤或展示。名称、品牌、描述通常适合字符串搜索；价格适合数值字段，类别适合开启 facet。集合字段一旦设计不合适，调整可能需要更新 schema 或重新整理索引，因此建议先拿少量真实数据验证，并让所有文档使用一致的数据格式。

• 搜索字段：在 query_by 中写入可检索字段，例如 name；多个字段用逗号分隔。
• 筛选字段：用 filter_by 限定条件，例如 category:=背包 或 price:100..500。
• 结果数量：用 per_page 控制每页返回条数，按页面设计调整。
• 访问密钥：服务端管理密钥不要放进公开网页，前端应使用权限受限的搜索密钥。

第三步：执行搜索查询

集合和文档准备好后，向 products 搜索端点发送 GET 请求。q 是用户输入的关键词，query_by 指定搜索字段；如果想只看在售且价格在 100 到 500 之间的背包，可加筛选参数。查询参数需要进行 URL 编码，避免空格、中文或特殊符号造成请求错误。试试搜索“通勤包”，观察返回的匹配文档。

curl -G ‘http://localhost:8108/collections/products/documents/search’ –data-urlencode ‘q=通勤包’ –data-urlencode ‘query_by=name’ –data-urlencode ‘filter_by=category:=背包 && price:100..500 && in_stock:true’ –data-urlencode ‘per_page=10’ -H ‘X-TYPESENSE-API-KEY: change-this-key’。响应中的 hits 包含匹配商品及相关信息。前端可读取这些结果渲染列表，并在输入变化时发起查询；可加短暂防抖，减少连续请求。

上线前建议根据真实查询调试 query_by、排序和筛选条件，并限制搜索密钥的权限。若团队不想自行维护搜索服务器，也可以了解火山引擎等国内服务选项；润灭整理的相关入口是volcengine.cgref.cn。无论选自建还是托管方案，都先用样例数据验证响应速度、字段能力和运维成本，再决定部署方式。