先确认服务运行、端口开放、SDK与服务版本匹配；再检查ConnectParam配置（含认证和超时）；接着验证字段schema（主键、向量维度、VarChar长度）；最后确保flush()和loadCollection()正确调用。
Milvus Java客户端连不上服务？先确认这三件事
绝大多数连接失败不是代码问题，而是环境没对齐。Milvus 2.x（当前主流）要求客户端和服务端协议版本严格匹配，MilvusClient 默认用 gRPC 连接 localhost:19530，但这个地址可能根本没服务，或者防火墙拦了。
- 检查 Milvus 服务是否真在运行：
docker ps | grep milvus（Docker 部署）或systemctl status milvus（systemd），别只看启动命令有没有报错 - 确认端口开放：
telnet localhost 19530或nc -zv localhost 19530，如果连不通，可能是容器网络模式不对（比如用了host模式但宿主机没开对应端口） - 核对客户端 SDK 版本和 Milvus 服务版本兼容性——
milvus-sdk-java2.4.x 只支持 Milvus 2.4.x，混用 2.3.x 客户端连 2.4.x 服务会抛io.grpc.StatusRuntimeException: UNIMPLEMENTED
初始化 MilvusClient 时该选 ConnectParam 还是 ClientParam？
SDK 2.3+ 已废弃 ClientParam，所有连接配置必须走 ConnectParam。老教程里用 new ClientParam.Builder().withHost(...) 的写法会编译失败。
-
ConnectParam.newBuilder()是唯一入口，必须显式调用.withHost()和.withPort()，缺一不可 - 如果 Milvus 启用了认证（如
admin:123456），得加.withAuthorization("admin", "123456")，否则连上也执行不了任何操作，错误信息是io.milvus.exception.MilvusException: code=15, message=invalid token - 超时设置别忽略：
.withConnectTimeoutMs(5000)和.withReadTimeoutMs(15000)，尤其在 k8s 环境下，DNS 解析慢或 service endpoint 波动时，不设读超时会导致线程卡死
Collection 创建失败：字段 schema 写错的典型表现
Java SDK 对字段定义极其敏感，FieldType 构建出错不会立刻报错，而是在 createCollection() 调用时炸，错误信息往往只显示 io.milvus.exception.ParamException: Field name is illegal，实际原因五花八门。
- 主键字段必须且只能有一个，且类型必须是
DataType.Int64（不能是Int32），名字固定为id或自定义，但得显式标.withIsPrimaryKey(true) - 向量字段必须指定维度：
.withDimension(128)，漏写会直接抛NullPointerException；维度值必须和你后续插入的 float[] 长度一致，否则插入时报vector dimension mismatch - 非向量字段（如
text字符串）不能设.withDataType(DataType.VarChar)就完事——还得加.withMaxLength(65535)，否则创建失败，错误提示含糊，只说invalid field type params
插入数据后查不到？注意 flush() 和 loadCollection() 的调用时机
Milvus 不是实时可见的数据库。Java 客户端插入数据后，数据还在内存 buffer 里，不主动刷盘 + 加载进内存，search() 永远返回空结果。
立即学习“Java免费学习笔记（深入）”；
- 插入完成后必须调用
milvusClient.flush(FlushParam.newBuilder().withCollectionNames(Arrays.asList("my_collection")).build())，否则数据没落盘，重启服务就丢 - 新创建的 collection 默认不在内存中，首次查询前要先
milvusClient.loadCollection(LoadCollectionParam.newBuilder().withCollectionName("my_collection").build())，否则search()报collection not loaded - 开发阶段可加日志验证：
milvusClient.getCollectionStatistics(GetCollectionStatisticsParam.newBuilder().withCollectionName("my_collection").build())返回的row_count才是真实入库数，别只信插入返回的InsertResponse
最常被跳过的其实是 flush 后的等待逻辑——flush() 是异步触发，但 loadCollection() 必须等 flush 完成才能生效，否则加载的是旧快照。没有 sleep 或轮询确认 getCollectionStatistics 结果稳定前，就急着搜，大概率扑空。
