django-elasticsearch-dsl不是开箱即用方案，必须明确定义Index类、注册Document、配置ES连接及中文分词器，否则同步失败或搜索为空；__icontains和SearchVector不走倒排索引，无法支持权重排序、高效全文检索与中文分词。
django-elasticsearch-dsl 是当前最稳的路径，不是“装完就能搜”，跳过映射定义、同步机制和分词配置，90% 的项目会在搜索返回空结果时卡住。
为什么 __icontains 和 SearchVector 不能凑合用
它们本质是数据库层面的模糊匹配或预计算向量，不走倒排索引：查“跑步鞋”找不到“跑鞋”，搜“笔记本电脑”匹配不到“本本”，更没法按标题权重 ×3、正文权重 ×1 动态排序。百万级数据下响应从 200ms 涨到 3s+ 是常态，且中文完全靠猜——因为没分词器。
django-elasticsearch-dsl 同步必须配对三件事
只注册模型、不写 Index 类，或漏掉 @registry.register_document，ES 里压根没数据。
-
ES_URL必须在settings.py显式声明，例如'http://127.0.0.1:9200'；靠环境变量 fallback 会静默失败 - Document 类必须继承
django_elasticsearch_dsl.Document（不是elasticsearch_dsl.Document），字段名严格对齐模型字段，否则update_index时忽略该字段 - 中文字段要在
Index类里加'analyzer': 'ik_max_word'，并确认 Elasticsearch 已安装 ik 插件——没装的话，“人工智能”会被拆成“人”“工”“智”“能”四个单字
查询时 Search 实例别硬拼 JSON
直接调 requests.post() 构造 DSL 容易错漏字段、难调试、无法复用。用 elasticsearch_dsl.Search 链式调用更可靠：
from elasticsearch_dsl import Search
s = Search(index='product').query(
'multi_match',
query='无线耳机',
fields=['name^3', 'description']
)
注意点：
python-script-generator
下载
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
立即学习“Python免费学习笔记（深入）”；
-
s[:100]是硬限制，ES 默认只返回前 10 条；from/size超过 10000 会报result window is too large - 字段权重用
^3语法，不是boost=3 - 高亮要显式加
.highlight('content').highlight_options(order='score')，取结果时用hit.meta.highlight.content[0]
生产环境最容易被跳过的降级逻辑
ES 连不上、索引不存在、查询超时——这些不是该抛 500 的错误，而是要 fallback 到 Model.objects.filter(name__icontains=q) 保底。别指望前端加防抖或后端校验能覆盖所有异常路径；ConnectionError 和 NotFound Error 必须区分处理：前者走 DB 模糊查，后者该触发告警并自动重建索引。
同步机制一旦写死在信号里，上线改 schema 就得停写入、重建索引、切 alias——真正的坑不在怎么搜，而在怎么让搜这件事不拖垮整个数据写入链路。
