# 内部错误: grpc: 遇到 protobuf 未知字段: 字段编号 12345

- **ID:** `grpc/grpc-protobuf-unknown-field`
- **领域:** grpc
- **类别:** encoding_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

服务器收到包含 .proto 模式中未定义的字段编号的 protobuf 消息，通常是由于客户端和服务器之间的版本不匹配。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| protobuf 25.3 | active | — | — |
| grpc-go 1.62.0 | active | — | — |
| grpc-java 1.60.0 | active | — | — |
| buf 1.28.0 | active | — | — |

## 解决方案

1. ```
   Synchronize the .proto files between client and server. Run:
  buf breaking --against .git
  to detect breaking changes. Regenerate code for both sides:
  protoc --go_out=. --go-grpc_out=. *.proto
  Or use Buf to manage versioning:
  buf generate --template buf.gen.yaml
   ```
2. ```
   If the unknown field is intentional (e.g., forward compatibility), use protojson or custom parsing to explicitly handle unknown fields. In gRPC-Go, set:
  import "google.golang.org/protobuf/encoding/protojson"
  opts := protojson.MarshalOptions{AllowPartial: true}
  But prefer updating the schema to include the field.
   ```

## 无效尝试

- **** — This hides the symptom but does not fix the root cause; data loss may occur if important fields are ignored. (70% 失败率)
- **** — Unknown field handling is a proto3 feature; older versions may still reject or silently drop fields, leading to data corruption. (85% 失败率)