Win10 安装 simpleaudio 失败？缺少 VC++ 14.0？快速解决

2025-03-19 10:10:08

Windows 10 安装 Simpleaudio 失败：缺少 Microsoft Visual C++ 14.0 或更高版本

最近想在 Windows 10 上用 pip 安装 Python 的 simpleaudio 库, 结果遇到报错, 提示缺少 Microsoft Visual C++ 14.0 或更高版本。错误信息挺长, 关键是这句: error: Microsoft Visual C++ 14.0 or greater is required. 看样子, 问题出在编译环节。

一、问题原因分析

simpleaudio 这个库里面有些部分是用 C++ 写的。pip 在安装这种包含 C/C++ 代码的 Python 包时，如果找不到预编译好的二进制文件（wheel 文件），就会尝试从源代码编译。编译就需要用到 C++ 编译器。而 Windows 上默认没有安装, 就会报这个错。

简单说，就是你电脑上没装 C++ 的编译工具。

二、解决方法

1. 安装 Microsoft Visual C++ Build Tools (推荐)

最直接的方法，就是按照错误提示里的链接，去下载安装 "Microsoft C++ Build Tools"。

原理： 这是微软官方提供的 C++ 编译工具集，包含了编译 C++ 代码所需的编译器、链接器、库文件等。安装后，pip 就能找到它们来编译 simpleaudio。
步骤：
1. 访问错误信息中提供的链接： https://visualstudio.microsoft.com/visual-cpp-build-tools/
2. 下载 "Build Tools for Visual Studio 2022" (或更高版本) 的安装程序。
3. 运行安装程序。
4. 在 "工作负载" 选项卡下, 勾选 "C++ build tools"，右侧可选组件不用全装, 只勾选 "Windows 10 SDK" （或对应你的系统的SDK）和 "MSVC v143 - VS 2022 C++ x64/x86 build tools" （或类似版本）就行，这样能减少安装体积.
5. 点击“安装”。
安装之后重新打开一个新的 cmd 或 powershell 窗口 ，再运行：

pip install simpleaudio

这次不出意外就 OK 了.

2. 安装完整版 Visual Studio

如果你本来就要用 Visual Studio 做开发, 那直接装个完整版的也行.

原理： Visual Studio 是个庞大的 IDE（集成开发环境）, 里面自然包含了 C++ 编译工具。
步骤：
1. 下载 Visual Studio Community (免费版就够用), 或者其他版本.
2. 安装时, 记得勾选 "使用 C++ 的桌面开发" 这个工作负载.

安装完 Visual Studio, pip 也能找到 C++ 编译器了。之后重开命令行, 执行pip install simpleaudio就完事了.

3. 使用预编译的 wheel 文件 (不太推荐)

理论上，你可以去找 simpleaudio 对应你 Python 版本和操作系统位数的 wheel 文件 (.whl) 来手动安装，避开编译过程。但实际操作中比较麻烦，不推荐新手这么搞.

原理: wheel 文件是 Python 包的一种分发格式，包含了预编译好的二进制文件，可以直接安装，无需编译。
操作 (不推荐):
1. 到 PyPI (Python Package Index) 上搜索 simpleaudio, 看有没有合适的 wheel 文件下载. PyPI 地址：https://pypi.org/project/simpleaudio/#files
要注意, 这个页面上不一定有适合你系统的, 就算有, 你下载下来，也还要确认跟你 python 版本匹配。
2. 如果找到了, 下载 .whl 文件.
3. 在命令行里，用 pip 安装：
```
```bash
pip install <path_to_your_downloaded_wheel_file.whl>
```
把 `<path_to_your_downloaded_wheel_file.whl>` 换成你下载的 wheel 文件的实际路径。
```

进阶技巧和补充说明

清理pip缓存

有时安装失败, pip可能会留下一些缓存. 遇到莫名其妙的问题时, 可以尝试清理一下 pip 缓存:

pip cache purge

或

pip install simpleaudio --no-cache-dir

环境变量的确认（较少见的情况）

在极少数情况下，即使你正确的安装了build tools，pip 可能也无法自动找到相应的编译环境, 如果在执行编译时遇到类似 cl.exe not found 的提示，建议手动设置一下相关的环境变量. 通常 Visual Studio Installer 会自动帮你处理好，所以这一步绝大部分情况下都用不到, 除非你手动改过，或者有多个版本的VS，导致路径冲突了.

设置环境变量（示例, 实际路径可能有差异, 以你自己的安装路径为准. 如果不知道, 可以在 "Visual Studio Installer"->已安装->对应版本->更多->打开安装位置，这样就能定位到了）：

假设 VS2022 装在了 C:\Program Files\Microsoft Visual Studio\2022\Community，则在"系统属性" -> "高级" -> "环境变量" -> "系统变量" 里，检查或新增/修改这些变量（如果你的系统语言不是中文, 就找对应的名称）：

INCLUDE :
- 新增或追加:
  C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.3x.xxxxx\include;C:\Program Files (x86)\Windows Kits\10\Include\10.0.xxxxx.0\ucrt
  (这里的 14.3x.xxxxx 和 10.0.xxxxx.0 要根据你的实际安装版本号来改)
LIB :
* 新增或追加：
C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.3x.xxxxx\lib\x64;C:\Program Files (x86)\Windows Kits\10\Lib\10.0.xxxxx.0\ucrt\x64
(注意, 这里是 x64, 如果你 python 是32位的，就改成 x86. 同上, xxxxx 要按实际改.)
Path :
* 在已有的 Path 变量值的最后, 追加:
;C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.3x.xxxxx\bin\Hostx64\x64