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

AudioStreamPlayer.play

定义

AudioStreamPlayer.play 就是让音频播放器开始播放声音。就像你按下音乐播放器上的"播放"按钮一样，调用这个方法后，之前加载好的音频（比如背景音乐、音效）就会开始播放。

打个比方：AudioStreamPlayer 就像一个随身听，play 就是按下播放键。你需要先把磁带（AudioStream）放进去，然后按下播放键，音乐就响起来了。

在实际游戏开发中，你需要用 play 来播放各种声音：角色攻击时的挥剑声、按钮点击时的"嗒"声、背景音乐循环播放等。

函数签名

C#

public void Play(float fromPosition = 0.0f)

GDScript

func play(from_position: float = 0.0) -> void

参数说明

参数	类型	必需	说明
fromPosition	float	否	从音频的哪个时间点（秒）开始播放，默认从 0（开头）开始

返回值

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

代码示例

基础用法：播放音效

C#

var sfxPlayer = GetNode<AudioStreamPlayer>("SFXPlayer");

// 从头开始播放音效
sfxPlayer.Play();
// 运行结果: 音效从头开始播放

// 从第 5 秒位置开始播放
sfxPlayer.Play(5.0f);
// 运行结果: 音效从第 5 秒处开始播放

GDScript

var sfx_player = $SFXPlayer as AudioStreamPlayer

# 从头开始播放音效
sfx_player.play()
# 运行结果: 音效从头开始播放

# 从第 5 秒位置开始播放
sfx_player.play(5.0)
# 运行结果: 音效从第 5 秒处开始播放

实际场景：播放按钮点击音效和背景音乐

C#

using Godot;

public partial class AudioManager : Node
{
    private AudioStreamPlayer _bgmPlayer;
    private AudioStreamPlayer _sfxPlayer;

    public override void _Ready()
    {
        _bgmPlayer = GetNode<AudioStreamPlayer>("BGMPlayer");
        _sfxPlayer = GetNode<AudioStreamPlayer>("SFXPlayer");
    }

    public void PlayBGM()
    {
        if (!_bgmPlayer.Playing)
        {
            _bgmPlayer.Play();
            // 运行结果: 背景音乐开始播放
        }
    }

    public void PlayButtonClick()
    {
        // 每次都从头播放按钮音效
        _sfxPlayer.Play();
        // 运行结果: 每次点击按钮时播放一个短音效
    }

    public void StopBGM()
    {
        _bgmPlayer.Stop();
        // 运行结果: 背景音乐停止
    }
}

GDScript

extends Node

@onready var _bgm_player: AudioStreamPlayer = $BGMPlayer
@onready var _sfx_player: AudioStreamPlayer = $SFXPlayer

func play_bgm():
    if not _bgm_player.playing:
        _bgm_player.play()
        # 运行结果: 背景音乐开始播放

func play_button_click():
    # 每次都从头播放按钮音效
    _sfx_player.play()
    # 运行结果: 每次点击按钮时播放一个短音效

func stop_bgm():
    _bgm_player.stop()
    # 运行结果: 背景音乐停止

进阶用法：带淡入效果的音乐播放

C#

using Godot;

public partial class MusicPlayer : Node
{
    private AudioStreamPlayer _musicPlayer;
    private float _targetVolume = 0.0f;   // 目标音量（分贝）
    private float _fadeSpeed = 3.0f;       // 淡入速度

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

    public void PlayWithFadeIn()
    {
        // 先把音量设为最低（静音），然后开始播放
        _musicPlayer.VolumeDb = -40.0f;
        _musicPlayer.Play();

        // 在 _Process 中逐渐增大音量
        // 运行结果: 音乐从静音开始，逐渐变大直到目标音量
    }

    public override void _Process(double delta)
    {
        if (_musicPlayer.Playing && _musicPlayer.VolumeDb < _targetVolume)
        {
            _musicPlayer.VolumeDb = Mathf.MoveToward(
                _musicPlayer.VolumeDb, _targetVolume, _fadeSpeed * (float)delta * 20.0f
            );
        }
    }
}

GDScript

extends Node

@onready var _music_player: AudioStreamPlayer = $MusicPlayer
var _target_volume: float = 0.0  # 目标音量（分贝）
var _fade_speed: float = 3.0     # 淡入速度

func play_with_fade_in():
    # 先把音量设为最低（静音），然后开始播放
    _music_player.volume_db = -40.0
    _music_player.play()
    # 运行结果: 音乐从静音开始，逐渐变大直到目标音量

func _process(delta):
    if _music_player.playing and _music_player.volume_db < _target_volume:
        _music_player.volume_db = move_toward(
            _music_player.volume_db, _target_volume, _fade_speed * delta * 20.0
        )

注意事项

• 必须先设置 Stream 属性：调用 Play() 之前，必须先给 AudioStreamPlayer 的 Stream 属性赋值（加载音频文件），否则不会播放任何声音。
• 重复调用会重新开始：如果音频正在播放，再次调用 Play() 会从头开始播放。可以利用这个特性来重复播放短音效。
• Playing 属性：可以用 IsPlaying()（C#）/ playing（GDScript）检查是否正在播放。
• 信号 finished：音频播放完毕后会触发 finished 信号，你可以连接这个信号来执行后续逻辑（比如播放下一首曲子）。