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

replace

定义

replace 用来把字符串中的某一段内容全部替换成另一段内容。你可以把它想象成"查找并替换"功能——就像 Word 里的那个功能一样：找到所有"旧词"，全部换成"新词"。

比如把 "I love cats" 里的 "cats" 替换成 "dogs"，就变成了 "I love dogs"。

函数签名

C#

// Godot.StringExtensions 方法
public static string Replace(this string instance, string what, string forwhat)

GDScript

func replace(what: String, forwhat: String) -> String

参数说明

参数	类型	必需	说明
what	string / String	是	要被替换的原始子字符串（即"旧词"）
forwhat	string / String	是	替换后的新子字符串（即"新词"）

返回值

类型： string / String

返回替换后的新字符串。原字符串不会被修改。如果没找到 what，则原样返回。

代码示例

基础用法

C#

using Godot;

public partial class ReplaceExample : Node
{
    public override void _Ready()
    {
        string text = "I love cats, cats are great!";

        // 把所有 "cats" 替换成 "dogs"
        string result = text.Replace("cats", "dogs");
        GD.Print(result);
        // 运行结果: I love dogs, dogs are great!

        // 要替换的内容不存在时，原样返回
        string noMatch = text.Replace("birds", "fish");
        GD.Print(noMatch);
        // 运行结果: I love cats, cats are great!
    }
}

GDScript

extends Node

func _ready():
    var text := "I love cats, cats are great!"

    # 把所有 "cats" 替换成 "dogs"
    var result := text.replace("cats", "dogs")
    print(result)
    # 运行结果: I love dogs, dogs are great!

    # 要替换的内容不存在时，原样返回
    var no_match := text.replace("birds", "fish")
    print(no_match)
    # 运行结果: I love cats, cats are great!

实际场景：本地化文本模板处理

C#

using Godot;

public partial class LocalizationHelper : Node
{
    public override void _Ready()
    {
        string template = "欢迎 {player}！你在 {map} 获得了 {item}。";

        // 逐个替换占位符
        string result = template
            .Replace("{player}", "勇者")
            .Replace("{map}", "龙之谷")
            .Replace("{item}", "传说之剑");

        GD.Print(result);
        // 运行结果: 欢迎 勇者！你在 龙之谷 获得了 传说之剑。

        // 清理多余的空白字符
        string messy = "  Hello   World  ";
        string cleaned = messy.Replace("  ", " ").StripEdges();
        GD.Print(cleaned);
        // 运行结果: Hello World
    }
}

GDScript

extends Node

func _ready():
    var template := "欢迎 {player}！你在 {map} 获得了 {item}。"

    # 逐个替换占位符
    var result := template \
        .replace("{player}", "勇者") \
        .replace("{map}", "龙之谷") \
        .replace("{item}", "传说之剑")

    print(result)
    # 运行结果: 欢迎 勇者！你在 龙之谷 获得了 传说之剑。

    # 清理多余的空白字符
    var messy := "  Hello   World  "
    var cleaned := messy.replace("  ", " ").strip_edges()
    print(cleaned)
    # 运行结果: Hello World

进阶用法：批量替换与敏感词过滤

C#

using Godot;
using System.Collections.Generic;

public partial class ReplaceAdvanced : Node
{
    public override void _Ready()
    {
        // 敏感词过滤
        string chat = "你这个 badword1，真是 badword2！";
        var bannedWords = new Dictionary<string, string>
        {
            { "badword1", "***" },
            { "badword2", "***" }
        };

        foreach (var pair in bannedWords)
        {
            chat = chat.Replace(pair.Key, pair.Value);
        }
        GD.Print(chat);
        // 运行结果: 你这个 ***，真是 ***！

        // 空字符串替换 = 删除
        string url = "https://www.example.com/path";
        string cleanUrl = url.Replace("https://", "").Replace("www.", "");
        GD.Print(cleanUrl);
        // 运行结果: example.com/path

        // 注意：replace 是全部替换，区分大小写
        string text = "Hello hello HELLO";
        GD.Print(text.Replace("hello", "hi"));
        // 运行结果: Hello hi HELLO（只替换了小写的 hello）
    }
}

GDScript

extends Node

func _ready():
    # 敏感词过滤
    var chat := "你这个 badword1，真是 badword2！"
    var banned_words := {
        "badword1": "***",
        "badword2": "***"
    }

    for word in banned_words:
        chat = chat.replace(word, banned_words[word])
    print(chat)
    # 运行结果: 你这个 ***，真是 ***！

    # 空字符串替换 = 删除
    var url := "https://www.example.com/path"
    var clean_url := url.replace("https://", "").replace("www.", "")
    print(clean_url)
    # 运行结果: example.com/path

    # 注意：replace 是全部替换，区分大小写
    var text := "Hello hello HELLO"
    print(text.replace("hello", "hi"))
    # 运行结果: Hello hi HELLO（只替换了小写的 hello）

注意事项

1. 全部替换：replace 会替换字符串中所有匹配到的子字符串，不是只替换第一个。如果只想替换第一个，GDScript 中可以使用 replacen（C# 中为 ReplaceN，但 Godot C# 目前无此扩展方法，需自行实现）。
2. 区分大小写：replace 是区分大小写的。"Hello".Replace("hello", "hi") 不会发生任何替换。如果需要不区分大小写，可以先转为统一大小写再替换。
3. 不修改原字符串：字符串是不可变的，replace 返回一个新字符串，原字符串保持不变。
4. 空字符串替换等于删除：如果把 forwhat 设为空字符串 ""，效果等同于删除所有匹配的内容。
5. 替换不会递归：替换完成后不会对结果再次扫描替换。比如 "aaa".Replace("aa", "a") 返回 "aa"，而不是 "a"。
6. C# 中的 string.Replace()：C# 自带的 string.Replace() 和 Godot 的 Replace 扩展方法功能完全一致，可以互换使用。