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

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

OS.shell_open

定义

OS.shell_open 用来用系统默认程序打开一个链接或文件——就像用户在资源管理器里双击了一个文件，或者点击了一个网页链接。

打个比方：你给朋友发了一条消息说"看看这个网页 www.example.com"。朋友需要自己打开浏览器、输入网址才能看到。ShellOpen() 就相当于你直接帮朋友点开了这个链接，系统会自动用默认浏览器打开它。

在游戏开发中，这个功能常用于：打开官方网站、打开反馈/支持页面、在文件管理器中打开存档目录、用默认图片查看器打开截图等。

函数签名

C#

// OS.ShellOpen 用系统默认程序打开链接或文件
public static Error ShellOpen(string uri)

GDScript

static func shell_open(uri: String) -> int

参数说明

参数	类型	必需	说明
uri	String	是	要打开的 URI（网址）或文件路径。支持 http/https 网址、本地文件路径等

返回值

Error (int) —— 返回 Error.Ok（值为 0）表示请求已发送成功。注意：这只表示系统接受了打开请求，不代表目标程序已经成功打开。

代码示例

基础用法：打开网页链接

C#

using Godot;

public partial class MyScene : Node
{
    public override void _Ready()
    {
        // 用默认浏览器打开官网
        Error result = OS.ShellOpen("https://www.godotengine.org");
        GD.Print($"打开结果: {result}");
        // 运行结果: 打开结果: Ok（浏览器自动打开 Godot 官网）
    }
}

GDScript

extends Node

func _ready():
    # 用默认浏览器打开官网
    var result = OS.shell_open("https://www.godotengine.org")
    print("打开结果: ", result)
    # 运行结果: 打开结果: 0（浏览器自动打开 Godot 官网）

实际场景：游戏中的"联系我们"按钮

C#

using Godot;

public partial class AboutMenu : Control
{
    public void OnWebsiteButtonPressed()
    {
        OS.ShellOpen("https://www.evocosmos.com");
        GD.Print("已打开官方网站");
        // 运行结果: 已打开官方网站
    }

    public void OnFeedbackButtonPressed()
    {
        OS.ShellOpen("mailto:support@evocosmos.com?subject=游戏反馈");
        GD.Print("已打开邮件客户端");
        // 运行结果: 已打开邮件客户端（系统默认邮件程序）
    }

    public void OnDiscordButtonPressed()
    {
        OS.ShellOpen("https://discord.gg/example");
        GD.Print("已打开 Discord 邀请链接");
        // 运行结果: 已打开 Discord 邀请链接
    }
}

GDScript

extends Control

func on_website_button_pressed():
    OS.shell_open("https://www.evocosmos.com")
    print("已打开官方网站")
    # 运行结果: 已打开官方网站

func on_feedback_button_pressed():
    OS.shell_open("mailto:support@evocosmos.com?subject=游戏反馈")
    print("已打开邮件客户端")
    # 运行结果: 已打开邮件客户端（系统默认邮件程序）

func on_discord_button_pressed():
    OS.shell_open("https://discord.gg/example")
    print("已打开 Discord 邀请链接")
    # 运行结果: 已打开 Discord 邀请链接

进阶用法：在文件管理器中打开存档目录

C#

using Godot;

public partial class SaveManager : Control
{
    public void OnOpenSaveFolderPressed()
    {
        string saveDir = OS.GetUserDataDir();

        // 在文件管理器中打开存档目录
        // Windows 会打开资源管理器，Mac 会打开 Finder
        OS.ShellOpen(saveDir);

        GD.Print($"已打开存档目录: {saveDir}");
        // 运行结果: 已打开存档目录: C:\Users\Player\AppData\Roaming\MyGame
    }
}

GDScript

extends Control

func on_open_save_folder_pressed():
    var save_dir = OS.get_user_data_dir()

    # 在文件管理器中打开存档目录
    # Windows 会打开资源管理器，Mac 会打开 Finder
    OS.shell_open(save_dir)

    print("已打开存档目录: ", save_dir)
    # 运行结果: 已打开存档目录: C:\Users\Player\AppData\Roaming\MyGame

注意事项

• 非阻塞调用：ShellOpen() 不会等待目标程序打开或执行完毕，它会立即返回。
• 返回值只表示"请求已发送"：即使链接无效或文件不存在，返回值也可能为 Ok。实际是否打开成功取决于系统。
• 安全考虑：不要将未经验证的用户输入直接传给 ShellOpen()，避免打开恶意链接。
• 各平台行为不同：Windows 用 cmd /c start，macOS 用 open，Linux 用 xdg-open。Godot 会自动处理这些差异。
• Web 平台限制：在浏览器中运行时，只能打开 http/https 链接，不能打开本地文件。