先检查 Elasticsearch 服务是否运行及网络是否连通，浏览器访问 http://127.0.0.1:9200 能返回 JSON 则服务正常；否则排查 Docker 端口映射、防火墙、network.host 配置或 URI 协议头缺失等问题。
NEST 客户端连不上 Elasticsearch 时先查什么
90% 的连接失败不是代码问题，而是服务没跑起来或网络不通。Elasticsearch 默认监听 localhost:9200，但 Docker 启动、Windows 服务、WLS 环境下地址常是 http://127.0.0.1:9200 或 http://host.docker.internal:9200 —— 浏览器直接访问这个地址，能返回 JSON 就说明服务在线；返回超时或拒绝连接，就别急着改 C# 代码。
常见错误现象：Unable to connect to the remote server、Connection refused、HttpRequestException 带 StatusCode=0。
- 确认
elasticsearch.yml中network.host没写死为127.0.0.1（本地开发可设为0.0.0.0，但别在生产用） - 检查防火墙或 Docker 网络：Docker 运行时加
-p 9200:9200，且宿主机能 ping 通容器 IP -
ConnectionConfiguration初始化时别漏掉http://协议头，new Uri("9200")是错的，必须是new Uri("http://localhost:9200")
全文搜索写错 Query DSL 导致无结果或报错
NEST 把 Match、MultiMatch、QueryString 这些封装成强类型方法，但字段名拼错、映射类型不匹配、大小写敏感都会让搜索“静默失败”——没报错，但 Hits.Count 永远是 0。
使用场景：想搜商品标题含“蓝牙耳机”，但索引里字段叫 ProductName，而代码里写了 f => f.Name，就查不到。
- 字段名必须和 Elasticsearch 中实际 mapping 一致，区分大小写；用 Kibana 的
GET /your-index/_mapping确认 -
Match默认是best_fields，如果字段是text类型但开了"index": false，就搜不了——得用keyword子字段或改 mapping - 中文搜索务必确认用了
ik_smart或ik_max_word分词器，否则默认标准分词器对中文基本无效 - 示例：正确写法是
.Query(q => q.Match(m => m.Field(f => f.ProductName).Query("蓝牙耳机")))，不是.Field("productname")字符串硬编码
NEST 7.x 升级到 8.x 后 SearchDescriptor 编译不过
8.x 彻底移除了 ISearchRequest 和旧版 SearchDescriptor 的部分构造方式，最典型的是 .From(0).Size(10) 必须改成 .From(0).Size(10)（看似一样，但底层泛型约束变了），而且 Sort、Aggregations 的链式调用入口也收紧了。
性能影响：8.x 默认启用 SourceFiltering，不显式调用 .Source(s => s.Includes(i => i.Fields(...))) 就会返回全部字段，网络开销变大。
- 删掉所有
using Nest.Resolvers.Converters;—— 8.x 不再需要自定义 JSON 转换器来处理日期 -
LowLevelDispatch接口废弃，改用Client.LowLevel.Search或直接发 HTTP 请求 - 聚合写法从
.Aggregations(a => a.Terms("by_category", t => t.Field("category.keyword")))变成必须带泛型：.Aggregations(a => a.Terms("by_category", t => t.Field(f => f.Category.Suffix("keyword")))) - 如果还用 7.x 的
Nest.JsonNetSerializer，8.x 会直接抛NotSupportedException
搜索结果反序列化失败，Hit.Source 是 null
不是数据丢了，是 NEST 默认只反序列化你声明的 POCO 类中「有对应字段」的部分。如果索引里有个 tags 字段是数组，但你的 C# 类里写成 public string Tags { get; set; }，整个 Source 就会为 null，而不是抛异常。
容易踩的坑：用 dynamic 或 object 接收结果，看起来能跑，但取值时才崩，且错误信息极不友好。
- 确保 POCO 类字段名、类型、嵌套结构和 mapping 完全一致；用
[Text(Name = "product_name")]显式绑定别名字段 - 字段缺失时 NEST 默认跳过，加
[JsonProperty(Required = Required.Always)]可触发反序列化异常，方便定位 - 调试时先用
response.DebugInformation查看原始 JSON，比盲猜快得多 - 如果字段类型不确定（比如有的文档是 string，有的是 int），别用强类型
T，改用SearchResponse+ 手动解析hit.Source.ToString()
事情说清了就结束。Elasticsearch 搜索真正卡住的地方，往往不在 C# 语法，而在 mapping 定义、分词器配置、网络可达性这三层上——代码写对了，但索引建错了，照样搜不出东西。
