Unity 使用 Protobuf（Pb2）二進制數據全流程工具詳解

前言

在Unity游戲開發中，高效、快速、安全地讀取配置數據是一項重要需求。本文介紹一種完整的解決方案——使用Protobuf二進制格式（Pb2）存儲和讀取游戲數據，并詳細分享實現全流程的Unity工具。

一、技術流程概覽

實現Unity讀取Pb2二進制數據的流程如下：

Excel設計數據表
Excel轉Proto文件
Proto文件轉C#類
Excel數據序列化為Pb2二進制文件
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}");}