UE4 C++解析Json数组：从基础类型到嵌套结构实战指南

做 UE4 开发的朋友，早晚都会碰到这么一件事：手里有一份 Json 数据，可能是服务器下发的活动列表，也可能是本地配表里的技能参数，你想用 C++ 把它读进来，把一个数组完整地解析出来——是对象数组还是字符串数组，结构是平的还是嵌套的，这些细节一不注意就翻车。我见过有人因为一个中文编码折腾一晚上，也见过把对象数组当成普通数组强转然后直接崩溃的。这篇文章就从 UE4 里 C++ 读取 Json、解析 Json 数组这件事讲起，把环境配置、读取姿势、三种不同难度的数组解析、可复用的封装置槽以及高频坑点全部过一遍，适合刚接触 Json 模块的新手，也适合想把手头解析代码写得更稳的朋友。

1. 这块需求到底在解决什么问题

1.1 哪些场景必须用 C++ 解析 Json

很多人在蓝图里用 “Json Object” 相关节点也能解析，但一旦数据量大、结构复杂、或者要嵌入到纯逻辑层（比如数据表加载、网络协议解析），蓝图那套就变得又慢又难维护。C++ 直接操作FJsonObject的好处是：它能进模块化代码，能放进异步线程，能方便地跟项目里的结构体、容器、存档逻辑打通。

具体来说，这几类场景基本绕不开 C++ 解析 Json 数组：

• 网络接口回包里的列表数据，比如排行榜、商品列表、任务列表；
• 本地配表/配置文件，比如武器参数数组、关卡配置数组；
• 存档系统里用 Json 记录多个存档槽或者多条行为数据；
• 从外部工具导出的批量数据，一次性导入工程。

标题里特别提到“解析 Json 数组”，是因为数组在实际数据里出现的频率比想象中高得多。一个 JSON 文件的根节点往往是对象，但对象里面装的数据，十有八九是数组。数组里面可能是字符串、数字、布尔值，也可能是对象，甚至对象里再嵌数组。不同形态解析方式完全不同，这也是这篇文章的展开主线。

1.2 解析 Json 数组的完整数据链路

要理解 UE4 里 Json 解析，先记住这一整条链路：

读取文件或拿到字符串 → 丢给TJsonReader→ 用FJsonSerializer反序列化成TSharedPtr<FJsonObject>→ 从对象里用GetArrayField或TryGetField拿出数组 → 遍历数组里的TSharedPtr<FJsonValue>→ 根据元素类型调用AsString/AsNumber/AsObject/AsArray取出真正数据。

很多人只会中间两步，拿到FJsonObject之后直接GetStringField一把梭，结果遇到数组就懵了。其实核心思想非常简单：FJsonObject是一个键值对容器，数组在它内部是“一个键对应一个TArray<TSharedPtr<FJsonValue>>”，而FJsonValue是各种类型的包装器。理解了这两层，剩下就是 API 熟练度的问题。

1.3 为什么官方的 Json 模块够用，不需要造轮子

UE4 内置的Json模块虽然名字朴素，但功能完全覆盖日常需求：能解析、能生成、支持嵌套、支持数组、支持各种基础类型。很多新手觉得“内置的不专业”，其实多虑了。游戏里常用的 Json 序列化场景，引擎这套 API 都撑得住。你真正要做的是把Json和JsonUtilities两个模块加到工程依赖里，然后熟悉那几个核心类。瞎折腾出第三方库纯属给自己找事，引擎版本一升级还要跟着踩坑。

2. 动手前先把环境配好：模块与头文件

2.1 Build.cs 里加依赖

这一步虽然简单，但错过的人不在少数。在项目的.Build.cs文件里，把Json和JsonUtilities补进依赖列表：

PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "Json", "JsonUtilities" });

Json模块提供FJsonObject、FJsonValue、FJsonSerializer这一整套解析核心；JsonUtilities额外提供FJsonObjectConverter，常用于 UStruct 和 Json 互转。如果你手写解析为主，Json是必需的，JsonUtilities属于“加上保险”的类型。不加模块直接 include 头文件，编译期会报出一堆“找不到 XXX.h” 的错误，这种问题排查起来很烦，所以先把这个搞定。

2.2 必须认识的三组核心类

第一组是FJsonObject和FJsonValue。前者是键值对容器，代表一个 JSON 对象；后者是所有 JSON 值的包装基类。数组里的每个元素，即使是个普通字符串，也会被包装成FJsonValue存到数组里。

