企业官网建设流程全解析

写UE的C++变量时，我见过太多新人把UPROPERTY当装饰品，随手复制一行，结果要么策划在场景里把武器伤害改得乱七八糟，要么蓝图节点列表里死活找不到变量，最后只能debug半天。EditDefaultsOnly、EditAnywhere、VisibleAnywhere、VisibleDefaultsOnly、BlueprintReadWrite、BlueprintReadOnly这六个说明符，就是控制变量“谁能看、谁能改、在哪儿改”的开关。这篇内容是我多年踩坑后整理的选型笔记，从反射原理一直讲到搭配组合和排查思路，适合所有写UE C++的人，也适合正在从蓝图转C++的开发者。看完你会明白，这些说明符不是靠背的，而是有一套非常清晰的判断逻辑。

1. 先搞清楚UPROPERTY到底在管什么

1.1 反射系统决定了这些说明符有意义

UPROPERTY不是给编译器看的，是给引擎的反射系统看的。UE里的编辑器细节面板、蓝图节点、序列化存档，都依赖反射系统去扫描类的成员变量。一个C++变量如果不带UPROPERTY，它在引擎眼里就是“不存在”的，哪怕你把变量声明为public也没用，蓝图依然找不到它。

我常跟团队里新人打一个比方：普通成员变量是你抽屉里的一封信，只有你自己知道；加上UPROPERTY等于在信封上贴了标签，让引擎知道这封信存在、内容是什么、谁可以打开。反射系统就像公司的行政，没有登记过的资产，盘点时根本不会出现在系统里。

所以第一步要建立观念：EditDefaultsOnly、EditAnywhere这些说明符，本质是在告诉反射系统，这个变量在编辑器的哪些情境下可以被展示、被修改。

1.2 两套完全独立的权限维度

很多刚上手的人把EditAnywhere和BlueprintReadWrite混为一谈，这是最大的误区。实际上它们管的是两套完全独立的维度。

第一套维度是编辑器访问权限，由EditDefaultsOnly、EditAnywhere、VisibleAnywhere、VisibleDefaultsOnly控制。它决定的是“细节面板里这个变量能不能看到、能不能手动改”。

第二套维度是蓝图访问权限，由BlueprintReadWrite、BlueprintReadOnly控制。它决定的是“蓝图图表里的变量节点能不能取值、能不能赋值”。

这两套维度可以自由叠加。比如一个变量可以设置为“细节面板里能编辑，但蓝图只能读”，写法是EditAnywhere + BlueprintReadOnly；也可以设置为“细节面板只读，但蓝图里可以读写”，写法是VisibleAnywhere + BlueprintReadWrite。理解这个独立性，后面的组合就全都顺了。

1.3 类默认值CDO和实例，先把这个搞明白

要理解EditDefaultsOnly和EditAnywhere的差别，绕不开CDO（Class Default Object，类默认对象）的概念。每个UCLASS在引擎加载时都会生成一份默认对象，蓝图编辑器里的“类默认值”面板，改的就是这个CDO身上的属性。

你从蓝图类拖一个Actor到关卡里，得到的是这个类的实例。实例在生成时会从CDO拷贝一份属性值，之后它身上存的是自己的那份拷贝。

我通常用汽车出厂配置和实际车辆来类比：类默认值就是汽车出厂时的标准配置表，每个实例是一辆实际卖出去的车。EditDefaultsOnly只允许你修改出厂配置表，不允许你在某辆具体车上改参数；EditAnywhere则允许你针对每一辆车单独设置颜色、选装包。想明白这个区别，很多选择就自然有了答案。

2. 编辑相关说明符逐个拆解

2.1 EditDefaultsOnly：只允许设计者改类默认值

EditDefaultsOnly的意思是，这个属性只能在蓝图类的默认值面板里编辑，放到关卡里的实例细节面板上，它要么不显示，要么显示为灰色只读状态。

UCLASS() class AWeaponBase : public AActor { GENERATED_BODY() public: UPROPERTY(EditDefaultsOnly, Category = "Weapon") float BaseDamage = 30.0f; };

我一般用EditDefaultsOnly放两类东西：一类是全局平衡参数，比如武器基础伤害、最大血量、攻击CD，这类数据不希望每个实例出现不同版本；另一类是给策划/美术看的配置入口，让他们集中在蓝图默认值里调整，而不是跑到关卡里一个一个改。

这里有个实战经验：如果把一个原本应该全局统一的数值改成EditAnywhere，很快就会出现关卡里某个武器伤害是40、另一个还是30的情况。项目后期排查这种问题非常痛苦。所以我的原则是，能不用EditAnywhere就不用，先用EditDefaultsOnly守住边界，真有个体化需求再放开。

