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

path_join

定义

path_join 用来把两个路径片段拼接成一个完整的路径。你可以把它想象成"把两段路连接起来"——它会自动处理中间的斜杠，确保不会出现双斜杠或缺少斜杠的问题。

比如 "res://assets".PathJoin("player.png") 会变成 "res://assets/player.png"，不管第一段末尾有没有 /，结果都是正确的。

函数签名

C#

// Godot.StringExtensions 方法
public static string PathJoin(this string instance, string file)

GDScript

func path_join(file: String) -> String

参数说明

参数	类型	必需	说明
file	string / String	是	要拼接到当前路径后面的路径片段或文件名

返回值

类型： string / String

返回拼接好的完整路径字符串，路径之间用 / 正确分隔。

代码示例

基础用法

C#

using Godot;

public partial class PathJoinExample : Node
{
    public override void _Ready()
    {
        // 基本拼接
        string path1 = "res://assets".PathJoin("player.png");
        GD.Print(path1);
        // 运行结果: res://assets/player.png

        // 前面已经有斜杠也没问题
        string path2 = "res://assets/".PathJoin("player.png");
        GD.Print(path2);
        // 运行结果: res://assets/player.png
    }
}

GDScript

extends Node

func _ready():
    # 基本拼接
    var path1 := "res://assets".path_join("player.png")
    print(path1)
    # 运行结果: res://assets/player.png

    # 前面已经有斜杠也没问题
    var path2 := "res://assets/".path_join("player.png")
    print(path2)
    # 运行结果: res://assets/player.png

实际场景：动态构建资源路径

C#

using Godot;

public partial class ResourcePathBuilder : Node
{
    [Export] public string ExResourceDir = "res://assets";

    public override void _Ready()
    {
        string characterName = "knight";
        string animationName = "idle";

        // 一层一层地拼接路径，非常清晰
        string basePath = ExResourceDir.PathJoin("characters");
        string characterPath = basePath.PathJoin(characterName);
        string animPath = characterPath.PathJoin("animations");
        string fullPath = animPath.PathJoin(animationName + ".tres");

        GD.Print(fullPath);
        // 运行结果: res://assets/characters/knight/animations/idle.tres
    }
}

GDScript

extends Node

@export var resource_dir := "res://assets"

func _ready():
    var character_name := "knight"
    var animation_name := "idle"

    # 一层一层地拼接路径，非常清晰
    var base_path := resource_dir.path_join("characters")
    var character_path := base_path.path_join(character_name)
    var anim_path := character_path.path_join("animations")
    var full_path := anim_path.path_join(animation_name + ".tres")

    print(full_path)
    # 运行结果: res://assets/characters/knight/animations/idle.tres

进阶用法：链式调用与批量构建

C#

using Godot;

public partial class PathJoinAdvanced : Node
{
    public override void _Ready()
    {
        string baseDir = "res://data";

        // 批量构建多个文件路径
        string[] subDirs = { "textures", "sounds", "scenes" };
        string[] files = { "bg.png", "click.wav", "menu.tscn" };

        for (int i = 0; i < subDirs.Length; i++)
        {
            string fullPath = baseDir.PathJoin(subDirs[i]).PathJoin(files[i]);
            GD.Print(fullPath);
        }
        // 运行结果:
        // res://data/textures/bg.png
        // res://data/sounds/click.wav
        // res://data/scenes/menu.tscn

        // 与 get_base_dir 配合：基于当前路径找同级文件
        string currentFile = "res://maps/level_01.tscn";
        string baseDir2 = currentFile.GetBaseDir();
        string nextLevel = baseDir2.PathJoin("level_02.tscn");
        GD.Print($"下一关路径: {nextLevel}");
        // 运行结果: 下一关路径: res://maps/level_02.tscn
    }
}

GDScript

extends Node

func _ready():
    var base_dir := "res://data"

    # 批量构建多个文件路径
    var sub_dirs := ["textures", "sounds", "scenes"]
    var files := ["bg.png", "click.wav", "menu.tscn"]

    for i in range(sub_dirs.size()):
        var full_path := base_dir.path_join(sub_dirs[i]).path_join(files[i])
        print(full_path)
    # 运行结果:
    # res://data/textures/bg.png
    # res://data/sounds/click.wav
    # res://data/scenes/menu.tscn

    # 与 get_base_dir 配合：基于当前路径找同级文件
    var current_file := "res://maps/level_01.tscn"
    var base_dir2 := current_file.get_base_dir()
    var next_level := base_dir2.path_join("level_02.tscn")
    print("下一关路径: " + next_level)
    # 运行结果: 下一关路径: res://maps/level_02.tscn

注意事项

1. 自动处理斜杠：path_join 会自动在两段路径之间添加 /，并且不会产生 //。无论前面的路径末尾是否有 /，结果都是正确的。
2. 仅处理字符串拼接：path_join 不会检查路径是否实际存在，它只做字符串拼接操作。
3. 不处理 .. 和 .：path_join 不会解析路径中的 ..（上级目录）和 .（当前目录）。如果需要规范化路径，可以结合 SimplifyPath（GDScript 中 simplify_path）使用。
4. 推荐使用此方法：不要手动拼接路径（如 dir + "/" + filename），因为容易出错。始终使用 path_join 来拼接路径，代码更健壮。
5. C# 替代方案：C# 的 System.IO.Path.Combine() 功能类似，但不识别 Godot 的 res:// 路径前缀。在 Godot 项目中推荐使用 PathJoin。