Protobuf字段编号须从1起顺序分配，禁用0和19000–19999保留号，已发布编号不可变更，需预留空档；端口冲突时查lsof/netstat；UNAVAILABLE错误需拦截日志、验连接状态、禁TLS测试；proto import路径须相对于--proto_path根目录。
Protobuf 文件里字段编号不能乱填
字段编号不是随便写个数字就行，它直接决定序列化后的二进制格式。填错会导致服务端和客户端解析不一致，出现 invalid wire type 或字段值为默认值（比如 0、""）这类静默错误。
实操建议：
- 从
1开始顺序编号，跳过0（Protobuf 不允许）和保留号（19000–19999） - 已发布的字段编号绝不能改，哪怕字段名变了——否则老客户端会把新字段当未知字段丢弃
- 预留空档（比如每 10 个号留 1 个）方便后续加字段，例如：
1、2、10、20 - 重复使用编号（比如两个字段都用
1）会导致编译失败：Field number 1 has already been used
gRPC Server 启动时报错 “port already in use”
常见于本地反复调试时没杀干净进程，或多个服务误绑同一端口（如都用 50051）。错误信息是：bind: address already in use，但 gRPC 默认不打印详细堆栈，容易误判成代码问题。
实操建议：
- 先查端口占用：
lsof -i :50051（macOS/Linux）或netstat -ano | findstr :50051（Windows） - Go 服务启动前可加端口检测逻辑，Python 可捕获
OSError并提示；Java 的NettyServerBuilder需手动设usePlaintext()才能监听 localhost - 别硬写死端口，用环境变量或配置文件注入：
GRPC_PORT=${GRPC_PORT:-50051} - Docker 环境下注意宿主机端口映射冲突，
docker run -p 50051:50051要确认宿主机没被占
客户端调用返回 UNAVAILABLE 却没具体原因
UNAVAILABLE 是最模糊的 gRPC 错误码之一，可能对应网络断开、服务未启动、TLS 配置不匹配、甚至 DNS 解析失败。它不带底层错误细节，光看状态码没法定位。
实操建议：
- 加日志拦截器：Go 用
grpc.WithUnaryInterceptor打印status.Code()和status.Err().Error()；Python 用grpc.intercept_channel - 检查连接是否建立成功：调用前先发个
GetMetadata或用channel.state（Python）/cc.GetState(true)（Go）判断是否READY - 禁用 TLS 测试：客户端构造 channel 时显式加
insecure参数（如 Go 的grpc.WithTransportCredentials(insecure.NewCredentials())），排除证书问题 - 用
grpcurl命令行验证服务可达：grpcurl -plaintext localhost:50051 list
proto 文件 import 路径对不上就编译不过
Protobuf 编译器（protoc）只认 --proto_path（即 -I）指定的根目录。import 语句里的路径是相对于这个根的，不是相对于当前 .proto 文件位置。路径错一个字母，就会报 File not found。
实操建议：
- 统一用 vendor 目录管理第三方 proto，比如把
google/api/annotations.proto放到vendor/google/api/，然后加-I vendor - 所有 import 写绝对路径：
import "user/v1/user.proto";，而不是import "./user.proto";（后者 protoc 不支持） - 生成代码时，
protoc命令的--go_out、--python_out等参数必须跟在对应-I之后，顺序错会导致生成路径混乱 - IDE 插件（如 VS Code 的 Protobuf Support）需要单独配置
protoc的 include paths，否则编辑器里标红但命令行能过
