Proto3 中字段默认可选、零值合法；syntax = "proto3" 必须严格首行无BOM/空格；go_package 路径须与 go.mod module 完全一致；字段编号不可复用，禁用 19000–19999；嵌套 message 必须定义在父 message 体内。
proto3 里不能写或，所有字段默认可选，零值合法 —— 这是 Go 中用 Protobuf 定义消息时最常踩的坑。
syntax = "proto3" 必须是文件首行，且不能有 BOM 或空格
protoc 会根据第一行判断语法版本。如果前面有 UTF-8 BOM、空行、注释或缩进，它就按 proto2 解析，导致生成的 Go 字段全是指针类型（比如
），后续做
判断或 JSON 序列化时行为异常，且不报错。
正确写法：
必须严格占首行，前后无空格、无注释
错误示例：
或
或带 BOM 的文件（VS Code 默认可能加）
验证方式：用
看是否以
开头（BOM）
go_package 路径必须和 go.mod module 名完全一致
不是“建议写”，而是 protoc 找包、Go 编译器找类型的唯一依据。路径错一点，
就报
或找不到包。
写法必须是完整导入路径，例如：
末尾不加
，也不写相对路径（如
）或空字符串
必须和
第一行
完全匹配；如果 module 是
，那
也得是
生成后立刻检查
头部的
是否符合预期；如果是
，基本就是
没写或写错了
字段编号不能复用，尤其要避开 19000–19999
Protobuf 序列化只认编号，不认字段名。编号冲突或复用，会导致反序列化时数据塞错字段，静默错乱 —— 不报错、不 panic，但业务逻辑崩了才发觉。
立即学习
“
go语言免费学习笔记（深入）
”；
同一
内编号绝不能重复，protoc 编译直接失败
删掉一个字段（如
），编号
就该废弃，不能再分配给新字段
禁止使用
–
段：protoc 不报错，但 Google 预留作内部扩展，运行时可能触发未知行为
建议从
开始连续编号（
），跳号太多（如
）容易在多人协作中误判“中间漏了啥”
嵌套 message 必须真定义在父 message 体内
嵌套不是靠命名约定（比如叫
）或点号语法（
）实现的，而是把子结构显式写在父结构大括号里。否则 protoc 报
，生成代码里根本找不到那个类型。
正确写法：
字段类型直接写
，不用加包名或前缀
不要试图用
引入外部
里的类型来“模拟嵌套”——那是复用，不是嵌套
嵌套类型的作用域仅限于父
，对外不可见；想跨 message 复用，得提成顶层
并
最容易被忽略的是编号复用和
路径一致性 —— 它们不出现在编译错误里，却会在运行时悄悄破坏数据或让 import 失败，排查成本远高于写的时候多看两眼。
requiredoptional*string== ""syntax = "proto3";// 注释 syntax = "proto3";xxd person.proto | head -n10000000go_packagego buildundefined: pb.Useroption go_package = "github.com/yourorg/yourrepo/pb";.pb./pbgo.modmodule github.com/yourorg/yourrepogithub.com/yourorg/yourrepo/v2go_packagegithub.com/yourorg/yourrepo/v2/pbuser.pb.gopackage pbpackage maingo_packagemessagestring deprecated_field = 3;3190001999911, 2, 3...1, 2, 5, 6User_AddressUser.Addressundefined symbolmessage User {
string name = 1;
message Address {
string city = 1;
string street = 2;
}
Address address = 2;
}Addressimport.protomessagemessageimportgo_package