UE5 C++字符串与容器全解析：FString、FName、FText与TArray、TMap底层原理

做 UE5 C++ 开发，容器和字符串这两块绕不过去。项目做大了，每次新建一个类、存一份配置、调一次接口，都要跟它们打交道。我最早是从 std 那套东西切过来的，一开始真被 UE 的命名搞晕过——明明都是字符串，为什么有 FString、FName、FText 三个？容器也是，TArray 看着像 vector，实际用起来却多了不少脾气；TMap 的键值对到底存了个什么东西，内部继承链是怎么走的，查过源码才彻底明白。这篇就把这三个系列的用法和底层逻辑一次性讲透。

1. FString、FName、FText：三种字符串不是让你随便选的

很多新手第一个困惑就是：UE5 里字符串怎么这么多？我早期也图省事，到处用 FString，编译能过，跑起来也没报错，但项目一上规模问题就来了——内存疯涨、查找变慢、本地化文本全部失效。后来认真捋了一遍，这三种类型压根是给不同场景准备的。

1.1 FString：负责“加工”，是真正的动态字符串

FString 本质就是一个 TArray 包装的 ANSI 或 UTF-16 字符缓冲区，支持拼接、替换、查找、切割、格式化，几乎所有需要运行时“处理字符串内容”的操作都靠它。它会在堆上动态分配内存，字符串越长、操作越多，分配和拷贝的开销就越大。

在蓝图里看到的所有白底字符串引脚，绝大多数都是 FString 或下面要说的 FText，而 C++ 里接受字符串参数的接口，也常常是 FString。比如从文件读配置、解析 JSON、拼一个日志输出，这些场景非它不可。

FString RawData = TEXT("name=zhangsan;level=99"); FString LeftPart, RightPart; if (RawData.Split(TEXT(";"), &LeftPart, &RightPart)) { UE_LOG(LogTemp, Log, TEXT("key part: %s"), *LeftPart); }

注意*LeftPart这个取地址符不能省，UE_LOG 的%s需要的是 TCHAR*，不是 FString 对象本身。这是最容易被绊倒的地方，后面细说。

1.2 FName：负责“标识”，查得快、占得少

FName 的设计目标就是“轻量标识符”。它内部是一个不区分大小写的哈希索引，指向一张全局字符串表。同一个字符串在程序里出现一千次，实际内容只存一份，每个 FName 只保存一个静态索引和几个比较用的附加位。所以 FName 的拷贝、比较、哈希都极快，几乎是常数时间。

但 FName 有两个致命限制：一是不建议在运行时拼字符串改内容，虽然技术上允许，但会产生表项泄漏式的累积，而且设计哲学上就不该这么干；二是它不区分大小写，做用户输入、密文、路径判别时要特别小心。适合它的场景是：Actor 的 Tag、Socket 名称、动画曲线名、资产行名、状态枚举名——这些字符串生命周期长、重复率高、主要靠“相等判断”来用。

蓝图里选中很多节点时弹出的搜索框、引擎内部各种名字表，基本都是 FName。

1.3 FText：负责“展示”，为本地化而生

FText 要解决的是“给玩家看什么”。它内部会被标记为“已本地化”，并且可以携带源语言文本和命名空间。运行时从文本表里根据当前语言重新查找对应翻译。最典型的创建方式是NSLOCTEXT或LOCTEXT宏，蓝图里文本引脚默认就是 FText。

注意，FText 不能直接拼变量。C++ 里拼本地化文本要用FText::Format，配合FText::FromString把动态内容转进去。这个限制绕不开，否则本地化校验会出问题。

举例来说，模拟项目X里我们要做一个弹窗提示：“玩家 xxx 获得了 xx 金币”。如果用 FString 直接拼，翻译工具扫描时根本拿不到“玩家{0}获得了{1}金币”这个模板，本地化就废了。正确做法是：

