NEST客户端初始化时必须指定正确的连接地址和序列化配置
直接用
new ConnectionSettings()而不指定
Uri会导致连接失败，错误信息通常是
Unable to connect to the remote server或空响应。默认使用
http://localhost:9200，但 Elasticsearch 8.x 默认启用 HTTPS 和认证，本地开发若未改配置，需显式传入
new Uri("http://localhost:9200")。
另一个常见坑是序列化器：Elasticsearch 7.10+ 默认返回
_source字段为对象结构，若 C# 类型字段名与 JSON 键不一致（比如驼峰转下划线），不配置
DefaultFieldNameInferrer就会反序列化为空值。 用
new ConnectionSettings(new Uri("http://localhost:9200")).DefaultFieldNameInferrer(s => s.SnakeCase()) 匹配 Elasticsearch 默认命名策略
若启用了 Basic Auth，需添加 .BasicAuthentication("username", "password")
ES 8.x 启用 TLS 时，必须用 https://并设置
.CertificateFingerprint("...") 或禁用证书验证（仅开发）
Query DSL 写法要匹配 NEST 的强类型 API 风格
别照搬 Kibana Console 里的 JSON 查询直接塞进
Search<t>()</t>—— NEST 不接受原始 JSON 字符串作为查询主体，而是通过方法链构造。比如想查
title包含 “net” 且
status为 “published”，不能写
.Query("{ \"match\": { \"title\": \"net\" } }")，而要用：var response = client.Search<Article>(s => s
.Query(q => q
.Bool(b => b
.Must(
m => m.Match(ma => ma.Field(f => f.Title).Query("net")),
m => m.Term(t => t.Field(f => f.Status).Value("published"))
)
)
)
);
Match()用于全文检索，
Term()用于精确匹配（注意字段是否被
keyword类型映射） 字段引用必须用表达式
f => f.Title，不能用字符串
"title"，否则无法做编译期检查和自动映射 聚合、高亮、排序都得在同一个
Search<t>()</t>调用中声明，不能分多次调用
处理返回结果时要注意 Hits 和 Source 的解包逻辑
NEST 返回的
response.Hits是
IHit<t>[]</t>，不是原始文档列表。
IHit<t>.Source</t>才是反序列化后的 C# 对象，而
IHit<t>.Id</t>、
.Score、
.Highlight等元数据需单独访问。 如果
Source为 null，大概率是字段未映射或查询字段不在
_source中（检查索引 mapping 的
"_source": {"enabled": true}）
高亮内容在 hit.Highlight?.GetValues("title")，不是直接挂在 Source上 分页靠
.From(0).Size(10)，但注意 ES 默认
from + size ≤ 10000，深度分页要用
SearchAfter()或
PointInTime
异步搜索必须用 Async 方法族，且不能混用同步/异步客户端实例
NEST 的
ISearchResponse<t></t>和
Task<isearchresponse>></isearchresponse>完全不同，调用
client.SearchAsync<t>()</t>却用
.Result强制同步等待，容易引发死锁（尤其在 ASP.NET Core 早期版本或 UI 线程中）。 始终用
await client.SearchAsync<article>(...)</article>，并在方法签名加
async Task不要在
Startup.cs或
Program.cs中注册同步版
IElasticClient，统一用
AddElasticClient()（NEST 7.17+）或手动注册
IElasticLowLevelClient+
IElasticClient批量操作如
BulkAsync()和单文档
IndexAsync()同理，异步方法必须走异步路径
Elasticsearch 版本与 NEST 版本严格对应，比如 ES 8.4 要用 NEST 8.4.x，低版本 NEST 连高版本 ES 可能解析不了新字段（如
result中的
took类型变更），也容易因 HTTP header 差异静默失败。