2.2 EditAnywhere：默认值和实例都能改

EditAnywhere是使用频率最高的一个说明符，因为它最直观：既能在类默认值里改，也能在关卡中选中任意实例后在细节面板里改。

UPROPERTY(EditAnywhere, Category = "NPC") FName CharacterName;

适合用EditAnywhere的场景往往是“这个变量天然需要每个对象不一样”。比如NPC名字、商店ID、路灯亮度、门锁编号。如果你做一个路灯类，每盏灯的亮度不同，那理所当然应该用EditAnywhere，否则所有路灯共享一个亮度，灯光效果会非常奇怪。

使用EditAnywhere要小心一个坑：它会让属性在所有实例上产生“覆盖值”。一旦你在某个实例上手动改过，这个值就存进了关卡存档里。之后如果类的默认值再做调整，这个实例不会跟着变，因为它的值已经被覆盖了。这一点我们在第五部分排查问题时会重点讲。

2.3 VisibleAnywhere：可以看到，但不在面板里直接编辑

VisibleAnywhere的意思是“细节面板上显示这个值，但不允许手动修改”。它适合运行时状态和调试信息。

UPROPERTY(VisibleAnywhere, Category = "State") int32 CurrentAmmo = 30;

当前血量、剩余弹药、AI状态、正在播放的动画名，这些数据都是运行中由代码算出来的。设计者需要看到它们来判断当前状态，但绝不应该手动在面板里改，否则运行时状态就会和逻辑脱节。

我自己特别喜欢给调试属性加VisibleAnywhere，因为查看问题非常方便。比如角色最近一次受到伤害的数值，如果只写UPROPERTY()而不加可见性，编辑器里看不到，调试时还得加日志；加上VisibleAnywhere后，运行中选中角色就能直接看到当前值，效率高很多。

注意一点：VisibleAnywhere只是编辑器维度，如果蓝图侧想读取这个变量，还需要配合BlueprintReadOnly，否则蓝图节点列表里依然找不到它。

2.4 VisibleDefaultsOnly：只在类默认值里显示，且不可编辑

VisibleDefaultsOnly相对冷门，但某些场景很好用。它的行为是：只在类默认值面板里显示这个属性，并且显示为只读，实例细节面板里完全看不到。

UPROPERTY(VisibleDefaultsOnly, Category = "Info") FName WeaponClassIdentifier;

什么时候用？我认为最合适的场景是：这个值是由其他配置或代码自动推导出来的类级信息，你希望蓝图设计者在类默认值里能看到，但不想让他们改，也不想在实例上刷存在感。比如根据伤害值自动生成的武器评级，或者某个Actor的碰撞体积描述。

对比一下：如果这个信息放在实例上也有显示价值，就选VisibleAnywhere；如果只属于类本身、实例显示反而干扰操作，就选VisibleDefaultsOnly。比如你放了一百个NPC在关卡里，每个NPC细节面板都显示一条相同的类标识，那纯属噪音，不如只在类默认值里看。

3. 蓝图访问权限：BlueprintReadWrite与BlueprintReadOnly

3.1 没有蓝图说明符，蓝图里根本看不到

我见过不少C++老手也会在这个地方翻车：以为变量声明成public，蓝图那边就能直接链接。实际上，蓝图反射系统只看UPROPERTY里有没有显式声明蓝图访问权限。

UPROPERTY(EditAnywhere) int32 PublicValue; // 编辑器里能改，但蓝图里没有任何节点

这种写法下，细节面板能编辑，但打开蓝图，变量列表里压根没有PublicValue。想让蓝图能使用这个变量，必须加上BlueprintReadWrite或BlueprintReadOnly中的任意一个。

UPROPERTY(EditAnywhere, BlueprintReadWrite) int32 PublicValue;

对，就是如此简单粗暴。public只是C++层面的访问权限，不会自动转化成蓝图访问权限。UE的反射系统要求你明确表态：这个变量到底要不要暴露给蓝图。

3.2 BlueprintReadWrite与BlueprintReadOnly的取舍

BlueprintReadWrite表示蓝图可以读取，也可以赋值。它会在右键变量时同时提供Get和Set两个节点。BlueprintReadOnly表示蓝图只能读取，右键时只有Get节点，你尝试连一个Set节点，蓝图编译器会直接报错。

UPROPERTY(BlueprintReadOnly, Category = "State") float CurrentHealth;

这里要重点纠正一个认知：BlueprintReadOnly不是说“C++里不能改”，也不是说“编辑器里不能改”。它只限制蓝图的Set操作，C++侧的构造函数、成员函数完全可以直接修改这个变量。

