Unity 使用 Protobuf（Pb2）二进制数据全流程工具详解

前言

在Unity游戏开发中，高效、快速、安全地读取配置数据是一项重要需求。本文介绍一种完整的解决方案——使用Protobuf二进制格式（Pb2）存储和读取游戏数据，并详细分享实现全流程的Unity工具。

一、技术流程概览

实现Unity读取Pb2二进制数据的流程如下：

1. Excel设计数据表
2. Excel转Proto文件
3. Proto文件转C#类
4. Excel数据序列化为Pb2二进制文件
5. Unity中加载Pb2数据文件

二、具体实现步骤

1. Excel设计数据表

数据表应遵循特定的格式规范：

• 第一行：字段注释
• 第二行：字段名（英文变量名）
• 第三行：字段数据类型（例如int32、string）
• 第四行及以下：数据内容

2. Excel转Proto文件

使用自定义编辑器工具自动将Excel表转换为.proto文件。

关键代码：ProtoGenerator.cs

private void GenerateProtoFile(){FileInfo fileInfo = new FileInfo(excelFilePath);if (!fileInfo.Exists){Debug.LogError("Excel 文件不存在: " + excelFilePath);return;}// 确保输出目录存在if (!Directory.Exists(outputFolder)){Directory.CreateDirectory(outputFolder);}// 定义 .proto 文件头部信息string protoContent = "syntax = \"proto3\";\n";protoContent += "package GameDataProto;\n\n";using (ExcelPackage package = new ExcelPackage(fileInfo)){// 遍历所有工作表，每个工作表生成一个 messageforeach (ExcelWorksheet worksheet in package.Workbook.Worksheets){string messageName = worksheet.Name;protoContent += $"message {messageName} {{\n";// 假定第一行为注释，第二行为变量名，第三行为类型int colCount = worksheet.Dimension.Columns;int fieldIndex = 1;for (int col = 1; col <= colCount; col++){object commentObj = worksheet.Cells[1, col].Value;object variableNameObj = worksheet.Cells[2, col].Value;object typeObj = worksheet.Cells[3, col].Value;if (variableNameObj == null || typeObj == null)continue;string comment = commentObj != null ? commentObj.ToString().Trim() : "";string variableName = variableNameObj.ToString().Trim();string type = typeObj.ToString().Trim();if (!string.IsNullOrEmpty(comment)){protoContent += $"    // {comment}\n";}protoContent += $"    {type} {variableName} = {fieldIndex};\n";fieldIndex++;}protoContent += "}\n\n";}}string protoFilePath = Path.Combine(outputFolder, "GameDataProto.proto");Editor.EditorHelper.WriteAllText(protoFilePath, protoContent);Debug.Log($"生成 .proto 文件: {protoFilePath}");}

• 通过Unity Editor菜单打开窗口，选择Excel文件与输出目录，自动生成.proto文件。

3. Proto文件转C#类

根据生成的.proto文件，自动生成对应的C#数据类。

关键代码：ProtoToCSharpGenerator.cs

• 自动解析proto协议，生成继承自DataInfo的数据类与继承自BaseGameData的容器类GameData。

[ProtoBuf.ProtoContract]public class DataInfo{[ProtoBuf.ProtoIgnore]public int id;}public class BaseGameData{/// <summary>/// 使用反射将加载到的表格数据存储到当前 GameData 实例中。/// 例如，加载到的 List<CharacterInfo> 会赋值给属性名为 CharacterInfo 的属性，/// 要求属性类型必须为 List<T>，T 与传入数据类型一致。/// </summary>/// <typeparam name="T">表格数据的元素类型</typeparam>/// <param name="tableData">加载到的表格数据列表</param>public void SetTableData<T>(List<T> tableData){// 查找当前实例中类型为 List<T> 的公共属性var property = this.GetType().GetProperties(BindingFlags.Public | BindingFlags.Instance).FirstOrDefault(p => p.PropertyType == typeof(List<T>));if (property != null){property.SetValue(this, tableData);Debug.Log($"成功将 {typeof(T).Name} 数据加载到 {this.GetType().Name} 中。");}else{Debug.LogError($"在 {this.GetType().Name} 中未找到类型为 List<{typeof(T).Name}> 的属性。");}}public T GetDataByID<T>(int id) where T : DataInfo{var containerType = GetType();// 改为搜索公共字段，而非属性var field = containerType.GetFields(BindingFlags.Public | BindingFlags.Instance).FirstOrDefault(f => f.FieldType == typeof(List<T>));if (field != null){var list = field.GetValue(this) as List<T>;if (list != null){return list.FirstOrDefault(item => item.id == id);}}return default(T);}}

 // 固定使用的命名空间string packageName = "Reacool.Core.DataTable";List<string> messageNames = new List<string>();string[] lines = Reacool.Editor.EditorHelper.ReadAllLines(protoFilePath);bool isMessage = false;bool isEnum = false;StringBuilder sb = new StringBuilder();// 文件头注释和 using 声明sb.AppendLine("// 通过 .proto 文件自动生成的 C# 文件，请勿手动修改");sb.AppendLine("using System.Collections.Generic;");sb.AppendLine();// 开始生成代码，强制命名空间为 Reacool.Core.DataTablesb.AppendLine($"namespace {packageName}");sb.AppendLine("{");// 解析 .proto 文件内容for (int i = 0; i < lines.Length; i++){string line = lines[i].Trim();// 忽略 package 声明（固定命名空间）if (line.StartsWith("package")){continue;}else if (line.StartsWith("//")){sb.AppendLine("    " + line);}else if (line.StartsWith("message")){isMessage = true;var match = Regex.Match(line, @"message\s+(\w+)");if (match.Success){string messageName = match.Groups[1].Value;if (!messageNames.Contains(messageName))messageNames.Add(messageName);// 表格类继承 DataInfosb.AppendLine("    [ProtoBuf.ProtoContract]");sb.AppendLine($"    public class {messageName} : DataInfo");sb.AppendLine("    {");// 在每个 message 里，自动插入 idProxy 属性，替代基类 id 做序列化sb.AppendLine("        [ProtoBuf.ProtoMember(1)]");sb.AppendLine("        public int idProxy");sb.AppendLine("        {");sb.AppendLine("            get => base.id;");sb.AppendLine("            set => base.id = value;");sb.AppendLine("        }");}}else if (line.StartsWith("enum")){isEnum = true;var match = Regex.Match(line, @"enum\s+(\w+)");if (match.Success){string enumName = match.Groups[1].Value;sb.AppendLine("    public enum " + enumName);sb.AppendLine("    {");}}else if (line.StartsWith("}")){if (isMessage || isEnum){sb.AppendLine("    }");isMessage = false;isEnum = false;}}else if (string.IsNullOrEmpty(line)){sb.AppendLine();}else if (isMessage){// 解析 message 内字段，如 "repeated type name = id;"var fieldMatch = Regex.Match(line, @"(repeated\s+)?(\w+)\s+(\w+)\s*=\s*(\d+);");if (fieldMatch.Success){bool isArray = !string.IsNullOrEmpty(fieldMatch.Groups[1].Value);string fieldType = fieldMatch.Groups[2].Value;string fieldName = fieldMatch.Groups[3].Value;int fieldId = int.Parse(fieldMatch.Groups[4].Value);// 跳过 id 属性，因为我们已经用 idProxy 代替if (fieldName.Equals("id", System.StringComparison.OrdinalIgnoreCase)){continue;}// 简单转换 Protobuf 基本类型为 C# 类型if (fieldType == "int32") fieldType = "int";else if (fieldType == "int64") fieldType = "long";sb.AppendLine($"        [ProtoBuf.ProtoMember({fieldId})]");sb.AppendLine($"        public {fieldType}{(isArray ? "[]" : "")} {fieldName};");}}else if (isEnum){sb.AppendLine("        " + line.Replace(';', ','));}

4. Excel数据序列化为Pb2二进制文件

使用工具将Excel表中数据自动序列化为Protobuf二进制格式。

关键代码：ProtobufBytesGenerator.cs

• 自动读取Excel文件，解析工作表，并序列化为Pb2格式，存储成.bytes文件。

FileInfo excelFile = new FileInfo(excelFilePath);using (ExcelPackage package = new ExcelPackage(excelFile)){// 通过反射获取 GameData 类型的所有公共实例字段Type gameDataType = typeof(T);FieldInfo[] fields = gameDataType.GetFields(BindingFlags.Public | BindingFlags.Instance);foreach (FieldInfo field in fields){// 仅处理 List<T> 类型的字段if (field.FieldType.IsGenericType &&field.FieldType.GetGenericTypeDefinition() == typeof(List<>)){Type elementType = field.FieldType.GetGenericArguments()[0];// 约定工作表名称与元素类型名称相同（如 CharacterInfo、AudioInfo 等）string sheetName = elementType.Name;var worksheet = package.Workbook.Worksheets[sheetName];if (worksheet == null){Debug.LogWarning("未找到工作表：" + sheetName + "，跳过。");continue;}// 调用通用解析方法 ParseSheet<T> 将工作表数据转为 List<T>MethodInfo method = typeof(BinaryGenerator).GetMethod("ParseSheet", BindingFlags.NonPublic | BindingFlags.Static);MethodInfo genericMethod = method.MakeGenericMethod(elementType);object listObj = genericMethod.Invoke(null, new object[] { worksheet });// 输出文件路径：以工作表名称命名的二进制文件（例如 CharacterInfo.bytes）string outputFilePath = Path.Combine(outputFolder, sheetName + ".bytes");using (FileStream fs = new FileStream(outputFilePath, FileMode.Create)){Serializer.Serialize(fs, listObj);}Debug.Log("生成二进制文件成功：" + outputFilePath);}}}

5. Unity中加载Pb2数据文件

通过DataTableManager读取Pb2二进制文件并反序列化。

关键代码：DataTableManager.cs、BaseGameData.cs

• 使用泛型反射动态加载二进制数据，存入BaseGameData对象中，统一管理。

 /// <summary>/// 保存二进制数据/// </summary>/// <param name="fileData"></param>/// <typeparam name="T"></typeparam>public void ProcessByteData<T,T2>(byte[] fileData)where T : DataInfo where T2 : BaseGameData{if (fileData == null || fileData.Length == 0){Debug.LogError("传入的数据为空！");return;}// 根据类型名称生成对应的字段名：例如 "CharacterInfo" -> "characterInfos"string typeName = typeof(T).Name;string fieldName = char.ToLowerInvariant(typeName[0]) + typeName.Substring(1) + "s";// 利用反射获取全局 GameData 实例中对应的公共字段var field = typeof(T2).GetField(fieldName, System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Instance);if (field == null){Debug.LogWarning($"GameData 中未找到对应字段：{fieldName}");return;}// 检查该字段是否已经有数据加载，若有数据，则跳过加载var existingData = field.GetValue(this.GameData) as System.Collections.IList;if (existingData != null && existingData.Count > 0){Debug.Log($"{typeName} 数据已加载，跳过加载。");return;}// 反序列化传入的 bytes 数据List<T> listObj = null;try{using (var ms = new System.IO.MemoryStream(fileData)){listObj = ProtoBuf.Serializer.Deserialize<List<T>>(ms);}}catch (System.Exception ex){Debug.LogError($"解析 {typeName} 数据失败：{ex.Message}");return;}// 将解析后的数据存入 GameData 中对应的字段field.SetValue(this.GameData, listObj);Debug.Log($"成功加载 {typeName} 数据到 GameData.{fieldName}");}

三、关键代码解析

• Excel转二进制数据：使用EPPlus解析Excel文件，序列化数据为二进制格式。
• 数据反序列化：利用Protobuf库，将二进制数据反序列化为C#对象。
• 反射自动加载：利用C#反射特性，自动匹配数据字段和数据类型，简化数据加载过程。

四、总结

本文提供了一整套基于Unity引擎的Protobuf（Pb2）数据管理流程，从Excel设计、数据转换、代码生成到数据加载，自动化程度高且扩展性强。通过本文分享的工具与方法，开发者可以高效地实现Unity项目的数据管理。