不能直接用PlaySound或system("afplay")，因为它们分别是Windows和macOS专属、Linux不可用，且绕过程序控制流，无法获知播放状态；miniaudio则跨平台、零依赖、统一抽象后端并返回明确错误码。
为什么不能直接用 PlaySound 或 system("afplay")
因为跨平台声音播放最常踩的坑就是“本地能跑，换台机器就静音”——PlaySound 是 Windows 专属，afplay 只在 macOS 有效，Linux 上甚至没这个命令。更麻烦的是，这些方式都绕过程序控制流：你调用完就返回，根本不知道音频是否真正开始播、播完了没、中途出错了没。真正的跨平台类必须统一抽象音频后端，而不是拼凑系统命令。
推荐用 miniaudio 而不是 SDL2 或 PortAudio
miniaudio 是目前最轻量、单头文件、零依赖的跨平台音频库，编译时不用链接一堆动态库，也不会因 SDL2 的窗口依赖或 PortAudio 的构建复杂度卡住。它默认支持 Windows（WASAPI）、macOS（Core Audio）、Linux（PulseAudio/ALSA），且 API 极简：
#include "miniaudio.h"
<p>class SimplePlayer {
ma_device device;
ma_engine engine;</p><p>public:
bool init() {
if (ma_engine_init(nullptr, &engine) != MA_SUCCESS) return false;
return true;
}</p><pre class='brush:php;toolbar:false;'>bool play(const char* filepath) {
ma_sound sound;
if (ma_sound_init_from_file(&engine, filepath, 0, nullptr, nullptr, &sound) != MA_SUCCESS) {
return false;
}
ma_sound_start(&sound);
// 注意：这里只是启动播放，不阻塞
// 如需同步等待结束，得轮询 ma_sound_is_playing(&sound)
return true;
}};
关键点：ma_engine_init 自动选最佳后端；ma_sound_init_from_file 支持 WAV/MP3/FLAC（MP3 需定义 MA_ENABLE_MP3）；所有函数返回明确错误码，不抛异常。
立即学习“C++免费学习笔记（深入）”；
Linux 下 PulseAudio 挂掉时会静音，怎么快速 fallback
某些嵌入式或最小化 Linux 环境（比如 Docker 容器、Raspberry Pi Lite）默认没 PulseAudio，miniaudio 会自动尝试 ALSA，但若 ALSA 也没配好（比如没权限访问 /dev/snd/），ma_engine_init 就直接失败。此时别硬扛，加一层降级逻辑：
- 先尝试
ma_engine_init默认配置 - 失败后，显式指定后端：
ma_engine_config config = ma_engine_config_init(); config.pBackend = ma_backend_alsa; - 仍失败？记录日志并返回 false，**不要静默吞错** —— 很多“没声音”问题其实源于权限或内核模块未加载（
sudo modprobe snd_bcm2835）
注意：ma_backend_alsa 在 macOS 和 Windows 上会被忽略，所以这段降级代码可安全跨平台编译。
播放完成检测和资源释放容易被忽略
很多人只调 ma_sound_start 就以为完事了，结果反复播放同一文件时内存泄漏，或程序退出时音频设备没释放导致下次初始化失败。必须做两件事：
- 每次
ma_sound_init_from_file后，记得ma_sound_uninit(&sound)—— 即使播放中途出错也要调 - 如需知道播放是否结束，不能靠 sleep 猜时长，而应轮询：
while (ma_sound_is_playing(&sound)) { ma_sleep(10); }（ma_sleep是跨平台毫秒休眠） -
ma_engine_uninit(&engine)必须在析构中调用，否则部分后端（如 WASAPI）可能残留设备句柄
最典型的漏点：把 ma_sound 对象放在栈上，函数返回就销毁，但音频还在后台播——ma_sound 不是 RAII 类型，生命周期完全由你手动管理。