FText PlayerName = FText::FromString(SomeNameString); FText CoinText = FText::FromString(FString::FromInt(CoinCount)); FText Message = FText::Format( LOCTEXT("CoinReward", "Player {0} got {1} coins."), PlayerName, CoinText );

1.4 三者的转换代价和使用边界

转换不是免费的。FString 转 FName 要查一次全局表，转 FText 要做一次本地化评估。反过来，FName 转 FString 可以拿到真实字符，FText 转 FString 则会丢失本地化信息。开发阶段偶尔转换没问题，但不要在热路径或每帧调用里反复转。

我在实际项目里总结了一条铁律：给玩家看的走 FText，给人做标识的走 FName，给机器做处理的走 FString。这条规则哪怕不理解细节，先照着用，也能少踩百分之八十的坑。

2. TArray：看着像 std::vector，底子和脾气都不太一样

TArray 是 UE 项目里用得最多的容器，接口和 std::vector 相似度极高，push_back 对应 Add，size 对应 Num，[] 运算符都在。但如果你真把它当 vector 用，迟早会踩到几种奇特的坑。

2.1 内存模型：不是散落节点的链表，是一整块可增长堆内存

TArray 之所以“快”，就是因为它把元素存在一块连续内存里，迭代时缓存命中率高，随机访问是 O(1)。它内部有三个核心字段：指向堆内存的指针（Data）、元素个数（ArrayNum）、最大容量（ArrayMax）。

Add 一个新元素时，如果容量不够，它会按一定规则申请更大内存、把旧元素移过去、释放旧内存。这个过程和 vector 的扩容逻辑没有本质区别，都是摊还 O(1)。

但 UE 对“移动”这件事要求更严格。如果你的元素类型没有定义移动构造函数，扩容时会做深拷贝，那代价就大了。因此自定义结构体放进 TArray 之前，最好实现移动构造和移动赋值，或者至少确保里面嵌套的都是可高效移动的容器。

2.2 元素类型：到底能不能放不完整类型和引用

TArray 里的元素必须是“完整类型”，不能放引用，因为引用不是 object，不能作为容器元素。这个和 std::vector 一样。但 TArray 可以放 TArray、TMap、TSharedPtr、TWeakObjectPtr、UClass* 这类引擎类型，只要它们是可拷贝/可移动的。

还有一点和 vector 很不一样：TArray 允许元素是const成员吗？不行。任何const TArray<const int32>这种写法都不建议，等于自己把自己锁死。老老实实用const TArray<int32>&这种引用传递方式。

2.3 常用的查找和删除：Remove、RemoveAt、RemoveSwap 的区别

这是 TArray 比 vector 多出来的实用接口，也是新手比较容易搞混的：

• Remove(Elem)：把与 Elem 相等的所有元素移除，并保持剩余元素相对顺序。
• RemoveAt(Index)：移除指定索引的元素，后续元素向前挪。
• RemoveAtSwap(Index)：先把这个位置用最后一个元素补上，再缩短数组。速度快，但顺序会变。

如果你的数组不需要保持顺序，尽量用RemoveAtSwap，它才是真正的 O(1) 操作。RemoveAt涉及大量元素移动，O(n) 级别。

TArray<int32> Values = {1, 2, 3, 4, 5, 2}; Values.Remove(2); // {1, 3, 4, 5}，所有 2 都被移除 Values.RemoveAtSwap(0); // {5, 3, 4}，最后一个元素补到 0 位置

另外，Find系列返回的是指针而不是索引。如果你只是判断存在，用Contains；需要拿位置修改，用IndexOfByKey或直接Find拿指针改。

2.4 Empty、Reset、Shrink 是三个完全不同的行为

很多人以为 Empty 和 Reset 差不多，其实差远了：

• Empty()：释放所有元素内存，数组回到空状态，容量也可能变成 0。
• Reset()：保留容量，只把元素析构，后续 Add 不用重新分配。
• Shrink()：把容量缩到和元素数一样，释放多余内存。

