---

name: godot-4-migration description: "Godot 3.x 项目迁移到 Godot 4（GDScript 2.0）的专业指南，涵盖语法变更、Tween 和导出。" risk: safe source: community date_added: "2026-02-27"

Godot 4 迁移指南

概述

为从 Godot 3.x 过渡到 Godot 4 的开发者提供的关键指南。此技能专注于 GDScript 2.0 的主要语法变更、新的 Tween 系统和 export 注解更新。

何时使用此技能

• 将 Godot 3 项目移植到 Godot 4 时使用。
• 升级后遇到语法错误时使用。
• 替换已弃用的节点（如 Tween 节点 vs create_tween）时使用。
• 将 export 变量更新为 @export 注解时使用。

关键变更

1. 注解（@）

Godot 4 使用 @ 修饰行为的关键字。

• export var x -> @export var x
• onready var y -> @onready var y
• tool -> @tool（文件顶部）

2. Setter 和 Getter

属性现在内联定义 setter/getter。

Godot 3：

var health setget set_health, get_health

func set_health(value):
    health = value

Godot 4：

var health: int:
    set(value):
        health = value
        emit_signal("health_changed", health)
    get:
        return health

3. Tween 系统

Tween 节点已弃用。在代码中使用 create_tween()。

Godot 3：

$Tween.interpolate_property(...)
$Tween.start()

Godot 4：

var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2(100, 100), 1.0)
tween.parallel().tween_property($Sprite, "modulate:a", 0.0, 1.0)

4. 信号连接

不推荐基于字符串的连接。使用 callable。

Godot 3：

connect("pressed", self, "_on_pressed")

Godot 4：

pressed.connect(_on_pressed)