# 错误问题汇总 ## 1. `Could not find Opus library. Make sure it is installed.` ### **错误描述** ``` (.venv) C:\Users\Junsen\Desktop\learning\xiaozhi-python>python xiaozhi-python.py Traceback (most recent call last): File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\xiaozhi-python.py", line 5, in import opuslib File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\.venv\lib\site-packages\opuslib\__init__.py", line 19, in from .exceptions import OpusError # NOQA File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\.venv\lib\site-packages\opuslib\exceptions.py", line 10, in import opuslib.api.info File "C:\Users\Junsen\Desktop\learning\xiaozhi-python\.venv\lib\site-packages\opuslib\api\__init__.py", line 20, in raise Exception( Exception: Could not find Opus library. Make sure it is installed. ``` ### **解决方案** 1. **Windows** - 下载并安装 Opus 库。 - 确保 `opuslib` 相关库正确安装。 2. **Linux/macOS** - 运行以下命令安装 `libopus`: ```sh sudo apt-get install libopus-dev # Ubuntu/Debian brew install opus # macOS ``` 3. **Python 代码安装** ```sh pip install opuslib ``` --- ## 2. `externally-managed-environment` (macOS) ### **错误描述** ``` (.venv) huangjunsen@huangjunsendeMac-mini py-xiaozhi % pip install -r requirements_mac.txt -i https://pypi.tuna.tsinghua.edu.cn/simple error: externally-managed-environment × This environment is externally managed ╰─> To install Python packages system-wide, try brew install xyz, where xyz is the package you are trying to install. If you wish to install a Python library that isn't in Homebrew, use a virtual environment: python3 -m venv path/to/venv source path/to/venv/bin/activate python3 -m pip install xyz If you wish to install a Python application that isn't in Homebrew, it may be easiest to use 'pipx install xyz', which will manage a virtual environment for you. You can install pipx with brew install pipx You may restore the old behavior of pip by passing the '--break-system-packages' flag to pip, or by adding 'break-system-packages = true' to your pip.conf file. The latter will permanently disable this error. If you disable this error, we STRONGLY recommend that you additionally pass the '--user' flag to pip, or set 'user = true' in your pip.conf file. Failure to do this can result in a broken Homebrew installation. Read more about this behavior here: note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages. hint: See PEP 668 for the detailed specification. ``` ### **解决方案** 1. **使用虚拟环境安装** ```sh python3 -m venv my_env source my_env/bin/activate pip install -r requirements.txt ``` 2. **使用 **``** 进行全局安装** ```sh brew install pipx pipx install package_name ``` 3. **强制安装（不推荐）** ```sh pip install package_name --break-system-packages ``` --- ## 3. `WebSocket连接失败: BaseEventLoop.create_connection() got an unexpected keyword argument 'extra_headers'` ### **错误描述** ```python # 建立WebSocket连接 self.websocket = await websockets.connect( self.WEBSOCKET_URL, extra_headers=headers # 高版本这里改为 additional_headers=headers ) ``` ### **解决方案** - **新版本 **``: `extra_headers` 改为 `additional_headers`。 - **旧版本 **``: `additional_headers` 改为 `extra_headers`。 --- ## 4. `没有找到默认的输入/输出音频设备` ### **错误描述** ``` AudioCodec - ERROR - 初始化音频设备失败: [Errno -9996] Invalid input device (no default output device) AudioCodec - WARNING - 无法初始化音频设备: [Errno -9996] Invalid input device (no default output device) ``` ### **解决方案** 1. **Windows**: - 在 **声音设置** 中启用麦克风和扬声器。 2. **Linux/macOS**: ```sh pactl list sources | grep "Name" ``` 3. **检查可用音频设备**: ```python import pyaudio p = pyaudio.PyAudio() for i in range(p.get_device_count()): print(f"设备 {i}: {p.get_device_info_by_index(i)['name']}") ``` 4. **手动指定音频设备**: ```python stream = p.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True, input_device_index=0) ``` --- ## **5. `ModuleNotFoundError: No module named '_tkinter'` mac m4以下常见 ** ### **错误描述** ``` (.venv) apple@appledeMac-mini py-xiaozhi % python main.py Traceback (most recent call last): File "/Users/apple/Desktop/py-xiaozhi/main.py", line 5, in from src.application import Application File "/Users/apple/Desktop/py-xiaozhi/src/application.py", line 23, in from src.display import gui_display, cli_display File "/Users/apple/Desktop/py-xiaozhi/src/display/gui_display.py", line 2, in import tkinter as tk File "/opt/homebrew/Cellar/python@3.12/3.12.9/Frameworks/Python.framework/Versions/3.12/lib/python3.12/tkinter/__init__.py", line 38, in import _tkinter # If this fails your Python may not be configured for Tk ^^^^^^^^^^^^^^^ ModuleNotFoundError: No module named '_tkinter' ``` ### **解决方案** 1. **安装 `tcl-tk`** ```sh brew upgrade tcl-tk # 一般第一步就可以了 ``` 2. **检查 Homebrew 的 `tcl-tk` 路径** ```sh brew info tcl-tk ``` 3. **重新安装 Python，并链接 `tcl-tk`** ```sh brew install python-tk ``` 4. **手动指定 `Tcl/Tk` 路径（如有必要）** ```sh export PATH="/opt/homebrew/opt/tcl-tk/bin:$PATH" export LDFLAGS="-L/opt/homebrew/opt/tcl-tk/lib" export CPPFLAGS="-I/opt/homebrew/opt/tcl-tk/include" ``` 5. **重新创建虚拟环境** ```sh python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` --- ## 6. `导入 opuslib 失败: No module named 'pyaudioop'或'_cffi_backend'` ### **错误描述** ``` 找到opus库文件: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll 已添加DLL搜索路径: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows 已成功加载 opus.dll: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll 导入 opuslib 失败: No module named 'pyaudioop' 确保 opus 动态库已正确安装或位于正确的位置 ``` 或 ``` 找到opus库文件: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll 已添加DLL搜索路径: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows 已成功加载 opus.dll: D:\xiaozhi\PC\py-xiaozhi-main\libs\windows\opus.dll 导入 opuslib 失败: No module named '_cffi_backend' 请确保 opus 动态库已正确安装或位于正确的位置 ``` ### **解决方案** 1. **Python版本兼容性问题** - 这个错误通常与Python版本有关，尤其是Python 3.13版本 - 建议使用Python 3.9-3.12版本 2. **重新安装cffi** ```sh pip uninstall cffi pip install cffi ``` 3. **opus.dll放置** - 确保已将opus.dll放在正确位置（项目根目录和System32目录） ```sh # 检查是否已复制到这些位置 C:\Windows\System32\opus.dll 项目根目录\opus.dll 项目根目录\libs\windows\opus.dll ``` 4. **安装pyaudioop支持库** - 对于'pyaudioop'错误，尝试降级Python版本或安装相关依赖 ```sh pip install pyaudio ``` --- ## 8. `error: subprocess-exited-with-error`（安装 `numpy` 失败） ### **错误描述** ``` Collecting numpy==2.0.2 (from -r requirements.txt (line 8)) Using cached https://mirrors.aliyun.com/pypi/packages/a9/75/10dd1f8116a8b796cb2c737b674e02d02e80454bda953fa7e65d8c12b016/numpy-2.0.2.tar.gz (18.9 MB) Installing build dependencies ... done Getting requirements to build wheel ... done Installing backend dependencies ... done Preparing metadata (pyproject.toml) ... error error: subprocess-exited-with-error × Preparing metadata (pyproject.toml) did not run successfully. │ exit code: 1 ╰─> [21 lines of output] ... WARNING: Failed to activate VS environment: Could not parse vswhere.exe output ERROR: Unknown compiler(s): [['icl'], ['cl'], ['cc'], ['gcc'], ['clang'], ['clang-cl'], ['pgcc']] The following exception(s) were encountered: Running `icl ""` gave "[WinError 2] 系统找不到指定的文件。" Running `cl /?` gave "[WinError 2] 系统找不到指定的文件。" Running `cc --version` gave "[WinError 2] 系统找不到指定的文件。" Running `gcc --version` gave "[WinError 2] 系统找不到指定的文件。" Running `clang --version` gave "[WinError 2] 系统找不到指定的文件。" Running `clang-cl /?` gave "[WinError 2] 系统找不到指定的文件。" Running `pgcc --version` gave "[WinError 2] 系统找不到指定的文件。" note: This error originates from a subprocess, and is likely not a problem with pip. error: metadata-generation-failed × Encountered error while generating package metadata. ╰─> See above for output. note: This is an issue with the package mentioned above, not pip. hint: See above for details. ``` ### **解决方案** - 建议python版本在 3.9 - 3.12 1. **确保 `numpy` 版本兼容** `numpy==2.0.2` 可能存在构建问题，建议尝试安装较稳定的版本： ```sh pip install numpy==1.24.3 ``` 如果你不需要特定版本，可以安装最新稳定版本： ```sh pip install numpy ``` 2. **安装编译工具** Windows用户可能需要安装Visual C++ Build Tools： ```sh # 安装Microsoft C++ Build Tools # 下载并安装: https://visualstudio.microsoft.com/visual-cpp-build-tools/ ``` 3. **使用预编译的轮子** ```sh pip install --only-binary=numpy numpy ```