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

AudioStreamPlayer.stop

定义

AudioStreamPlayer.stop 就是让正在播放的音频停下来。就像你按下音乐播放器上的"停止"按钮一样，声音立即停止。

打个比方：play 是按下播放键，stop 就是按下停止键。停止后播放位置会回到开头，下次调用 play() 会从头播放。

在实际游戏开发中，你需要用 stop 来在合适的时机停止声音：比如进入战斗时停止背景音乐、关闭菜单时停止菜单音效、或者暂停游戏时暂停背景音乐。

函数签名

C#

public void Stop()

GDScript

func stop() -> void

参数说明

参数	类型	必需	说明
无	—	—	此方法没有参数

返回值

无返回值（void）。调用后音频立即停止播放。

代码示例

基础用法：停止播放

C#

var musicPlayer = GetNode<AudioStreamPlayer>("MusicPlayer");

// 停止播放
musicPlayer.Stop();
// 运行结果: 音乐立即停止，播放位置回到开头

GDScript

var music_player = $MusicPlayer as AudioStreamPlayer

# 停止播放
music_player.stop()
# 运行结果: 音乐立即停止，播放位置回到开头

实际场景：切换背景音乐

C#

using Godot;

public partial class MusicManager : Node
{
    private AudioStreamPlayer _musicPlayer;

    public override void _Ready()
    {
        _musicPlayer = GetNode<AudioStreamPlayer>("MusicPlayer");
    }

    public void SwitchToBattleMusic()
    {
        // 先停止当前音乐
        _musicPlayer.Stop();
        // 运行结果: 当前音乐停止

        // 加载并播放战斗音乐
        var battleMusic = GD.Load<AudioStream>("res://assets/audio/battle_bgm.ogg");
        _musicPlayer.Stream = battleMusic;
        _musicPlayer.Play();
        // 运行结果: 战斗音乐开始播放
    }

    public void SwitchToMenuMusic()
    {
        _musicPlayer.Stop();

        var menuMusic = GD.Load<AudioStream>("res://assets/audio/menu_bgm.ogg");
        _musicPlayer.Stream = menuMusic;
        _musicPlayer.Play();
        // 运行结果: 菜单音乐开始播放
    }
}

GDScript

extends Node

@onready var _music_player: AudioStreamPlayer = $MusicPlayer

func switch_to_battle_music():
    # 先停止当前音乐
    _music_player.stop()
    # 运行结果: 当前音乐停止

    # 加载并播放战斗音乐
    var battle_music = load("res://assets/audio/battle_bgm.ogg") as AudioStream
    _music_player.stream = battle_music
    _music_player.play()
    # 运行结果: 战斗音乐开始播放

func switch_to_menu_music():
    _music_player.stop()

    var menu_music = load("res://assets/audio/menu_bgm.ogg") as AudioStream
    _music_player.stream = menu_music
    _music_player.play()
    # 运行结果: 菜单音乐开始播放

进阶用法：带淡出效果停止音乐

C#

using Godot;

public partial class FadingMusicPlayer : Node
{
    private AudioStreamPlayer _musicPlayer;
    private bool _isFadingOut = false;
    private float _fadeSpeed = 10.0f;

    public override void _Ready()
    {
        _musicPlayer = GetNode<AudioStreamPlayer>("MusicPlayer");
    }

    public void StopWithFadeOut()
    {
        _isFadingOut = true;
        // 运行结果: 开始淡出，音量逐渐降低直到静音后停止
    }

    public override void _Process(double delta)
    {
        if (_isFadingOut && _musicPlayer.Playing)
        {
            _musicPlayer.VolumeDb -= _fadeSpeed * (float)delta;

            if (_musicPlayer.VolumeDb <= -40.0f)
            {
                _musicPlayer.Stop();
                _musicPlayer.VolumeDb = 0.0f; // 恢复默认音量
                _isFadingOut = false;
                GD.Print("音乐已淡出并停止");
                // 运行结果: 音量降到最低后自动停止，音量恢复默认值
            }
        }
    }
}

GDScript

extends Node

@onready var _music_player: AudioStreamPlayer = $MusicPlayer
var _is_fading_out: bool = false
var _fade_speed: float = 10.0

func stop_with_fade_out():
    _is_fading_out = true
    # 运行结果: 开始淡出，音量逐渐降低直到静音后停止

func _process(delta):
    if _is_fading_out and _music_player.playing:
        _music_player.volume_db -= _fade_speed * delta

        if _music_player.volume_db <= -40.0:
            _music_player.stop()
            _music_player.volume_db = 0.0  # 恢复默认音量
            _is_fading_out = false
            print("音乐已淡出并停止")
            # 运行结果: 音量降到最低后自动停止，音量恢复默认值

注意事项

• 停止后播放位置重置：调用 Stop() 后，播放位置回到 0。如果想暂停而不是停止（保持播放位置），应该使用 StreamPaused = true 属性。
• 对未在播放的播放器调用是安全的：如果音频本来就没有在播放，调用 Stop() 不会有任何效果，也不会报错。
• 不会触发 finished 信号：手动调用 Stop() 不会触发 finished 信号。只有音频自然播放到结尾时才会触发。
• Stop vs StreamPaused：Stop() 完全停止并重置位置；StreamPaused = true 只是暂停，保持当前播放位置，之后恢复播放会从暂停处继续。