第二组是FJsonSerializer和TJsonReader<TCHAR>。FJsonSerializer是“翻译官”，负责把文本字符串翻译成FJsonObject对象；TJsonReader负责逐字逐句读入字符串，过程中如果语法错误，它会记录错误信息。

第三组是TJsonWriter<TCHAR>。这是把FJsonObject写成字符串的工具，虽然标题只说了“读取”，但实际项目里读写往往是一对，后面我会把小封装一并给出来。

这几类都通过TSharedPtr管理生命周期，不要想着手动 delete。理解这点很重要，因为后面所有操作几乎都离不开TSharedPtr和.IsValid()判断。

2.3 FString、TSharedPtr 和 UE_LOG 的配合

先说FString。从文件读出来的 Json 文本是FString，从网络回调拿到的响应体通常也是FString。FJsonSerializer接受的是FString，所以路径天然通顺。但注意，FString和标准库std::string不是一个东西，别混用。跨平台代码里经常有人把std::string和FString乱赋值，编译时各种崩溃，还找不到原因。

TSharedPtr<FJsonObject>在反序列化失败时可能是一个空指针，所以每次解析完第一件事就是IsValid()判断。这个习惯会帮你躲开一半的崩溃问题。

调试时的关键工具是UE_LOG。它可以直接打印FString，配合*JsonString解引用输出内容。很多解析问题其实不是 API 写错，而是数据格式和预期不一致，打日志是最快的排查方式。

3. 拿到 Json 字符串的四种常见姿势

3.1 从项目文件读取（最常用）

本地配置类 Json 一般放在Content目录下。用FPaths::ProjectContentDir()拼接文件路径，再通过FFileHelper::LoadFileToString读出来：

FString FilePath = FPaths::ProjectContentDir() + TEXT("Data/config.json"); FString JsonString; if (!FFileHelper::LoadFileToString(JsonString, *FilePath)) { UE_LOG(LogTemp, Error, TEXT("读取Json文件失败: %s"), *FilePath); return; }

这里有个容易看漏的点：LoadFileToString的第一个参数是FString&，第二个参数是const TCHAR*，所以文件路径要加*解引用。很多同学写的是FilePath而不是*FilePath，编译报错后一脸茫然。

如果文件不在Content下，而是在项目根目录、Saved 目录或者绝对路径，只要把FilePath换成你实际的位置即可，读取代码不用改。唯一要注意的是打包后目录结构可能变化，正式项目建议把路径抽象封装一下，不要到处硬编码。

3.2 从绝对路径或存档目录读取

如果是存档类数据，路径一般是FPaths::ProjectSavedDir()。这个目录在编辑器运行和打包后的位置不一样，但引擎帮我们做了统一。比如：

FString SavePath = FPaths::ProjectSavedDir() + TEXT("Save/slot_data.json"); FString JsonString; FFileHelper::LoadFileToString(JsonString, *SavePath);

存档场景下还有一个常见需求：读取失败时不直接报错，而是走默认数据初始化。所以最好把“读取 + 解析 + 回退默认值”包在一起，逻辑更干净。

3.3 从网络回调或命令行参数读取

如果你用的FHttpModule，在响应回调里会拿到一个FHttpResponsePtr，此时直接：

FString ResponseString = Response->GetContentAsString();

后面的解析逻辑和从文件读取完全一样。也就是说，整条 Json 解析链路和“数据来源”解耦，文件、内存、网络最终都汇合到同一个FJsonSerializer::Deserialize这一步。这也解释了为什么我们前面要花时间搞懂那三组核心类，因为它们是所有场景的公因数。

从命令行参数读取的场景比较少见，但某些工具类项目会用，比如测试程序里FParse::Value把-JsonData=xxx参数取出来，再把字符串交给解析器。这类场景务必注意参数里的特殊字符转义问题，命令行里的引号和反斜杠经常把 Json 搞成非法格式。

3.4 编码问题别等到跑起来才后悔

很多中文乱码问题都出在编码上。FFileHelper::LoadFileToString默认会尝试自动检测编码，但无 BOM 的 UTF-8 文件有时候会被识别成别的编码，导致中文全部变成乱码。

我的建议是：

