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

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

OS.execute

定义

OS.execute 用来在游戏运行时启动一个外部程序或命令——就像你在命令行里敲了一条命令然后按回车。

打个比方：你在写一封信，信里附上一张便条"请帮我打开计算器"。当收信人读到便条时，就会帮你把计算器打开。OS.Execute() 就是这张"便条"，告诉操作系统"帮我运行这个程序"。

在游戏开发中，这个功能常用于：启动外部工具（如语音聊天软件）、调用命令行工具处理文件、打开本地文档等。但要注意，它会阻塞当前线程直到外部程序执行完毕。

函数签名

C#

// OS.Execute 启动外部程序
public static int Execute(string path, string[] arguments, Godot.Collections.Array output = null, bool readStderr = false)

GDScript

func execute(path: String, arguments: PackedStringArray, output: Array = [], read_stderr: bool = false) -> int

参数说明

参数	类型	必需	说明
path	String	是	要执行的程序路径或命令名称
arguments	string[] / PackedStringArray	是	传给程序的命令行参数列表
output	Array	否	用于接收程序标准输出的数组（按行存储）
readStderr	bool	否	是否同时读取标准错误输出。默认 false

返回值

int —— 外部程序的退出码。通常 0 表示成功执行，非零值表示出错。

代码示例

基础用法：执行系统命令

C#

using Godot;
using Godot.Collections;

public partial class MyScene : Node
{
    public override void _Ready()
    {
        // Windows 上执行 dir 命令（列出当前目录文件）
        var output = new Array();
        int exitCode = OS.Execute("cmd", new string[] { "/c", "dir" }, output);

        GD.Print($"退出码: {exitCode}");
        // 运行结果: 退出码: 0
        GD.Print($"输出行数: {output.Count}");
        // 运行结果: 输出行数: 15（取决于目录内容）
    }
}

GDScript

extends Node

func _ready():
    # Windows 上执行 dir 命令（列出当前目录文件）
    var output = []
    var exit_code = OS.execute("cmd", ["/c", "dir"], output)

    print("退出码: ", exit_code)
    # 运行结果: 退出码: 0
    print("输出行数: ", output.size())
    # 运行结果: 输出行数: 15（取决于目录内容）

实际场景：获取 Git 版本信息

C#

using Godot;
using Godot.Collections;

public partial class VersionInfo : Node
{
    public override void _Ready()
    {
        var output = new Array();

        // 执行 git 命令获取当前提交的简短哈希
        int exitCode = OS.Execute("git", new string[] { "rev-parse", "--short", "HEAD" }, output);

        if (exitCode == 0 && output.Count > 0)
        {
            string commitHash = output[0].AsString().StripEdges();
            GD.Print($"当前 Git 提交: {commitHash}");
            // 运行结果: 当前 Git 提交: d08fb98
        }
        else
        {
            GD.Print("无法获取 Git 版本信息");
            // 运行结果: 无法获取 Git 版本信息
        }
    }
}

GDScript

extends Node

func _ready():
    var output = []

    # 执行 git 命令获取当前提交的简短哈希
    var exit_code = OS.execute("git", ["rev-parse", "--short", "HEAD"], output)

    if exit_code == 0 and output.size() > 0:
        var commit_hash = output[0].strip_edges()
        print("当前 Git 提交: ", commit_hash)
        # 运行结果: 当前 Git 提交: d08fb98
    else:
        print("无法获取 Git 版本信息")
        # 运行结果: 无法获取 Git 版本信息

进阶用法：获取程序输出结果

C#

using Godot;
using Godot.Collections;

public partial class ToolRunner : Node
{
    /// 调用外部工具并返回输出结果
    public string RunTool(string tool, string[] args)
    {
        var output = new Array();
        var stderr = new Array();

        int exitCode = OS.Execute(tool, args, output, readStderr: true);

        if (exitCode != 0)
        {
            GD.PrintErr($"工具执行失败，退出码: {exitCode}");
            return "";
        }

        // 将输出数组合并成字符串
        string result = "";
        foreach (var line in output)
        {
            result += line.AsString();
        }

        GD.Print($"工具输出: {result}");
        // 运行结果: 工具输出: （工具的实际输出内容）
        return result;
    }
}

GDScript

extends Node

## 调用外部工具并返回输出结果
func run_tool(tool: String, args: PackedStringArray) -> String:
    var output = []
    var stderr = []

    var exit_code = OS.execute(tool, args, output, true)

    if exit_code != 0:
        push_error("工具执行失败，退出码: " + str(exit_code))
        return ""

    # 将输出数组合并成字符串
    var result = ""
    for line in output:
        result += line

    print("工具输出: ", result)
    # 运行结果: 工具输出: （工具的实际输出内容）
    return result

注意事项

• 会阻塞当前线程：Execute() 会等外部程序执行完毕才返回。如果外部程序运行时间很长，游戏会卡住。对于长时间运行的任务，考虑使用线程或 OS.CreateProcess()（非阻塞版本）。
• 路径问题：在 Windows 上路径要用反斜杠或正斜杠，确保路径正确。建议使用绝对路径。
• 安全风险：不要把用户输入直接传给 Execute()，这可能导致命令注入攻击。
• 导出后可能受限：某些平台（如 Web、沙盒化的移动端）可能不允许执行外部程序。
• output 参数是引用传递：输出的内容会被追加到传入的数组中，记得每次调用前清空数组或传入新数组。