关于BlueprintReadWrite，我的建议是能不用就不用。暴露一个变量的Set权限，等于允许任意蓝图在任何时间把值改成任何数值。一旦项目变大，蓝图节点会被乱改得面目全非，查都无从查起。如果你只是希望蓝图在执行某个逻辑时修改内部数据，更好的做法是提供一个自定义函数，在函数内部做校验和边界判断，而不是直接把数据托管给蓝图。

3.3 常用组合速查表

把编辑权限和蓝图权限两两组合，最常见的有效搭配大概有六种，我整理成了一张表，方便你开发时对照复制。

注意，这张表没有覆盖所有合法组合，但覆盖了绝大多数项目里用得到的情况。额外说一句，还有EditInstanceOnly和VisibleInstanceOnly这类说明符，它们允许“只看实例、不看类默认值”，属于更细分的控制，标题里没列，但原理完全一致，理解了上面两套维度就不难再推。

4. 实操选型思路：我到底该用哪一组

4.1 最小权限原则

我写属性有一条不成文的规矩：默认从严，需求驱动放开。每声明一个变量，先问自己三个问题。

第一，这个值需要在细节面板上被看见吗？如果不需要，就不要加Edit或Visible系列，用普通UPROPERTY()就行。第二，如果需要看见，是需要被改，还是仅仅展示？需要被改再考虑EditAnywhere，否则VisibleAnywhere。第三，蓝图侧需要读还是写？能只读就只读，能不让蓝图碰就不加蓝图说明符。

这套“最小权限原则”在团队协作里特别有价值。你多暴露一个权限，就等于多给未来埋一个坑。权限收得越紧，策划、蓝图和美术就越不容易在引擎里把配置改出奇怪的状态。

4.2 实战：武器类常用配置

拿一个最简单的武器类演示一下真正能落到代码里的组合。

UCLASS() class AWeaponBase : public AActor { GENERATED_BODY() public: AWeaponBase(); // 基础伤害：策划在类默认值里统一调整，蓝图只能读取 UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Weapon") float BaseDamage = 30.0f; // 武器昵称：每把武器实例都可以独立命名 UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Weapon") FName WeaponDisplayName; // 当前弹药：运行时由C++更新，蓝图只能读取，不能在面板手动改 UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "State") int32 CurrentAmmo = 100; };

BaseDamage用EditDefaultsOnly + BlueprintReadOnly，因为一个武器大类的基础伤害通常统一，不希望每个实例不同；WeaponDisplayName用EditAnywhere + BlueprintReadWrite，因为每把武器实例名字不同，蓝图也能动态改名；CurrentAmmo用VisibleAnywhere + BlueprintReadOnly，因为它不需要也不允许手动配置，蓝图只需要读取弹药数来更新UI。

这个例子基本覆盖了80%常见需求。你会发现，真正困难的部分其实不是记语法，而是先想清楚每个数据在项目里的角色。

4.3 实战：NPC与交互物

NPC场景更能体现“同一种属性在不同项目里选型不同”的道理。比如NPC血量，如果你的NPC分为很多种类，每个种类有不同基础血量，那血量上限更适合EditDefaultsOnly + BlueprintReadOnly，分类配置而不是逐个NPC配置；如果要做“这只NPC比那只血厚”的效果，才需要用EditAnywhere支持实例差异。

再比如NPC对话次数。如果这个次数只由C++逻辑维护，蓝图不需要改变，就选VisibleAnywhere + BlueprintReadOnly；如果对话系统是蓝图做的，蓝图每次回答完要自增次数，那应该选VisibleAnywhere + BlueprintReadWrite。同样的变量名，因为在不同项目里使用方式不同，说明符组合也会不同。

这里体现的核心方法论是：先定数据流，再定说明符。你的数据是从编辑器流向代码，还是从代码流向界面？谁有权修改它？修改的时机是什么？这些问题想清楚，选型就是顺水推舟。

4.4 类默认值面板和实例面板的操作区分

使用EditDefaultsOnly后，很多新人会问“为什么我在关卡里选中Actor，属性还是不能改？”这是因为你看的是实例细节面板，需要回到蓝图编辑器的“Class Defaults”面板。

操作方法是：打开蓝图编辑器，工具栏上有一个“Class Defaults”按钮，或者点击左上角的选集下拉框，把“Class Defaults”作为当前编辑对象。此时看到的才是CDO。类默认值面板里会显示标了EditDefaultsOnly和EditAnywhere的属性，而VisibleDefaultsOnly属性也会显示，只是呈灰色。

在关卡里选中一个Actor实例，细节面板会看到该实例的属性。如果属性值后面出现一个圆点或箭头，说明这个值相对于类默认值已经被覆盖过。右键属性名，可以执行“Reset to Default”，让实例重新跟随类默认值。这个操作在排查配置漂移时非常有用，后面会细说。

5. 常见问题与排查技巧实录

5.1 改了类默认值，已放置的实例没变化

这是群里被问烂的问题：我用EditDefaultsOnly改了基础伤害，也保存了，但关卡里已经存在的武器实例伤害没变，只有新拖出来的实例是新数值。

原因通常在于实例上早已存在覆盖值。你在某次操作中，可能直接用EditAnywhere或者曾经在实例面板改过这个属性，甚至只是还没保存时拖入实例又撤销过，都可能在关卡存档里留有diff记录。实例加载时会优先使用自己序列化出来的属性值，而不是重新拉取CDO。

解决办法很直接：选中那个实例，在细节面板里找到该属性，右键执行“Reset to Default”。如果整个类的多个实例都有类似问题，可以用编辑器批量选中Actor，然后在细节面板右上角选择“Reset All”相关操作。需要注意，如果你改了类默认值，而实例没有任何覆盖记录，修改通常会自动生效，所以遇到“不生效”时先检查覆盖标记。

5.2 蓝图里报错“Cannot modify BlueprintReadOnly”

最常见报错还是“Cannot modify this property because it is BlueprintReadOnly”之类。发生原因很直白：你给属性加了BlueprintReadOnly，却在蓝图里拖了Set节点。

我有一次在项目里看到同事为了在蓝图里重置弹药量，对着一个BlueprintReadOnly变量愣是拖出一个Set节点，然后编译不过，直接用流程节点绕过，结果越绕越乱。正确做法是想清楚：如果蓝图确实需要改这个值，那就把说明符改成BlueprintReadWrite；如果不想暴露写入权限，就应该给蓝图提供一个公开函数，例如TrySetAmmo(int32 NewAmmo)，在函数里做数值合法性判断，而不是直接开放数据写入。

一般情况下我倾向于后者。因为BlueprintReadWrite的Set节点没有任何拦截能力，蓝图里可以随便赋一个负数，而自定义函数可以拦住这些越界值。

5.3 细节面板里看不到变量

如果你加了EditAnywhere，但细节面板里死活找不到这个变量，可以从几个方向排查。

先检查是否加了Edit或Visible系列说明符，这最基础。再看属性所属的Category，如果细节面板顶部有搜索过滤，搜索你的Category名称，能帮你快速定位。还要确认自己选中的是“Class Defaults”还是“实例”，因为VisibleDefaultsOnly属性只在类默认值里显示，实例里看不到不算bug。

有个容易忽略的点：某些属性类型本身不支持编辑器反射，比如部分容器类型或带复杂泛型的嵌套类型，虽然UPROPERTY标记了，但编辑器UI不一定渲染。这种情况通常需要改成支持的类型，或者用FText、FName等序列化简单的类型做配置。最后，检查类本身是不是UObject派生且包含GENERATED_BODY()，缺少这个宏时编辑器反射会失效。

5.4 C++构造函数里赋值和默认值面板冲突

这也是一个经典陷阱：你在构造函数里写CurrentAmmo = 30，同时UPROPERTY声明后面也写了= 30，然后在类默认值面板里改成100保存。你会发现运行起来永远是构造函数里的30，面板值不是100。

原因是CDO生成时会执行构造函数，UPROPERTY声明处的初始化值发生在构造函数之前，之后构造函数又覆盖了一次。所以如果你既在构造函数里赋值又在声明处给默认值，实际生效的是构造函数里的值，面板上虽然显示100，但运行时可能又被构造函数逻辑覆盖。

我的习惯是：属性默认值统一写在UPROPERTY声明处，构造函数里除非有计算逻辑，否则不要反复设置基础值。这样至少能确保CDO生成时面板展示的值就是最终值，减少“面板显示和实际运行不一致”的困惑。

最后再说一点个人体会。我踩过最多次坑的都来自权限放得太宽，后来养成了“先从严，再加权限”的习惯，项目里配置错乱和蓝图乱改的情况确实少了很多。如果你刚接触这套说明符，不用急着把所有组合背下来，拿到一个新变量时，按“需不需要显示、需不需要编辑、蓝图需不需要读写”的顺序捋一遍，答案自己就出来了。最后分享一个小技巧：每个UPROPERTY都写上清晰的Category和ToolTip说明，哪怕多花半分钟，一个月后再回来看这个类，你会感谢当时那个耐心的自己。