必须用 Grpc.AspNetCore——Grpc.Core 已被官方标记为 Legacy，.NET 6+ 不再更新且不支持 HTTP/2 关键特性；新手易因注册、配置顺序、HTTPS 设置、错误开关、proto 编译、命名空间、超时控制、流式响应等细节导致静默失败。
服务端该用 Grpc.AspNetCore 还是 Grpc.Core？
现在必须用 Grpc.AspNetCore ——Grpc.Core 已被官方标记为 Legacy，.NET 6+ 中不再更新，且不支持 HTTP/2 的部分关键特性（如流控、优先级），在容器或 Kubernetes 环境下容易出现连接复位或 UNAVAILABLE 错误。
但新手直接上 Grpc.AspNetCore 容易掉进“黑盒陷阱”：比如服务注册后接口不可见、健康检查失败、或 Startup.cs / Program.cs 配置顺序错乱导致中间件未生效。
- ASP.NET Core 6+ 必须在
Program.cs中调用AddGrpc()和MapGrpcService，漏掉任一都会让服务“静默失效”() - 若同时启用 HTTPS 和 gRPC，必须确保 Kestrel 的
HttpProtocols显式设为HttpProtocols.Http2，否则 Windows 上可能 fallback 到 HTTP/1.1 并报PROTOCOL_ERROR -
Grpc.AspNetCore默认启用EnableDetailedErrors = false，调试时建议临时设为true，否则客户端只收到泛泛的UNKNOWN错误，无法定位是序列化失败还是业务异常
.proto 文件编译失败的三个高频原因
不是语法写错了，而是构建上下文没对齐。VS 或 dotnet CLI 编译 .proto 时失败，90% 出在 Grpc.Tools 版本与 SDK 不兼容，或生成路径被覆盖。
-
Grpc.Tools必须和Grpc.AspNetCore/Grpc.Net.Client版本严格一致（例如都用2.63.0），版本差哪怕一个小号，就可能生成空类或缺失Base类型 -
.csproj中GrpcServices="Server"或"Client"，不能只写GrpcServices="Both"——后者在某些 SDK 补丁版本中会跳过生成 - 如果项目引用了多个
.proto文件，且它们定义了同名message（哪怕在不同package下），C# 命名空间冲突会导致编译器报Type name does not exist in namespace，这时得加option csharp_namespace = "Your.Company.Protos";强制隔离
客户端调用超时却收不到 DeadlineExceeded？
默认情况下，GrpcChannel 不会主动中断挂起的请求，而是等底层 TCP 超时（通常几分钟），你看到的其实是 TaskCanceledException，而非预期的 gRPC 状态码。
- 必须显式传入
CancellationToken，且该 token 应来自new CancellationTokenSource(5000)，而不是CancellationToken.None -
CallOptions中的Deadline是服务器侧感知的截止时间，它依赖客户端和服务端系统时钟同步；实际更可靠的是客户端本地的CancellationToken - 若服务端是 ASP.NET Core，还需确认
KestrelServerLimits中的MaxConcurrentUpgradedConnections没被设得太低，否则高并发下新连接会被排队，放大表观超时
流式响应中 IAsyncEnumerable 被提前释放
服务端返回 async IAsyncEnumerable，但客户端只收到前几条就断开，日志里没有错误——大概率是服务端方法体里用了 yield return，但没把整个异步流包装在 try/finally 或 using 块中，导致流还没发完，ServerCallContext 就被回收了。
- 务必在流生成逻辑外层包一层
try { ... } finally { await CleanupAsync(); }，确保资源释放不依赖 GC - 不要在流迭代中途
await长耗时操作（如数据库查询），这会让 gRPC 流控机制误判为“卡顿”，触发RESET_STREAM - 客户端消费时，
await foreach必须配合CancellationToken，否则网络中断时循环不会退出，线程持续阻塞
最麻烦的点往往藏在“看起来没问题”的地方：比如 csharp_namespace 拼写差一个字母，生成的类就完全找不到；或者 Grpc.Tools 更新了但没清理 obj/ 目录，旧缓存代码还在参与编译。这些细节不报红，但能让整个链路静默失败。
