做 UE 开发的人基本都体会过这种场景C 里明明写了一个公开变量结果蓝图里死活找不到或者属性面板上该出的框根本没出现再或者打包完发现存档数据丢了回查代码才发现是 UPROPERTY 没写对。这类问题十有八九都出在 UPROPERTY 的参数选择上。我整理这份 UPROPERTY() 参数汇总就是想把平时最常用、最容易被忽略的标记方式一次性说清楚从编辑器可见性、蓝图权限、序列化存储、网络复制到 Meta 元数据每个都配上使用场景和代码示例。刚接触 UE C 的开发者可以把这篇文章当入门索引已经写过一阵子的老手也可以拿来做查漏补缺的工具页。1. UPROPERTY 到底在干什么1.1 反射系统是这一切的前提UPROPERTY 表面上是个宏真正起作用的是它背后那套反射系统。UE 在编译 C 时会通过 Unreal Header Tool简称 UHT扫描头文件遇到 UPROPERTY 修饰的变量就自动生成对应的反射元数据存到 .generated.h 和相关的生成代码里。这样引擎在运行时就能知道这个变量的名字、类型、访问标志和 Meta 信息从而在编辑器面板、蓝图、序列化、GC 垃圾回收、网络复制这些环节里正确处理它。反过来看一个 C 成员变量如果没有任何 UPROPERTY 修饰它在 UE 的反射体系里就是隐形的。后果非常现实属性面板看不到它蓝图访问不到它存档和网络同步跟它没关系甚至连 GC 都不会把它当 UObject 引用去追踪。最常见的坑就是在一个 Actor 里存了一个 UObject* 指针却忘了写 UPROPERTY结果运行一段时间后指针变成悬垂地址对象被引擎回收了代码还在用。这种 bug 排查起来特别费劲因为它不是必现的往往取决于 GC 什么时候正好触发。所以理解 UPROPERTY 的第一件事就是记住它不是在修饰变量它是在告诉引擎“这个变量需要被反射系统管理起来”。至于具体怎么管理就由括号里的参数决定。1.2 空括号和没有括号的本质区别有朋友问过UPROPERTY() 里头什么都不写那不等于没写吗还真不是。空括号的 UPROPERTY 足够让变量进入反射系统了它会被序列化、会被 GC 正确追踪只是因为没有任何暴露标记所以在编辑器面板和蓝图里都看不到。换句话说如果你只是因为要存一个 UObject* 防止被 GC 回收那么 UPROPERTY() 就已经够用了。但如果你希望这个变量能出现在 Details 面板上或者能让蓝图去读写就必须在括号里加参数。这也解释了为什么老项目里有些变量明明没写任何访问修饰数据却能正常存档。明白了这个底层的区别后面理解各个参数就轻松多了。2. 编辑器和蓝图的访问权限参数2.1 可见性六兄弟怎么选这一组参数是 UPROPERTY 使用频率最高的也是很多人一开始最分不清的EditAnywhere、EditDefaultsOnly、EditInstanceOnly以及对应的 Visible 版本。它们控制的是两个维度能不能在编辑器里改以及在哪个层级上改。参数编辑器可见修改范围典型使用场景EditAnywhere可编辑默认值和实例都能改通用配置最常用EditDefaultsOnly可编辑只允许改类默认值CDO固定配置、常量表EditInstanceOnly可编辑只允许改摆放到场景里的实例每个实例都不同的临时参数VisibleAnywhere只读展示默认值和实例值运行时状态展示VisibleDefaultsOnly只读只展示默认值只读配置项VisibleInstanceOnly只读只展示实例值运行时调试状态这里面的 CDO 全称是 Class Default Object可以理解成这个类的“默认模板对象”。选 EditDefaultsOnly 意味着这个值在资产模板上定死场景里摆放出来的实例不能单独改适合武器 ID、攻击类型这类同一类对象保持一致的数据。选 EditInstanceOnly 则反过来改动不会写进默认模板适合“这棵树放得比其他树大一点”这种实例差异。如果拿不准默认用 EditAnywhere 是最稳妥的但也要注意别把需要统一管理的配置数据开放成实例可改那样很容易出现两棵武器参数不一致的脏数据。2.2 蓝图访问权限和 Getter/Setter编辑器面板之外蓝图能不能读写这个属性由另一组参数控制BlueprintReadOnly 和 BlueprintReadWrite。名字含义很直白前者蓝图只能读不能写后者蓝图可读可写。如果什么都不写蓝图里根本不会看到这个属性这时候就算加了 EditAnywhere 也没用它只对编辑器面板生效。实际项目里我一般遵循最小权限原则核心状态值用 BlueprintReadOnly由 C 来维护合法性希望蓝图灵活调整的数值才用 BlueprintReadWrite而且最好配合 BlueprintSetter 做一层校验。// 头文件 UPROPERTY(EditAnywhere, BlueprintReadWrite, BlueprintSetter SetMaxHealth, Category Combat, meta (ClampMin 1.f)) float MaxHealth 100.f; UFUNCTION(BlueprintSetter) void SetMaxHealth(float NewValue) { MaxHealth FMath::Max(NewValue, 1.f); }BlueprintSetter 的作用是蓝图里给这个属性赋值时不走直接赋值而是调用指定的函数。这样你就能在 C 侧把非法值拦下来。类似的还有 BlueprintGetter在蓝图读取属性时触发自定义逻辑。这个设计很符合工程习惯相当于给属性加了一道业务层的“门卫”特别适合处理百分比、血量上限这类有边界要求的数值。另外还有个高频细节如果属性声明成了 private又想给蓝图访问必须加上 Meta 参数meta (AllowPrivateAccess true)否则编译器会报封装性错误。我见过不少同事把属性临时改成 public 来解决其实完全没必要显式声明访问范围反而更干净。3. 序列化、存储和网络复制参数3.1 存什么、不存什么SaveGame / Transient / ConfigUPROPERTY 里有一组参数专门控制变量的生命周期和存储行为日常开发最容易踩坑的也集中在这块。SaveGame 是最直白的一个标记了这个参数的属性才会被 UE 的存档系统比如 UGameplayStatics::SaveGameToSlot写入存档文件。需要说明的是如果外层 SaveGame 属性指向一个 USTRUCT结构体内部的子属性只要有普通 UPROPERTY() 就会被一并序列化不需要每个字段都重复标 SaveGame。反过来如果希望结构体里某个字段不进存档那才需要单独处理。Transient 的含义是“临时数据”标记后该属性不参与序列化也不会存进存档或进编辑器撤销记录。运行时缓存、每帧临时结果、不需要留在磁盘上的中间状态都可以用它标记。这里有个非常典型的错误有人想存一个数据同时标了 SaveGame 和 Transient结果发现存档里永远是默认值。原因是 Transient 的优先级更高相当于告诉引擎“这玩意不需要持久化”SaveGame 自然就失效了。这两个参数是互斥的用之前先想好这个数据是存还是不存。Config 参数则是把属性的初始值和 ini 配置文件绑定。标了 Config 的属性引擎启动时会从配置文件的对应节读初值修改后也可以写回配置文件。用得最多的是各种可调参数比如服务器 TPS、资源刷新时间这类需要上线后微调的值。要注意的是一旦标了 Config运行时看到的初值可能跟你代码里写的默认值不一样因为 ini 里的残留旧值会优先覆盖。调试的时候如果发现改了默认值没生效第一反应应该是去查配置文件里有没有旧数据。3.2 网络复制Replicated 与 ReplicatedUsing多人项目里变量能不能从服务器同步到客户端由 Replicated 系列参数控制。Replicated 本身表示这个属性参与网络复制服务端的值变化后会推送到客户端。ReplicatedUsing 则在同步的基础上追加一个 OnRep 回调当客户端收到新值时触发指定函数通常用来刷新表现层。// 头文件 UPROPERTY(ReplicatedUsing OnRep_Health, BlueprintReadOnly, Category Combat) float Health 100.f; UFUNCTION() void OnRep_Health(float OldHealth); virtual void GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const override;对应的实现文件里必须注册复制变量#include Net/UnrealNetwork.h void APlayerCharacter::GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const { Super::GetLifetimeReplicatedProps(OutLifetimeProps); DOREPLIFETIME(APlayerCharacter, Health); } void APlayerCharacter::OnRep_Health(float OldHealth) { if (!HasAuthority()) { // 客户端表现更新比如血条、受伤特效 } }这里有两个容易踩的坑。第一标记了 Replicated 的属性如果忘了在 GetLifetimeReplicatedProps 里注册开发模式下可能只是表现不同步打包版本才会直接报编译错误找原因的过程相当痛苦。第二Replicated 变量只推荐在服务器端修改客户端本地改只影响自己不会同步给其他人如果设计上必须由客户端发起修改正确的姿势是先走服务器 RPC由服务器改完再复制回来。OnRep 回调在客户端收到新值时触发服务端本身不执行这套表现逻辑所以回调里一般用HasAuthority()判断一下再刷 UI避免 Listen Server 这种本机兼具服务器和客户端身份的情况下重复播放效果。4. Meta 元数据参数4.1 数值范围和面板显示控制Meta 参数是目前为止内容最丰富的一类它不改变属性的编译属性和复制行为专门负责“编辑器里怎么显示、操作员怎么输入”这类体验问题。最常用的是数值范围控制Meta 参数作用注意事项ClampMin / ClampMax严格限制数值上下限键盘输入也会被限制UIMin / UIMax只限制滑杆拖动范围直接输入可以超出Units在数值旁显示单位如 cm、m/sTooltip鼠标悬停时的提示文字适合补充说明DisplayName面板和蓝图中显示的别名支持空格和中文Clamp 和 UI 的区别很关键。UIMin/UIMax 只是把滑杆的范围框住操作者依然可以在输入框里填一个超过范围的值ClampMin/ClampMax 则是硬约束不管怎么输入都会被拽回合法区间。做伤害数值这类核心参数我习惯两个都写UIMax 设置一个舒服的拖动上限ClampMax 再设一个业务上的绝对上限避免有人填出个天文数字。比如一个暴击倍率属性滑杆拉到 3.0 就差不多了但 ClampMax 可以放宽到 10.0给策划留一点调试空间同时保证不会出现负数。面板显示相关的参数里Category 是老朋友了虽然不是 Meta但和显示关系最大。Category Weapon|Damage这种写法用竖线分层级会在 Details 面板里生成多级折叠目录强烈建议所有暴露到编辑器的属性都加 Category不然所有属性堆在默认分类下面后期根本没法看。4.2 那些能提升开发效率的元数据Meta 里还有一批参数不是必填但用了之后能让编辑体验上一个台阶。EditCondition 可以控制属性的可编辑状态配合一个 bool 属性条件为真时可编辑为假时置灰。比如“是否启用自定衰减”这个开关为 false 时后面的衰减系数就不该被乱动。新版引擎还支持 EditConditionHides条件不满足时直接把字段隐藏比置灰更清爽面板上不会出现一堆无效控件。ShowOnlyInnerProperties 是处理结构体的利器。如果一个属性指向 USTRUCT默认面板会显示成一个折叠块点开才能看到字段。加上这个 Meta 后结构体内层字段会直接平铺显示在面板上少一层嵌套配置效率高不少。注意这个参数加在结构体属性上而不是结构体声明里。GetOptions 参数可以实现下拉框动态选项。它指定一个返回 TArray 的函数编辑器会把函数返回的字符串列表渲染成下拉选项避免手填。比如角色职业列表、技能 ID 列表都可以这样维护。配合 AllowedClasses 限制资产选择器只能选特定类型做资产引用类属性非常实用能直接筛掉大部分无关资源。5. 实际组合用法与代码示例5.1 一个兼顾面板、存档、复制的完整示例把上面的参数组合起来看一个真实的武器 Actor 的声明大概长这样UCLASS(Blueprintable) class AGameWeapon : public AActor { GENERATED_BODY() public: // 固定配置只能在默认值里改蓝图只读 UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category Weapon|Config, meta (Tooltip 武器ID默认值统一在资产模板里配置)) FName WeaponID NAME_None; // 数值参数蓝图可读写严格限制范围 UPROPERTY(EditAnywhere, BlueprintReadWrite, Category Weapon|Config, meta (ClampMin 0.f, ClampMax 100.f, UIMin 0.f, UIMax 80.f, Units 点)) float BaseDamage 10.f; // 运行时状态只读展示不持久化 UPROPERTY(VisibleInstanceOnly, BlueprintReadOnly, Transient, Category Weapon|State) float CurrentDurability 100.f; // 存档数据参与存档系统 UPROPERTY(VisibleAnywhere, SaveGame, Category Weapon|State) int32 KillCount 0; // 网络复制服务器同步归属者变化时触发回调 UPROPERTY(ReplicatedUsing OnRep_OwnerChanged, BlueprintReadOnly, Category Weapon|Combat) AActor* WeaponOwner nullptr; UFUNCTION() void OnRep_OwnerChanged(); virtual void GetLifetimeReplicatedProps(TArrayFLifetimeProperty OutLifetimeProps) const override; };这个声明里每一行都有明确意图。WeaponID 属于固定配置用 EditDefaultsOnly 防止场景里每个实例私自改BaseDamage 是策划需要频繁调的数值给足权限但用 Clamp 守住底线CurrentDurability 是运行时变化的耐久Transient 保证它不进存档、不污染资产KillCount 是需要记录进存档的业务数据WeaponOwner 走网络复制多人模式下归属权变化能实时通知客户端。一个属性的参数选择直接把它的生命周期、权限边界和存储策略都写清楚了这就是 UPROPERTY 的价值。5.2 选参的决策思路刚上手时面对这么多参数容易懵我给一个自己一直在用的判断顺序第一步先问这个值谁来维护。如果是配置表或者资产模板统一维护用 EditDefaultsOnly如果是场景实例各自的差异用 EditInstanceOnly如果没什么讲究EditAnywhere 兜底。第二步问蓝图需不需要碰。需要写就 BlueprintReadWrite只读就 BlueprintReadOnly完全不需要就都不写省得蓝图侧变量列表里出现一堆用不到的东西。第三步问这个数据要活多久。永久记录就 SaveGame运行期间临时状态就 Transient需要启动时从配置文件读就 Config。这三种互相冲突只能选一个方向。第四步多人游戏里问一声要不要同步。要同步就 Replicated需要响应变化就补上 ReplicatedUsing 和 OnRep。不需要同步也别浪费带宽。这个顺序想清楚之后你写出来的 UPROPERTY 声明基本不会有大问题而且每行参数都能在评审时给出理由而不是“别人都这么写”。6. 高频问题与排查经验6.1 常见问题速查表现象大概率原因处理方式属性面板上看不到变量没写 UPROPERTY或只写了空括号补 UPROPERTY按需加 EditAnywhere 等蓝图里找不到变量缺 BlueprintReadOnly / BlueprintReadWrite补蓝图权限参数打包后数据丢失属性未标记 UPROPERTY或缺少序列化参数检查 SaveGame、Config客户端复制值不同步漏了 Replicated 或 DOREPLIFETIME 注册补注册复制变量蓝图能填出非法数值缺少 Clamp 或 setter 校验加 Clamp 或 BlueprintSetter存档里始终是默认值属性同时标了 Transient 和 SaveGame去掉 Transient改了 C 默认值但运行时没变化Config ini 里有旧值覆盖删除对应 ini 配置private 属性蓝图访问报错缺 AllowPrivateAccess加 meta (AllowPrivateAccess true)这个速查表覆盖了我这几年被问过最多的问题也是自查时的第一排查清单。6.2 日常开发容易忽略的细节有几个细节不在速查表里但踩过之后印象特别深。第一个是 Category 的层级设计。Category Weapon|Damage里的竖线能让面板生成二级目录但目录一旦定下来后期改名会让所有已配置资产的分类位置发生变化。所以分类名最好在项目初期就定好规范别写得太随意。第二个是结构体内部字段的 UPROPERTY。我见过有人只在 USTRUCT 整体上标了参数内部字段全靠默认结果某个字段在打包版本里悄悄消失了。记住一条规则反射遍历是逐层扫描的结构体内部的每个字段也必须各自有 UPROPERTY()哪怕就是空括号否则它不会被序列化。第三个是数组和容器的参数同样适用但要额外注意数组的元数据。比如 TArray 属性加了meta (EditFixedSize)之后编辑器面板里就不允许增删元素只能改已有的值这对那些“长度必须固定”的配置项非常有用避免美术或策划误加元素导致逻辑错乱。最后补一句和 UPROPERTY 无关但密切相关的习惯给暴露给蓝图的属性起名字时保持清晰默认蓝图侧会直接沿用 C 属性名下划线风格会在编译时报错所以属性名本身就要按照“变量名词 语义明确”的标准来写。属性声明多花几秒钟后面项目维护能省下大量沟通时间。我个人的体会是UPROPERTY 参数看着散核心逻辑只有一个你要清楚这个数据在编辑器、蓝图、存档、网络各自扮演什么角色然后用最小权限组合去满足它。少写一个参数往往不是编译报错而是运行期一个难查的诡异问题。这一篇算是 UPROPERTY() 参数汇总的第一部分后面如果有时间我再把 UFUNCTION 的参数、RPC 调用相关的反射声明单独拉出来整理一篇那样整个 UE C 的反射体系就能串起来了。