UPROPERTY 这三个字母几乎是每个用虚幻引擎Unreal Engine写 C 的人第一步就会撞到的东西。最典型的一幕就是你在类里声明了一个int32 Health;满心期待它出现在细节面板里、能被蓝图读到结果编辑器里干干净净什么都没有。不是引擎坏了是漏写了 UPROPERTY 这个宏。它本质上就是 UE 反射系统的入口开关只有被它标记过的成员变量编辑器、蓝图虚拟机、序列化系统、垃圾回收器才会“看到”这个变量。这篇文章是系列里的第一篇正篇我干脆把 UPROPERTY 里能填的参数按功能分类过一次配合实际工程里踩过的坑一起讲适合刚入门 UE C 的开发者也适合写过一段时间但一直靠“复制粘贴参数”糊弄过去的人。1. 在声明成员变量之前先搞懂 UPROPERTY 到底替你打开了哪些能力1.1 基础语法与生效位置UPROPERTY 是一个宏官方叫法叫“属性说明符”它写在成员变量声明上方格式是UPROPERTY(参数1, 参数2, ...)括号里可以填零个或多个参数。最基础的用法是这样UCLASS() class MYGAME_API AMyCharacter : public ACharacter { GENERATED_BODY() public: UPROPERTY(EditAnywhere, BlueprintReadWrite, Category Character) float WalkSpeed 600.0f; };需要注意的是它只能修饰 UCLASS 或 USTRUCT 内部的成员变量。普通函数里的局部变量、函数参数、静态全局变量这些都用不上 UPROPERTY。更准确地说UPROPERTY 标记的必须是“反射系统认识的类”里面的成员属性比如 AActor、UActorComponent、UObject 派生类或者带 USTRUCT 的结构体。这一点很多人一开始会搞混以为任何变量都能挂这个宏结果编译报错也不知道为什么。宏的作用范围决定了它能影响的维度编辑器面板上的可见性、蓝图节点能不能读写、存档时要不要写入、网络复制时要不要同步。这几件事看着不相关但底层全部依赖同一个东西——UClass 的反射信息。没有 UPROPERTY虚拟机和编辑器就完全不知道这个成员存在。1.2 哪些类型值得被标记理论上任何能在反射系统里表达的类型都可以标 UPROPERTY包括基础类型bool、int32、float、double、FString、FName、FText、FVector、FRotator、FTransform以及 TArray、TMap、TSet 和 UObject 指针。但不是所有类型都能被完整支持比如 TMap 的键值类型本身必须也是反射系统能认识的嵌套得很深的自定义类型也要小心。这里有个非常容易踩的坑C 标准库容器std::vector、std::unordered_map 等不能直接标 UPROPERTY。如果你写UPROPERTY() std::vectorint32 Data;编译会直接报错。必须换成 TArray、TMap。原因很简单UE 的反射系统和 GC 系统不认识标准库容器也不知道怎么去遍历里面的 UObject 指针。还有一个更隐蔽的规矩非 UPROPERTY 的 UObject* 指针成员变量垃圾回收器不会把它当成一条引用关系来追踪。也就是说你 new 出来的对象可能在某次 GC 时被判定为“无引用”直接回收掉然后你下次访问这个指针就是访问一块已经释放的内存轻则读到脏数据重则直接崩溃。这个问题的排查难度很高因为崩溃点往往不在指针本身而在之后某个使用它的函数里给你一种“这里代码明明没写错”的错觉。1.3 无参 UPROPERTY 的默认行为以及一个 GC 陷阱UPROPERTY()空括号不带任何参数它其实也不是完全没用——它至少让 GC 系统能追踪到这个成员并且属性本身也会参与 UObject 的默认序列化流程。但注意它不会出现在编辑器细节面板里蓝图节点默认也不能访问网络复制默认关闭。关于序列化这里必须说细一点不然很容易被误导。UE 中普通 UPROPERTY() 属性在保存关卡时其实会被写入关卡文件因为这是 Actor 实例序列化的一部分。而 UPROPERTY(SaveGame) 是额外标记给“游戏存档系统”用的比如 UGameplayStatics::SaveGameToSlot 这类 API 只处理标了 SaveGame 的属性。两者作用域不同后面第 4 章会详细拆。GC 陷阱再补一句如果成员变量不标 UPROPERTY但它是 UObject 指针它在 GC 看来就和一块普通内存差不多不会因为“有人还指向它”而存活。我见过一个项目某个 Manager 里放了一堆 UDataAsset 指针没标 UPROPERTY结果运行时偶发指针失效每次玩家换关卡时间还不一样最后排查到是数据资产被 GC 干掉了。加了 UPROPERTY() 之后问题彻底消失。所以哪怕你完全不碰编辑器、不用蓝图只要类里有 UObject* 成员请无条件给它挂一个 UPROPERTY这是 UE C 的底线习惯。2. 编辑器可见性参数六种写法背后的四种生命周期2.1 逐对拆解 Edit/Visible 与 DefaultsOnly/InstanceOnly编辑器可见性参数应该是 UPROPERTY 里被用得最多的一族但很多人只记住了 EditAnywhere 和 VisibleAnywhere剩下的四种组合基本靠猜。这一族参数其实是两个维度的组合产物。第一个维度是“能不能改”Edit 表示可以编辑Visible 表示只能看不能改。第二个维度是“在哪个层级上可见/可编辑”DefaultsOnly 表示只在类默认值Class Defaults里可见InstanceOnly 表示只在放置到关卡或蓝图实例的细节面板里可见而 Anywhere 表示所有层级都生效。为什么要分两个层级因为 UE 的 Actor 有“类默认值”和“实例”两个状态。在 C 类里声明的初始值属于类默认值蓝图里修改的是蓝图默认值而把 Actor 拖进关卡后每个放置出来的 Actor 都是一个实例。有些配置是整类通用的你希望用户只能在类默认值里改有些配置是每个实例都不同的比如门应该朝哪个方向开那就应该暴露在实例面板上。组合起来就是官方文档里列的六种EditAnywhere类默认值和实例都能编辑EditDefaultsOnly只能在类默认值/蓝图默认值里编辑EditInstanceOnly只能在实例上编辑VisibleAnywhere类默认值和实例都能看到但不能编辑VisibleDefaultsOnly只在类默认值里只读可见VisibleInstanceOnly只在实例里只读可见2.2 六种组合速查表说明符类默认值/蓝图默认值关卡实例典型用途EditAnywhere可编辑可编辑通用配置参数如移动速度、伤害数值EditDefaultsOnly可编辑不可编辑数据资产、角色基类共享能力配置EditInstanceOnly不可编辑可编辑每个放置实例单独定制的门朝向、巡逻点VisibleAnywhere只读只读运行时状态展示如当前生命值VisibleDefaultsOnly只读不可见组件引用、内部状态调试VisibleInstanceOnly不可见只读实例运行时内部状态不希望被误改表格里有一块很容易被忽略VisibleDefaultsOnly在关卡实例上是直接看不见的VisibleInstanceOnly在类默认值里看不见。这会导致一个很常见的迷惑行为——你在 C 里声明了一个组件指针用 VisibleDefaultsOnly蓝图类默认值里能看到但拖到关卡后实例细节面板里看不到这个组件条目了。很多人会以为自己没写对其实只是层级没对上。2.3 从默认值到实例值选型建议实际项目里我的建议很简单凡是运行时会被代码修改、只想给策划或美术看状态的用 VisibleAnywhere凡是需要在蓝图子类里统一配置的用 EditDefaultsOnly凡是每个放置实例都需要单独调的东西用 EditInstanceOnly如果拿不准默认用 EditAnywhere 一般不会出大问题只是面板会有点乱。这里还要强调一个容易混淆的概念编辑器的可见性和蓝图的BlueprintReadOnly/Write是两套正交系统。也就是说VisibleAnywhere只是让编辑器里不能手动改但如果你同时写了BlueprintReadWrite蓝图节点照样可以写这个变量。反过来EditAnywhere但只写BlueprintReadOnly编辑器里能改蓝图里却只能读。这类组合是合法的也经常是故意设计的——比如一个变量希望策划在编辑器里配好但运行时蓝图逻辑不允许随便覆盖。3. 蓝图读写与生成暴露把变量权限设计清楚而不是一刀切3.1 BlueprintReadOnly 与 BlueprintReadWrite 的真实边界这是 UPROPERTY 参数里语义最直白的一对但实际写代码时经常被误用。BlueprintReadWrite意味着蓝图里既能读又能写BlueprintReadOnly意味着蓝图里只能读不能写。我在项目里见过不少同事把状态类的变量全都标成BlueprintReadWrite理由是“反正蓝图里可能要用”。结果就是蓝图逻辑满天飞任何一个蓝图节点都能改血量和金币出 bug 时根本不知道是谁动的。更好的做法是只把外部需要修改的输入参数标 ReadWrite把内部运行时状态标 ReadOnly。比如UPROPERTY(EditAnywhere, BlueprintReadWrite, Category Character|Stats) float MaxHealth 100.0f; UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category Character|State) float CurrentHealth 100.0f;这样蓝图可以读当前血量并显示到 UI但不能随手把血量改掉。如果后面真的需要加血减血提供函数而不是开放变量本身。3.2 使用 BlueprintGetter/BlueprintSetter 的意义如果你不只想要“能读能写”还想在读写的时候执行额外逻辑那就要用BlueprintGetter和BlueprintSetter指定访问器函数。写法是这样的private: UPROPERTY(BlueprintReadWrite, BlueprintGetter GetHealth, BlueprintSetter SetHealth, meta (AllowPrivateAccess true)) float Health; public: UFUNCTION(BlueprintPure) float GetHealth() const { return Health; } UFUNCTION(BlueprintCallable) void SetHealth(float NewValue) { Health FMath::Clamp(NewValue, 0.0f, MaxHealth); }注意BlueprintGetter和BlueprintSetter参数的值是函数名不是meta。函数本身要标 UFUNCTIONGetter 通常用BlueprintPureSetter 通常用BlueprintCallable。加了这两个参数之后蓝图上生成的节点不再是直接读写变量而是调用对应的函数。这对需要校验、事件通知、同步 UI 的场景非常有用。3.3 ExposeOnSpawn让生成参数变得可配置ExposeOnSpawn是一个很有意思的参数它能让变量出现在蓝图里Spawn Actor节点下方的参数列表里。什么意思就是你从蓝图生成一个 Actor 时可以直接在生成节点上传入这个值而不需要生成之后再主动调用一个 Init 函数。UPROPERTY(EditAnywhere, BlueprintReadWrite, ExposeOnSpawn, Category Projectile) float InitialSpeed 1500.0f;这样以后其他蓝图在生成这个抛射物时Spawn 节点就会多出一个 InitialSpeed 输入引脚填多少它就带多少起飞。这个参数很适合做子弹初速度、敌人初始状态这类需要“一出生就决定”的数据。注意它一般搭配 BlueprintReadWrite 或 BlueprintReadOnly 使用纯 C 内部变量用不上。3.4 私有变量的 AllowPrivateAccess 细节还有一个细节我经常在代码里看到但很多人不清楚为什么加当你把属性声明在private或protected下又想让蓝图能访问时一般要在meta里加一个AllowPrivateAccess true。private: UPROPERTY(EditAnywhere, BlueprintReadOnly, meta (AllowPrivateAccess true)) float HiddenFromCpp;它的作用是让 UE 自动生成的反射代码可以访问这个私有成员因为 UHTUnreal Header Tool生成的代码本质上还是 C 代码直接访问 private 成员会编译报错。不写AllowPrivateAccess编译通常也会过因为 UHT 有默认行为但官方明确推荐你在私有访问时显式加上避免头文件工具在版本升级或特定配置下生成出不可编译的代码。这里顺带说一句虽然加了它蓝图能访问私有变量但它不会改变 C 层面的访问权限外部 C 代码依旧不能直接点这个私有变量只有蓝图可以。