• 手动维护的 Json 文件，统一保存为“UTF-8 with BOM”，解析最稳；
• 如果拿到的是无 BOM 的 UTF-8 文件，且出现中文乱码，优先尝试用FUTF8ToTCHAR手动转码，而不是在原字符串上硬碰；
• 服务器下发数据时，确认服务端输出的是标准 UTF-8，否则客户端解析必然踩坑。

关于网络响应字符串，GetContentAsString()一般按 UTF-8 处理，但如果服务端响应头里的charset写错，也可能出现乱码。这类问题一旦碰到，直接把响应字节打到日志里看十六进制，是定位是 UTF-8 还是 ANSI 的最快手段。

4. 解析 Json 数组：三个难度的递进实练

4.1 平民版：数组里全是基础类型

假设数据长这样：

{ "tags": ["rpg", "action", "puzzle"] }

这是一个最普通的字符串数组。解析步骤分为两段：先拿到整个对象，再取tags字段：

#include "Json.h" #include "Misc/FileHelper.h" TSharedPtr<FJsonObject> JsonObject; TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(JsonString); if (FJsonSerializer::Deserialize(Reader, JsonObject) && JsonObject.IsValid()) { const TArray<TSharedPtr<FJsonValue>>& Tags = JsonObject->GetArrayField(TEXT("tags")); for (const TSharedPtr<FJsonValue>& Tag : Tags) { FString TagName = Tag->AsString(); UE_LOG(LogTemp, Log, TEXT("Tag: %s"), *TagName); } }

注意两点：第一，GetArrayField返回的是const TArray<TSharedPtr<FJsonValue>>&，它内部持有的是引用或副本，这个细节不纠结也行，用const引用接收就好；第二，数组里每个元素调用AsString()之前，要确认它确实是字符串。如果 Json 里写的是数字 123，AsString()可能返回空字符串或者导致断言失败——这个坑在后面的排查表里会重点说。

整数数组、布尔数组逻辑完全一样，只是把AsString()换成AsNumber()或AsBool()。注意AsNumber()返回的是double，转int32时自己做好取舍。

4.2 日常版：数组里全是对象

这应该是实际项目里最常见的形态。比如服务器返回一批物品数据：

{ "items": [ { "name": "木头", "count": 12, "price": 3.5, "enabled": true }, { "name": "石头", "count": 30, "price": 1.2, "enabled": false } ] }

解析时遍历数组，对每个元素先调用AsObject()得到TSharedPtr<FJsonObject>，再从这个子对象里取字段：

const TArray<TSharedPtr<FJsonValue>>& Items = JsonObject->GetArrayField(TEXT("items")); for (const TSharedPtr<FJsonValue>& Item : Items) { const TSharedPtr<FJsonObject>& ItemObj = Item->AsObject(); if (!ItemObj.IsValid()) { UE_LOG(LogTemp, Warning, TEXT("数组元素不是有效对象，已跳过")); continue; } FString Name = ItemObj->GetStringField(TEXT("name")); int32 Count = ItemObj->GetIntegerField(TEXT("count")); float Price = ItemObj->GetNumberField(TEXT("price")); bool Enabled = ItemObj->GetBoolField(TEXT("enabled")); UE_LOG(LogTemp, Log, TEXT("物品: %s, 数量: %d, 价格: %.2f, 上架: %d"), *Name, Count, Price, Enabled); }

这段代码里最重要的习惯是IsValid()判断。一个 Json 数组里混入了非对象元素（比如数字或null），AsObject()会返回空指针，不判断就直接解引用，游戏瞬间崩溃。

第二个细节是GetIntegerField和GetNumberField的区别。count在 Json 里写成12，用GetNumberField得到的是12.0，类型是 double，隐式转 int32 没问题；但如果price用GetIntegerField去取，1.2 会被截成 1，精度直接丢了。所以我的习惯是：整数用GetIntegerField，浮点一律用GetNumberField，不要图省事混用。

第三个细节是字段缺失问题。如果某条物品没有price字段，GetNumberField会返回 0.0，你可能没察觉就带上错误数据了。正确做法是先用HasField判断，或者用TryGetField拿到FJsonValue*再判断类型：

if (ItemObj->HasField(TEXT("price"))) { Price = ItemObj->GetNumberField(TEXT("price")); }

4.3 硬核版：对象套对象、数组套数组

项目稍微复杂一点，就是章节、任务、配置这种多级结构。比如：

{ "content": [ { "id": 101, "title": "第一章", "sections": [ { "type": "text", "body": "你好" }, { "type": "image", "url": "/tex/hello.png" } ] } ] }

