本文介绍在 Python 3.14 环境下安装 PyAudio 的完整指南。涵盖 Windows、Linux 和 macOS 平台的安装步骤及依赖处理方案，对比了源码编译、预编译轮子及 Conda 环境三种技术选型。包含设备验证代码示例、常见错误（如头文件缺失、权限问题）的解决方案，以及 PyAudio 与 SoundDevice 的性能对比和 Docker 部署要点。旨在帮助开发者解决跨平台音频库的兼容性与依赖问题。
Python 3.14 引入了一些底层变更，特别是与 C 扩展模块交互相关的改进，这使得传统 PyAudio 安装方式面临新的兼容性问题。不同操作系统平台的差异性进一步加剧了安装复杂度：
PyAudio 作为 Python 音频处理的核心桥梁库，其底层依赖 PortAudio 的 C 语言实现，这种跨语言交互在 Python 版本更新时容易产生 ABI 兼容性问题。
优点：
缺点：
优点：
缺点：
优点：
缺点：
若失败，尝试指定版本：
pip install PyAudio==0.2.13
使用预编译轮子安装：
pip install PyAudio --index-url https://pypi.python.org/simple/ --trusted-host pypi.python.org
先安装依赖：
sudo apt-get install portaudio19-dev python3-dev
然后安装 PyAudio：
pip install pyaudio
使用 Homebrew 解决依赖：
brew install portaudio
然后安装 PyAudio：
pip install pyaudio
import pyaudio
import sys
try:
# 初始化 PyAudio
pa = pyaudio.PyAudio()
# 获取默认输入设备信息
default_input = pa.get_default_input_device_info()
print(f"默认输入设备：{default_input['name']}")
# 获取默认输出设备信息
default_output = pa.get_default_output_device_info()
print(f"默认输出设备：{default_output['name']}")
# 测试音频流
stream = pa.open(format=pyaudio.paInt16, channels=1, rate=44100, input=True, frames_per_buffer=1024)
print("音频流测试成功！")
stream.stop_stream()
stream.close()
except ImportError:
print("PyAudio 未正确安装", file=sys.stderr)
except OSError as e:
print(f"音频设备错误：{str(e)}", file=sys.stderr)
except Exception as e:
print(f"未知错误：{str(e)}", file=sys.stderr)
finally:
pa.terminate()
Linux/Mac 下出现 portaudio.h not found 错误时：
# Ubuntu/Debian
sudo apt-get install portaudio19-dev
# CentOS/RHEL
sudo yum install portaudio-devel
# MacOS
brew install portaudio
Linux 下出现权限拒绝错误时：
# 将用户加入音频组
sudo usermod -a -G audio $USER
确保虚拟环境中安装了正确版本的依赖：
# 创建干净虚拟环境
python -m venv audio_env
source audio_env/bin/activate
pip install --upgrade pip
pip install pyaudio
Dockerfile 关键配置：
FROM python:3.14-slim
# 安装依赖
RUN apt-get update && \
apt-get install -y portaudio19-dev && \
rm -rf /var/lib/apt/lists/*
# 安装 PyAudio
RUN pip install pyaudio
# 允许音频设备访问
RUN groupadd -r audio && \
usermod -a -G audio root
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online