最后同步日期：2026-04-15 | Godot 官方原文 — SceneTree.change_scene_to_file

SceneTree.change_scene_to_file

定义

change_scene_to_file 就像电视机换频道——你告诉游戏"现在不要显示这个画面了，换成另一个画面"。它会卸载当前正在运行的场景（连根拔起），然后加载一个新的场景文件来替换它。

打个比方：你正在看一部电影，突然想换另一部。于是你把当前电影关掉，放入新碟片，从头开始播放。change_scene_to_file 做的就是这件事——把当前场景整个换掉，换成你指定的新场景。

在游戏开发中，这是最常见的场景切换方式：从主菜单进入游戏关卡、从关卡回到主菜单、进入过场动画等等。

函数签名

C#

public Error ChangeSceneToFile(string path)

GDScript

func change_scene_to_file(path: String) -> Error

参数说明

参数	类型	必需	说明
path	String	是	新场景文件的路径，例如 "res://levels/level_01.tscn"。使用 res:// 开头表示项目根目录

返回值

Error 枚举——返回场景切换的结果状态：

返回值	含义
Ok	切换成功
CantOpen	无法打开指定的场景文件（路径错误或文件不存在）
CantCreate	无法创建场景实例

代码示例

基础用法：切换到另一个场景

C#

public override void _Ready()
{
    // 从当前场景切换到"主菜单"场景
    Error result = GetTree().ChangeSceneToFile("res://scenes/main_menu.tscn");

    if (result == Error.Ok)
    {
        GD.Print("场景切换成功！");
    }
    else
    {
        GD.Print($"场景切换失败，错误码: {result}");
    }
    // 运行结果（场景文件存在时）: 场景切换成功！
    // 运行结果（路径错误时）: 场景切换失败，错误码: CantOpen
}

GDScript

func _ready():
    # 从当前场景切换到"主菜单"场景
    var result = get_tree().change_scene_to_file("res://scenes/main_menu.tscn")

    if result == OK:
        print("场景切换成功！")
    else:
        print("场景切换失败，错误码: %s" % result)
    # 运行结果（场景文件存在时）: 场景切换成功！
    # 运行结果（路径错误时）: 场景切换失败，错误码: 13

实际场景：通过按钮从主菜单进入游戏

C#

using Godot;

public partial class MainMenu : Control
{
    public void OnPlayButtonPressed()
    {
        // 玩家点击"开始游戏"按钮，切换到第一关
        Error result = GetTree().ChangeSceneToFile("res://levels/level_01.tscn");

        if (result != Error.Ok)
        {
            GD.PrintErr("无法加载关卡场景！");
        }
    }

    public void OnSettingsButtonPressed()
    {
        // 切换到设置页面
        GetTree().ChangeSceneToFile("res://scenes/settings.tscn");
    }
}

GDScript

extends Control

func _on_play_button_pressed():
    # 玩家点击"开始游戏"按钮，切换到第一关
    var result = get_tree().change_scene_to_file("res://levels/level_01.tscn")

    if result != OK:
        push_error("无法加载关卡场景！")

func _on_settings_button_pressed():
    # 切换到设置页面
    get_tree().change_scene_to_file("res://scenes/settings.tscn")

进阶用法：带过渡动画的场景切换

C#

using Godot;

public partial class SceneTransition : CanvasLayer
{
    private ColorRect _fadeRect;
    private bool _isTransitioning = false;

    public override void _Ready()
    {
        // 创建一个全屏遮罩，用于淡入淡出效果
        _fadeRect = new ColorRect();
        _fadeRect.Color = new Color(0, 0, 0, 0); // 完全透明
        _fadeRect.SetAnchorsPreset(Control.LayoutPreset.FullRect);
        AddChild(_fadeRect);
    }

    public async void TransitionToScene(string scenePath)
    {
        if (_isTransitioning) return;
        _isTransitioning = true;

        // 第一步：淡出（屏幕逐渐变黑）
        var tween = GetTree().CreateTween();
        tween.TweenProperty(_fadeRect, "color:a", 1.0f, 0.5f);
        await ToSignal(tween, Tween.SignalName.Finished);

        // 第二步：在黑屏期间切换场景
        Error result = GetTree().ChangeSceneToFile(scenePath);
        // 运行结果: 场景已切换到新场景

        if (result != Error.Ok)
        {
            GD.PrintErr($"加载场景失败: {scenePath}");
            // 切换失败时淡回来
            var tweenBack = GetTree().CreateTween();
            tweenBack.TweenProperty(_fadeRect, "color:a", 0.0f, 0.3f);
            _isTransitioning = false;
            return;
        }

        // 第三步：淡入（黑屏逐渐消失）
        var tweenIn = GetTree().CreateTween();
        tweenIn.TweenProperty(_fadeRect, "color:a", 0.0f, 0.5f);
        await ToSignal(tweenIn, Tween.SignalName.Finished);

        _isTransitioning = false;
    }
}

GDScript

extends CanvasLayer

var _fade_rect: ColorRect
var _is_transitioning: bool = false

func _ready():
    # 创建一个全屏遮罩，用于淡入淡出效果
    _fade_rect = ColorRect.new()
    _fade_rect.color = Color(0, 0, 0, 0) # 完全透明
    _fade_rect.set_anchors_preset(Control.LayoutPreset.FULL_RECT)
    add_child(_fade_rect)

func transition_to_scene(scene_path: String):
    if _is_transitioning:
        return
    _is_transitioning = true

    # 第一步：淡出（屏幕逐渐变黑）
    var tween = get_tree().create_tween()
    tween.tween_property(_fade_rect, "color:a", 1.0, 0.5)
    await tween.finished

    # 第二步：在黑屏期间切换场景
    var result = get_tree().change_scene_to_file(scene_path)
    # 运行结果: 场景已切换到新场景

    if result != OK:
        push_error("加载场景失败: %s" % scene_path)
        # 切换失败时淡回来
        var tween_back = get_tree().create_tween()
        tween_back.tween_property(_fade_rect, "color:a", 0.0, 0.3)
        _is_transitioning = false
        return

    # 第三步：淡入（黑屏逐渐消失）
    var tween_in = get_tree().create_tween()
    tween_in.tween_property(_fade_rect, "color:a", 0.0, 0.5)
    await tween_in.finished

    _is_transitioning = false

注意事项

• 当前场景会被完全销毁：调用后，当前场景中的所有节点都会被释放（free），包括当前脚本所在的节点本身。所以不要在调用 ChangeSceneToFile 之后再访问当前场景的任何节点。
• 路径必须以 res:// 开头：res:// 代表项目的根目录，不是硬盘上的绝对路径。例如项目中有一个 levels/level_01.tscn 文件，路径就写成 "res://levels/level_01.tscn"。
• 不支持过渡动画：ChangeSceneToFile 是瞬间切换，没有内置的淡入淡出效果。如果需要过渡动画，需要自行实现（参见进阶用法示例）。
• 如果需要更精细的场景切换控制：可以使用 UnloadCurrentScene() 先卸载当前场景，再用 ChangeSceneToPacked() 加载预加载的场景实例。
• C# 差异：C# 中方法名用 PascalCase（ChangeSceneToFile），GDScript 中用 snake_case（change_scene_to_file）。