这种结构用循环嵌套就能解，但代码容易越写越长。我自己习惯单独写一个递归遍历函数，或者至少把“取对象数组”这个动作抽成一个工具函数，不然每层都要写一遍GetArrayField + AsObject + IsValid，又啰嗦又容易漏判断。

内层数组解析示例：

const TArray<TSharedPtr<FJsonValue>>& ContentList = JsonObject->GetArrayField(TEXT("content")); for (const TSharedPtr<FJsonValue>& ContentItem : ContentList) { const TSharedPtr<FJsonObject>& ContentObj = ContentItem->AsObject(); if (!ContentObj.IsValid()) { continue; } int32 Id = ContentObj->GetIntegerField(TEXT("id")); FString Title = ContentObj->GetStringField(TEXT("title")); const TArray<TSharedPtr<FJsonValue>>& Sections = ContentObj->GetArrayField(TEXT("sections")); for (const TSharedPtr<FJsonValue>& SectionValue : Sections) { const TSharedPtr<FJsonObject>& SectionObj = SectionValue->AsObject(); if (!SectionObj.IsValid()) { continue; } FString Type = SectionObj->GetStringField(TEXT("type")); if (Type == TEXT("text")) { FString Body = SectionObj->GetStringField(TEXT("body")); // 处理文本段落 } else if (Type == TEXT("image")) { FString Url = SectionObj->GetStringField(TEXT("url")); // 处理图片段落 } } }

嵌套解析核心是“先拆对象，再拆数组，再拆对象”这个循环。你只要记住：数组元素 -> AsObject() -> 对象; 对象字段 -> GetArrayField -> 数组，层层递推，再复杂的数据也能解出来。写的时候给自己定一条规矩：每个AsObject()后面必须跟着IsValid()判断，哪怕你觉得当前数据绝对不会有错——因为数据源不受你控制，服务器改个字段、策划配错一个值，崩溃或异常就在一瞬间。

4.4 一个小技巧：先打印结构再写代码

我在处理不熟悉的 Json 文件时，从来不直接写正式解析代码。第一步永远是读取字符串，然后一行UE_LOG把原始 Json 打出来，配合格式化工具看清楚层级关系。这一步能避免很多“想当然写错字段名”的低级错误。

如果 Json 很大，打日志会很长，可以只打印前几百个字符，或者把 Json 片段复制到本地文件里查看。UE 的日志窗口支持多行折叠，但太长的内容还是会影响阅读。个人习惯：准备一个临时函数，递归打印整个 JsonObject 的键名和值类型。这个工具我用了很久，排查效率翻倍。

5. 复用价值：把解析逻辑封装成 JsonHelper

5.1 为什么建议封装而不是到处拷贝

项目初期大家拿到 Json 都是到处写Deserialize加GetArrayField，三个月后项目里可能有二十处解析代码，每一处处理边界条件的方式都不同，有的判空了有的没判，改起需求来简直是灾难。更现实的问题是，如果引擎版本升级导致某个 API 弃用，你需要在二十个地方改同样的调用。

与其这样，不如写一个轻量级JsonHelper，把高频操作收敛成几个工具函数。团队其他人接到类似需求时直接调用，哪怕不会深入引擎 Json API 也能快速落地。

5.2 两个高频工具函数直接抄作业

第一个是“带默认值的安全取字符串字段”：

FString GetFieldStringOrDefault(const TSharedPtr<FJsonObject>& InObject, const FString& FieldName, const FString& DefaultValue) { if (!InObject.IsValid() || !InObject->HasField(FieldName)) { return DefaultValue; } return InObject->GetStringField(FieldName); }

第二个是“取对象数组”：

TArray<TSharedPtr<FJsonObject>> GetObjectArray(const TSharedPtr<FJsonObject>& InObject, const FString& FieldName) { TArray<TSharedPtr<FJsonObject>> Result; if (!InObject.IsValid() || !InObject->HasField(FieldName)) { return Result; } const TArray<TSharedPtr<FJsonValue>>& ValueArray = InObject->GetArrayField(FieldName); for (const TSharedPtr<FJsonValue>& Value : ValueArray) { const TSharedPtr<FJsonObject>& ObjectValue = Value->AsObject(); if (ObjectValue.IsValid()) { Result.Add(ObjectValue); } else { UE_LOG(LogTemp, Warning, TEXT("Json数组元素 %s 中，数组字段 %s 存在非对象元素，已跳过"), *GetFieldStringOrDefault(InObject, TEXT("name"), TEXT("未知")), *FieldName); } } return Result; }

这个封装的核心价值是“内部处理好空指针和类型错误”，业务代码永远不需要再判断AsObject()返回是否有效。它让解析代码从十行变成一行：

TArray<TSharedPtr<FJsonObject>> Items = JsonHelper::GetObjectArray(JsonObject, TEXT("items")); for (const auto& Item : Items) { FString Name = JsonHelper::GetFieldStringOrDefault(Item, TEXT("name"), TEXT("")); }

5.3 封装 Json 写回，解析和生成配套

读取之外，实际项目里经常还需要把结构体写回 Json 存档。核心只有四步：

TSharedPtr<FJsonObject> RootObject = MakeShareable(new FJsonObject()); TArray<TSharedPtr<FJsonValue>> ItemArray; TSharedPtr<FJsonObject> ItemObject = MakeShareable(new FJsonObject); ItemObject->SetStringField(TEXT("name"), TEXT("木头")); ItemObject->SetIntegerField(TEXT("count"), 12); ItemArray.Add(MakeShareable(new FJsonValueObject(ItemObject))); RootObject->SetArrayField(TEXT("items"), ItemArray); FString OutputString; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&OutputString); FJsonSerializer::Serialize(RootObject.ToSharedRef(), Writer); FFileHelper::SaveStringToFile(OutputString, *FilePath);

注意SetArrayField接受的参数是const TArray<TSharedPtr<FJsonValue>>&，所以每个对象要先用MakeShareable(new FJsonValueObject(...))包装成FJsonValue再放进数组。这一套如果也封装进JsonHelper，以后生成配置、写存档都能复用同一套模板。

6. 实战问题快查表：从解析失败到中文乱码

6.1 五个高频问题与排查思路

这里的核心排查思路是“先确认数据是什么，再怀疑代码写错”。很多新手把代码改来改去，最后才发现 Json 文件里字段名多了一个空格。建议所有拿到手的 Json 文本先原样打印一次，用眼睛确认格式无误再进入解析。

Reader->GetErrorMessage()是经常被忽略的好帮手。反序列化失败时，它能给出具体是哪一行、哪个位置出了问题，远比“Deserialize 返回 false”这种信息有用。我见过太多人卡在解析失败上，却没人去看这个错误消息。

6.2 UE_LOG 输出 Json 的几个注意点

打印 Json 字符串时，UE_LOG的格式化参数用%s，变量要加*：

UE_LOG(LogTemp, Log, TEXT("Json内容: %s"), *JsonString);

如果 Json 里含有特殊字符，比如换行和引号，日志窗口会显示得比较乱。这时候不要慌，这是正常现象。可以把 Json 写到临时文件再查看，或者只打印关键字段而不是整段字符串。

还有一点容易被忽略：UE_LOG 对超长文本的显示可能被截断。调试大数据时，与其打一长串 Json，不如循环打印数组里的每个元素字段。这样日志既短又有针对性。

6.3 用第三方工具生成测试数据的小建议

平时开发建议手边常备一个 Json 格式化工具。我自己的习惯是：先在编辑器里用插件格式化一遍，确认结构无误后，再复制到 UE 工程里测试。格式化工具还会高亮显示括号不匹配、尾逗号等问题，基本上能排除掉一半的解析失败原因。

如果你要构造测试数据，也建议先从少量数据开始。三五个元素的数组能跑通后，再压上几百条记录测性能。很多性能问题不是解析 API 本身造成的，而是你没意识到“每次 GetArrayField 都会复制一份数组”—用引用接收能省下不少不必要开销。

谈到性能，还有个大原则：大批量 Json 解析别放游戏主线程。比如存档读取、排行榜拉取，这些动辄几十毫秒的操作放进AsyncTask或单独线程，解析完成后再切回游戏线程使用数据，体感会好很多。解析本身是纯内存操作，线程安全上注意不要同时读写同一个FJsonObject就行。

最后再分享一个我个人的习惯：拿到一份要解析的 Json，先不着急写大逻辑，而是先写一个 20 行不到的“探查小工具”，打印出整个结构树：哪个字段是数组、数组里每个元素是什么类型、有没有空值。看清楚之后再动正式代码，出错率至少降一半。这套方法我用在很多项目上，效果一直很稳定，也希望你能用得上。