Skip to content

fix: 修复 Windows 平台中 Could not find Opus library 的问题#3105

Open
Yang-ZhiHang wants to merge 7 commits into
xinnan-tech:mainfrom
Yang-ZhiHang:main
Open

fix: 修复 Windows 平台中 Could not find Opus library 的问题#3105
Yang-ZhiHang wants to merge 7 commits into
xinnan-tech:mainfrom
Yang-ZhiHang:main

Conversation

@Yang-ZhiHang
Copy link
Copy Markdown

@Yang-ZhiHang Yang-ZhiHang commented Apr 16, 2026

平台:Windows11
项目版本:0.9.2
问题描述:安装好 requirement.txt 内的依赖后,运行 app.py 文件显示找不到 opuslib。具体报错如下:

Traceback (most recent call last):
  File "D:\code\dev\xiaozhi-esp32-server\main\xiaozhi-server\app.py", line 8, in <module>
    from core.utils.util import get_local_ip, validate_mcp_endpoint
  File "D:\code\dev\xiaozhi-esp32-server\main\xiaozhi-server\core\utils\util.py", line 11, in <module>
    import opuslib_next
  File "D:\code\dev\xiaozhi-esp32-server\.venv\lib\site-packages\opuslib_next\__init__.py", line 19, in <module>
    from .exceptions import OpusError  # NOQA
  File "D:\code\dev\xiaozhi-esp32-server\.venv\lib\site-packages\opuslib_next\exceptions.py", line 10, in <module>
    import opuslib_next.api.info
  File "D:\code\dev\xiaozhi-esp32-server\.venv\lib\site-packages\opuslib_next\api\__init__.py", line 44, in <module>
    raise Exception("Could not find Opus library. Make sure it is installed.")
Exception: Could not find Opus library. Make sure it is installed.

解决方案:通过在本地添加 opuslib 二进制文件,并在运行前进行加载即可解决此问题。

Copilot AI review requested due to automatic review settings April 16, 2026 13:13
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

该 PR 旨在解决 Windows 11 环境下运行 app.pyopuslib_next 报 “Could not find Opus library” 的问题,通过在应用启动早期主动定位并加载项目内置的 Opus 动态库来避免导入失败。

Changes:

  • 新增 utils/system_info.py:实现跨平台的 Opus 动态库查找、(可选)复制与加载逻辑,并对 ctypes.util.find_library 进行补丁。
  • 新增 utils/finder.py / utils/constant.py:提供 libs 目录定位与项目根目录常量。
  • 更新 app.py:在其他模块导入前调用 setup_opus() 以确保 Opus 库可用。

Reviewed changes

Copilot reviewed 4 out of 7 changed files in this pull request and generated 4 comments.

File Description
main/xiaozhi-server/utils/system_info.py 增加 Opus 动态库查找/加载与 find_library 补丁逻辑
main/xiaozhi-server/utils/finder.py 增加 libs 目录定位辅助方法
main/xiaozhi-server/utils/constant.py 增加项目根目录 APP_DIR 常量
main/xiaozhi-server/app.py 启动时优先执行 setup_opus(),避免后续 opuslib_next 导入失败

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread main/xiaozhi-server/utils/system_info.py Outdated
Comment thread main/xiaozhi-server/app.py Outdated
Comment thread main/xiaozhi-server/utils/finder.py Outdated
Comment thread main/xiaozhi-server/utils/system_info.py Outdated
@Yang-ZhiHang Yang-ZhiHang changed the title 修复opuslib找不到的问题 fix: 修复 Windows 平台中 Could not find Opus library 的问题 Apr 18, 2026
@Yang-ZhiHang
Copy link
Copy Markdown
Author

Yang-ZhiHang commented Apr 18, 2026

已经对内容进行修改:

  • 将新增内容迁移到 config/opus_loader.py 目录中;
  • 将 cdll 句柄添加到 sys 中进行持久化;
  • 添加对 setup_opus() 函数结果的处理;

适配了日志输出:

(xiaozhi-esp32-server) PS D:\code\dev\xiaozhi-esp32-server\main\xiaozhi-server> uv run .\app.py
260418 14:09:33[0.9.2_00000000000000][config.opus_loader]-INFO-检测到平台架构: windows x64
260418 14:09:33[0.9.2_00000000000000][config.opus_loader]-INFO-尝试从系统路径加载 Opus 库
260418 14:09:33[0.9.2_00000000000000][config.opus_loader]-INFO-系统路径未找到,尝试从本地加载 Opus 库
260418 14:09:33[0.9.2_00000000000000][config.opus_loader]-INFO-成功加载 Opus 库: D:\code\dev\xiaozhi-esp32-server\main\xiaozhi-server\libs\win\x64\opus.dll
260418 14:09:33[0.9.2_00000000000000][core.utils.gc_manager]-INFO-启动全局GC管理器,间隔300秒
...

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 5 changed files in this pull request and generated 5 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 2 out of 5 changed files in this pull request and generated 4 comments.


💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
Comment thread main/xiaozhi-server/config/opus_loader.py Outdated
chore: 删除多余的 LibPath 枚举
Yang-ZhiHang added a commit to xiaozhi-sys-CS203011/xiaozhi-sys-server that referenced this pull request May 6, 2026
fix: 修复 opuslib 加载失败的问题
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants