最后更新日期：2026-04-16

最后同步日期：2026-04-15 | Godot 官方原文 — @export_node_path

@export_node_path

定义

@export_node_path 是 GDScript 中的一个注解（annotation），用来在 Godot 编辑器的检查器面板中暴露一个节点路径选择器。使用这个注解后，你可以在编辑器中直接从场景树里选择一个节点，节点路径会以 NodePath 的形式保存在变量中。

简单说，就像在你的脚本里开了一个"拖拽位"，你可以从场景树里拖一个节点到检查器面板的这个位置，脚本就知道你要操作哪个节点了。比起硬编码节点路径（比如 "Sprite2D"），使用 @export_node_path 更灵活，不容易出错。

在 C# 中，推荐直接使用 [Export] public NodePath ExTargetPath; 的形式，或者更常见的做法是直接导出节点类型。

语法

C#

// 导出节点路径
[Export] public NodePath ExTargetNodePath = new NodePath();

// 导出带类型过滤的节点路径
[Export(PropertyHint.NodeType, "Sprite2D")]
public NodePath ExSpritePath = new NodePath();

GDScript

# 导出节点路径（不限制类型）
@export_node_path var ex_target_path: NodePath

# 导出节点路径（限制只能选择特定类型的节点）
@export_node_path("Sprite2D", "AnimatedSprite2D") var ex_sprite_path: NodePath

# 限制为 3D 节点
@export_node_path("Node3D", "CharacterBody3D") var ex_body_path: NodePath

参数说明

参数	类型	必需	说明
类型过滤器	String...	否	一系列节点类型名称，用于限制可选的节点类型。如果不传，则可以选择任何节点

返回值

@export_node_path 是一个注解，没有返回值。变量的值是一个 NodePath 对象，代表场景树中某个节点的路径。

代码示例

C#

using Godot;

public partial class TriggerZone : Area3D
{
    // ===== 基础用法：导出节点路径 =====
    [Export] public NodePath ExTargetDoorPath;

    private Node3D _targetDoor;

    public override void _Ready()
    {
        if (!ExTargetDoorPath.IsEmpty)
        {
            _targetDoor = GetNode<Node3D>(ExTargetDoorPath);
            GD.Print($"目标门: {_targetDoor.Name}");
        }
    }
    // 运行结果: 目标门: Door_Main


    // ===== 实际场景：灵活引用场景中的节点 =====
    [Export] public NodePath ExSpawnPointPath;
    [Export] public NodePath ExCameraPath;
    [Export] public NodePath ExAudioPlayerPath;

    private Marker3D _spawnPoint;
    private Camera3D _camera;
    private AudioStreamPlayer _audioPlayer;

    public override void _Ready()
    {
        if (!ExSpawnPointPath.IsEmpty)
        {
            _spawnPoint = GetNode<Marker3D>(ExSpawnPointPath);
            GD.Print($"出生点位置: {_spawnPoint.Position}");
        }

        if (!ExCameraPath.IsEmpty)
        {
            _camera = GetNode<Camera3D>(ExCameraPath);
        }
    }
    // 运行结果: 出生点位置: (0, 1, 0)


    // ===== 进阶用法：动态获取节点并操作 =====
    [Export(PropertyHint.NodeType, "Light3D")]
    public NodePath ExLightPath = new NodePath();

    [Export] public NodePath ExFollowTargetPath = new NodePath();

    private Light3D _light;
    private Node3D _followTarget;

    public void SetupConnections()
    {
        if (!ExLightPath.IsEmpty)
        {
            _light = GetNode<Light3D>(ExLightPath);
            _light.LightColor = Colors.Red;
            GD.Print($"已设置灯光颜色: {_light.LightColor}");
        }

        if (!ExFollowTargetPath.IsEmpty)
        {
            _followTarget = GetNode<Node3D>(ExFollowTargetPath);
            GD.Print($"跟随目标: {_followTarget.Name}，位置: {_followTarget.GlobalPosition}");
        }
    }
    // 运行结果: 已设置灯光颜色: #ff0000
    // 运行结果: 跟随目标: Player，位置: (5, 0, 3)
}

GDScript

extends Area3D

# ===== 基础用法：导出节点路径 =====
@export_node_path var ex_target_door_path: NodePath

func _ready():
    if ex_target_door_path:
        var target_door := get_node(ex_target_door_path) as Node3D
        print("目标门: %s" % target_door.name)
# 运行结果: 目标门: Door_Main


# ===== 实际场景：灵活引用场景中的节点 =====
@export_node_path var ex_spawn_point_path: NodePath
@export_node_path var ex_camera_path: NodePath
@export_node_path var ex_audio_player_path: NodePath

func setup_references():
    if ex_spawn_point_path:
        var spawn_point := get_node(ex_spawn_point_path) as Marker3D
        print("出生点位置: %s" % spawn_point.position)

    if ex_camera_path:
        var camera := get_node(ex_camera_path) as Camera3D
        camera.current = true
# 运行结果: 出生点位置: (0, 1, 0)


# ===== 进阶用法：带类型过滤的节点路径 =====
@export_node_path("Light3D") var ex_light_path: NodePath
@export_node_path("Node3D", "CharacterBody3D") var ex_follow_target_path: NodePath

func setup_connections():
    if ex_light_path:
        var light := get_node(ex_light_path) as Light3D
        light.light_color = Color.RED
        print("已设置灯光颜色: %s" % light.light_color)

    if ex_follow_target_path:
        var target := get_node(ex_follow_target_path) as Node3D
        print("跟随目标: %s，位置: %s" % [target.name, target.global_position])
# 运行结果: 已设置灯光颜色: #ff0000
# 运行结果: 跟随目标: Player，位置: (5, 0, 3)

注意事项

• @export_node_path 的变量类型应该是 NodePath。
• 路径是相对路径：选中的节点路径是相对于当前节点在场景树中的位置计算的（当然也可以选择绝对路径）。
• 类型过滤器只是编辑器中的显示限制，不会阻止你在代码中获取错误类型的节点。获取后应使用 as 进行类型检查。
• 如果目标节点被移动或删除，保存的路径可能失效，代码中应做 null 检查。
• 在 GDScript 中，也可以用 @export var ex_path: NodePath 的普通导出形式，但 @export_node_path 提供了类型过滤功能，编辑器体验更好。
• C# 中可以直接使用 [Export] public NodePath ExPath;，配合 [Export(PropertyHint.NodeType, "类型")] 做类型过滤。