在循环里反复创建的临时数组，优先用Reset()复用容量，能省下大量分配操作。我做过一次简单计时，同样一万次循环往 TArray 里 Add 固定数量的 int32，用 Empty 的方式比用 Reset 慢了三倍以上，原因就是 Empty 每次都要重新走一遍内存分配。

2.5 迭代器失效和范围 for 的隐藏翻车点

C++ 里常见的“迭代过程中删除当前元素导致迭代器失效”，TArray 同样存在。范围 for 写法在删除元素时尤其危险，它内部隐藏了迭代器。

正确做法是反向迭代或用索引倒着删：

// 错误示范：范围 for 里 RemoveAt 会翻车 for (int32 Value : MyArray) { if (Value < 0) MyArray.RemoveAt(0); } // 正确示范：倒序删除 for (int32 i = MyArray.Num() - 1; i >= 0; --i) { if (MyArray[i] < 0) MyArray.RemoveAtSwap(i); }

如果只是“边遍历边筛选”，更推荐用RemoveAll，它专门干这个，内部高效且不用手写循环：

MyArray.RemoveAll([](const FString& S) { return S.IsEmpty(); });

3. TMap 和 TPair：键值对的存储真相与继承链

TMap 是 UE 的关联容器，用键快速定位值。它内部不是红黑树，也不是单纯的哈希表，而是基于稀疏数组哈希表实现，从使用角度更接近 std::unordered_map。但键值对的类型名 TPair 在官网文档里存在感很低，不少人只看代码 TMap<int32, FString>，根本不知道里面还套了一层 TPair 结构。

3.1 TPair 到底是什么，它的继承链怎么走

TPair 就是 UE 对“一对键值”的封装，类似 std::pair。它的定义核心是TPair<K, V>，内部包含两个成员：Key和Value。但早期版本的 UE 为了让 TPair 能放进各种容器，做了一层比较绕的继承设计。

简单说，当 TMap 的模板参数确定后，内部会生成一个继承链：

• TPair 本身是一个基础对结构；
• 在 TMap 内部使用的其实是TPair<K, V>的派生形式，名字大致是TMapKeyValuePair这类的内部结构；
• 这个内部结构用继承方式把TPair<K,V>作为基类包起来，同时重载一些哈希和比较逻辑；
• TMap 真正存储的元素是这个内部派生结构的实例，而不是裸的 TPair。

这样做的意义是：键值对的数据布局在编译期就固定，哈希计算、Key 比较可以用“基类指针转成 TPair”的视角去做，而继承链让 TMap 内部可以挂自己的元数据或自定义函数，不需要动 TPair 本体。

我最早查这个继承链，是遇到了一个报错：模板参数里的 K 和 V 被要求支持GetTypeHash和operator==。顺着报错往下翻，才看到 TPair 在 TMap 的 ElementType 里被包了一层。如果你只是想写业务代码，不理解继承链也能用 TMap；但一旦要自定义键类型、做内存分析、或者写泛型工具，就必须知道 ElementType 并不是 TPair 本身。

3.2 TMap 的哈希：Hash 层和索引层

TMap 的底层划分成两层：一层是哈希桶，一层是元素数组。哈希桶里存的是指向元素数组的索引，元素数组则是紧凑排列的 TPair 派生对象。Find 一个键时，先对键算哈希，定位桶，然后在那个桶的小数组里做线性查找，逐个比较键。因此对自定义键类型的哈希函数质量要求很高——如果所有键的哈希值都落同一个桶，TMap 就退化成了链表，性能直线下滑。

自定义键类型的标准模板：

uint32 GetTypeHash(const FMyKey& MyKey) { return HashCombine(GetTypeHash(MyKey.ID), GetTypeHash(MyKey.Name)); } bool operator==(const FMyKey& A, const FMyKey& B) { return A.ID == B.ID && A.Name == B.Name; }

GetTypeHash和operator==必须配套。哈希定了桶，等号决定桶内哪个键匹配。只做哈希不写等号，会出现“同一个键存在两个不同槽位”的诡异现象。

3.3 Add、Emplace、FindOrAdd 的差别

TMap 的插入接口看着多，其实各有用途：

• Add(Key, Value)：先拷贝 Key 和 Value，再放进 map。如果有同键，会覆盖旧值。
• Emplace(Key, Args...)：和 Add 类似，但对 Value 是原地构造，少一次移动。
• FindOrAdd(Key)：如果键已存在，返回引用；否则用 Key 的默认值插入一个新项，返回引用。
• FindRef(Key)：如果键存在，返回值的拷贝；不存在则返回 Value 的默认构造值。如果你要判断“到底有没有”，不能靠 FindRef，因为它区分不了“值是默认值”和“键不存在”。

我用FindOrAdd最多的地方是“按需求缓存统计结果”：一笔数据算出来后，先FindOrAdd拿引用，再往 Value 里累加，省掉两次查找。

TMap<FName, int32> ScoreMap; FName Key = TEXT("Alice"); int32& Score = ScoreMap.FindOrAdd(Key); Score += 10;

这段代码只做了一次哈希查找，比先 Contains 再 Emplace 高效许多。

3.4 遍历 TMap：struct 解构和 Key/Value 分离

C++11 之后遍历 TMap 最舒服的写法是：

for (const TPair<FName, int32>& Pair : ScoreMap) { UE_LOG(LogTemp, Log, TEXT("%s : %d"), *Pair.Key, Pair.Value); }

UE5 较新的版也支持结构化绑定：

for (const auto& [Key, Value] : ScoreMap) { // Key 和 Value 可直接用 }

如果你的编译环境和引擎版本支持，结构化绑定更直观。但要注意，TMap 遍历顺序是不确定的，不要依赖插入顺序或键顺序。需要保证顺序的场景，要么用 TMap 额外维护一个 TArray 缓存键顺序，要么换 TSortedMap 这类有序容器。

3.5 TMap 和 TArray 组合的常见反模式

我做模拟项目X 时遇到过一种写法：用一个 TArray 存几十万个结构体，再用一个 TMap 记录主键到数组下标的映射，用于快速查找。本身这是合理设计，但有人为了省事，用 TMap 存整个结构体副本，再存一份完整数组。数据一同步就是双倍内存，而且两个容器的一致性要靠人肉保证，一不小心就稀碎。

正确姿势：数组是权威数据源，TMap 只存索引，查询时拿索引回数组取数。这样删除元素时索引会失效，要做“墓碑标记”或定期重建映射，代价低于双写一致性。

4. 字符串和容器混用时那些最容易忽略的坑

字符串和容器单独用都不难，混在一起才是重灾区。这里不是讲基础 API，列几个我真实踩过、也见过同事踩的坑。

4.1 用 FString 当 TMap 的键：查询快，但创建时抖一下

FString 是可以直接当 TMap 键的，因为 UE 已经给 FString 实现了GetTypeHash。问题在于，每次向 TMap 里 Add 一个 FString 键，都会发生一次字符串内存分配和内容拷贝。如果一个帧内做几百次这种插入，GC 压力和堆分配都会上来。

如果这个键是“固定枚举性质的标识”，比如几组有限的状态名、动画通知名，果断换成 FName。FName 键比较开销是索引级别，几乎为零。但如果你的键是运行时的动态内容，比如玩家输入的用户名，那么用 FString 没问题，因为动态字符串转 FName 本身就是一次全局表插入，不划算。

4.2 TMap 里 Value 是 TArray，增删子元素要小心引用失效

这个坑很隐蔽。你用FindOrAdd拿到的 Value 的引用，随后往这个 Value（一个 TArray）里 Add 元素，TArray 内部扩容会把旧内存释放，这时你之前存的那个“指向 TArray 的指针”或者迭代器可能全失效。

很多人会写：

TMap<int32, TArray<FString>>& Dict = GetDict(); TArray<FString>& List = Dict.FindOrAdd(ID); List.Add(TEXT("hello"));

这段代码安全，因为每次都重新调FindOrAdd，拿的是新鲜引用。危险的是：

TArray<FString>& List = Dict.FindOrAdd(ID); // 之后又把别的键值对加进 Dict Dict.Add(AnotherID, AnotherArray); List.Add(TEXT("danger?")); // Dict 哈希层可能重构，List 可能悬垂

TMap 在插入新键导致哈希桶扩容时，会重新分配内部存储，之前拿出来的引用就失效。任何语言、任何哈希表都有这个问题，C++ 里不会给你运行时保护，只能靠规范规避：先完成 map 的增删操作，再拿引用去改子容器，不要在持有一个 map 元素引用的同时插入其他元素。

4.3 FText 和 TMap 的组合别乱来：本地化键和显示值要分开

有时候你想把界面文案缓存在 TMap 里，键用 FText 直接当 Key。这在逻辑上说得通，但它引入两个问题：一是 FText 的哈希和比较基于本地化状态，不同语言环境下的哈希结果可能变动；二是每次拿 FText 查找都要先走一遍本地化评估，性能不可控。

更规范的设计是：TMap 用 FName 当键，Value 存 FText。FName 描述这条文案的逻辑 ID，FText 是真正的显示文本。比如模拟项目X 里的任务描述缓存，我都是TMap<FName, FText>配合表格读入，切语言时整体重建 Value，不怎么动 Key。

4.4 容器默认值带来的“看似存在”心理陷阱

int32 Count = CountMap.FindRef(Key);

如果 Key 不存在，上面的Count拿到的是 0，而业务上“真正的零”也是 0，看起来完全正常。但如果 Key 的值本来就是“未知”状态，就不该用 FindRef 当成“查到了”。我见过一个 bug：玩家注册奖励，判断奖励计数是否已存在，用 FindRef 拿到的 0 被当成“已存在但数值为 0”，于是跳过补发，玩家损失奖励。

正确写法是：

int32* CountPtr = CountMap.Find(Key); if (CountPtr) { // 键确实存在 } else { // 键不存在 }

Find返回原始指针，为空就是不存在，没有默认值歧义。这是 TMap 使用里最值得养成习惯的一个细节。

5. 选型决策：一张表和一串建议让你少走弯路

技术点都讲完了，最后给一套我常用的选型逻辑。它不是唯一正确答案，但能覆盖大多数项目场景。

字符串选型再看一眼：

• 静态标识、比较频繁：FName
• 动态内容、要修改内容：FString
• 输出到界面、需要多语言：FText
• 三者在函数参数间传递时，优先考虑用引用传递，避免拷贝开销

TArray 和 TMap 之外的扩展：字符串当 Key 如果非要保留原字符串内容，又想要哈希性能，可以用TMap<FString, T*, FStringSetKeyFuncs>这种自定义分配器，不是常规需求，但存在。

6. 算一笔实际账：一个缓存模块的改造过程

理论讲太多不如结合场景。模拟项目X 里有一个怪物刷新配置表，早期用TArray<FMonsterInfo>存全部配置，查找通过遍历比对 ID。数据量只有几百条，开发时觉得无所谓。后面前端要频繁请求怪物详情，每帧可能有几十次查找，遍历一下子成了热点。

第一步：把索引关系改成TMap<int32, int32>，键是怪物 ID，值是数组下标。查找从 O(n) 变 O(1)。数组仍然保留，因为 UI 列表要按配置顺序渲染，TMap 无法保证顺序。

第二步：键类型一开始考虑过 FString 或 FName。怪物 ID 是从配置表读进来的整型，直接 int32 就好，省到不能再省。这里不要为了“统一用字符串 ID”去转一圈，整型键的哈希和比较都最低廉。

第三步：缓存详情对象。原先每次查找都是重新从结构体拷贝数据，改成在 TMap 里缓存一个索引，再拿索引去数组里取引用返回。注意，返回的是引用还是值要看调用方是否要改数据。只读用const FMonsterInfo&，避免大结构体频繁拷贝。

改造后，原来每帧查找热点完全消失。整个过程中最有价值的不是换了容器，而是把“哪些是稳定数据、哪些是索引、哪些是缓存”理清楚了。容器的选择永远是跟着数据生命周期走的。

7. 一些分散但实用的熟手操作细节

有些知识点太小，单独开一章显得啰嗦，但不写又确实有用，凑在一起记录一下。

7.1 UE_LOG 输出容器内容

直接UE_LOG(LogTemp, Log, TEXT("%s"), *MyArray)是不行的，TArray 没有直接转字符串的函数。三种常用方案：

// 1. 手动遍历拼 FString FString Result; for (int32 V : MyArray) Result += FString::FromInt(V) + TEXT(", "); // 2. 用 FString::Join 处理字符串数组 TArray<FString> Names = {TEXT("A"), TEXT("B"), TEXT("C")}; FString Joined = FString::Join(Names, TEXT("|")); // 3. 如果元素类型支持 ToString，可以封装一层模板工具

FString::Join 是个宝藏函数，处理 CSV、日志输出比手写循环干净得多。

7.2 TArray 的 Reserve 与 Emplace 配合

当你知道 TArray 大概会存多少元素时，先Reserve一个容量，避免多次扩容：

TArray<FVector> Points; Points.Reserve(10000); for (int32 i = 0; i < 10000; ++i) { Points.Emplace(X, Y, Z); }

Emplace对 FVector 这种类型是原地构造，少一次默认构造再赋值的开销。对于大结构体，Emplace比Add有肉眼可见的效率优势。

7.3 TMap 的 Keys 和 Values 视图

有些场景要单独拿所有键。TMap 提供了Keys()和Values()视图，返回的是不可修改的轻量视图，不要动态分配数组复制一份——除非你真的需要“某一时刻的快照”，否则直接用视图遍历：

for (const int32& K : MyMap.Keys()) { // 遍历所有键 }

这么写在语义上更清晰，也不会误改 map 结构。

7.4 TSortedMap 和 TMap 的取舍

TSortedMap内部基于有序数组实现，键必须支持operator<。它的优势是内存更紧凑、遍历有序；劣势是插入和删除是 O(n)。如果容器数据变化不频繁但遍历频繁，TSortedMap 可能比 TMap 更合适。不过实际项目里 TMap 确实是绝对主流，性能瓶颈往往不在容器本身，而在“算哈希”和“比较键”这两个动作上。

7.5 自定义结构体做键的常见翻车点

有种情况特别坑：结构体里有个 FString 成员，用来当键的一部分。你的GetTypeHash写的是GetTypeHash(MyStruct.Name)，但查询时这个 FString 的大小写和插入时不一样，哈希值不同，就找不到。FString 的 GetTypeHash 是区分大小写的，如果业务上不区分大小写，必须先ToLower()再哈希，否则一样的内容会变成两个键。写哈希函数时一定要和业务的等值语义对齐。

8. 最后的“查漏补缺”：从源码角度再看一眼这几种类型

想把这几个类型彻底内化，建议有空直接翻 UE 的源码。FString 看StringBase.h开头那两百行，就能理解它的存储布局；FName 看NameTypes.h中GetComparisonIndex的处理，理解大小写不敏感的真正含义；TMap 看Map.h里Find的完整路径，能一眼看出它先算哈希再比较键的执行顺序。这些源码不难读，虽然没有注释，但结构脉络非常清楚。

所以我一般不建议死记 API，而是把“数据生命周期”想清楚：谁创建、谁持有、谁查询、谁销毁，容器类型和字符串类型自然会选对。这一步想清楚了，什么 TArray、TMap、TPair 继承链，都只是顺手的事。