From d081803434f29cd4b6a2ab8a7c555a8e97669c68 Mon Sep 17 00:00:00 2001
From: Hanabi <78060373+KurobaKaitou@users.noreply.github.com>
Date: Mon, 20 Oct 2025 12:28:22 +0800
Subject: [PATCH] =?UTF-8?q?chore(util):=20=E4=BC=98=E5=8C=96=E9=A1=B9?=
 =?UTF-8?q?=E7=9B=AE=E5=90=AF=E5=8A=A8=E6=97=B6=E6=A3=80=E6=B5=8Bffmpeg?=
 =?UTF-8?q?=E7=8E=AF=E5=A2=83=E6=97=B6=E5=9C=A8=E6=9F=90=E4=BA=9B=E5=9C=BA?=
 =?UTF-8?q?=E6=99=AF=E4=B8=8B=E7=9A=84=E6=8F=90=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

此次变动主要针对 Linux (Ubuntu 22.04) 环境下根据官方提供的README文档以及conda安装 ffmpeg 环境后出现缺失动态库libiconv.so.2的问题 报错完整信息如下:
`ffmpeg: error while loading shared libraries: libiconv.so.2: cannot open shared object file: No such file or directory` 基于以上报错信息 优化了util.py中的check_ffmpeg_installed函数
- 保留了原有命令行的提示信息 [定位问题更加友好]
- 抓取报错中的 libiconv.so.2 文本内容 进行提示用户通过conda安装 libiconv 动态库
---
 main/xiaozhi-server/core/utils/util.py | 69 +++++++++++++++++++-------
 1 file changed, 51 insertions(+), 18 deletions(-)

diff --git a/main/xiaozhi-server/core/utils/util.py b/main/xiaozhi-server/core/utils/util.py
index 27471e58..ea34d3e8 100644
--- a/main/xiaozhi-server/core/utils/util.py
+++ b/main/xiaozhi-server/core/utils/util.py
@@ -176,31 +176,64 @@ def parse_string_to_list(value, separator=";"):
     return []
 
 
-def check_ffmpeg_installed():
-    ffmpeg_installed = False
+def check_ffmpeg_installed() -> bool:
+    """
+    检查当前环境中是否已正确安装并可执行 ffmpeg。
+
+    Returns:
+        bool: 如果 ffmpeg 正常可用，返回 True；否则抛出 ValueError 异常。
+
+    Raises:
+        ValueError: 当检测到 ffmpeg 未安装或依赖缺失时，抛出详细的提示信息。
+    """
     try:
-        # 执行ffmpeg -version命令，并捕获输出
+        # 尝试执行 ffmpeg 命令
         result = subprocess.run(
             ["ffmpeg", "-version"],
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,
-            check=True,  # 如果返回码非零则抛出异常
+            check=True,  # 非零退出码会触发 CalledProcessError
         )
-        # 检查输出中是否包含版本信息（可选）
-        output = result.stdout + result.stderr
-        if "ffmpeg version" in output.lower():
-            ffmpeg_installed = True
-        return False
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        # 命令执行失败或未找到
-        ffmpeg_installed = False
-    if not ffmpeg_installed:
-        error_msg = "您的电脑还没正确安装ffmpeg\n"
-        error_msg += "\n建议您：\n"
-        error_msg += "1、按照项目的安装文档，正确进入conda环境\n"
-        error_msg += "2、查阅安装文档，如何在conda环境中安装ffmpeg\n"
-        raise ValueError(error_msg)
+
+        output = (result.stdout + result.stderr).lower()
+        if "ffmpeg version" in output:
+            return True
+
+        # 如果未检测到版本信息，也视为异常情况
+        raise ValueError("未检测到有效的 ffmpeg 版本输出。")
+
+    except (subprocess.CalledProcessError, FileNotFoundError) as e:
+        # 提取错误输出
+        stderr_output = ""
+        if isinstance(e, subprocess.CalledProcessError):
+            stderr_output = (e.stderr or "").strip()
+        else:
+            stderr_output = str(e).strip()
+
+        # 构建基础错误提示
+        error_msg = [
+            "❌ 检测到 ffmpeg 无法正常运行。\n",
+            "建议您：",
+            "1. 确认已正确激活 conda 环境；",
+            "2. 查阅项目安装文档，了解如何在 conda 环境中安装 ffmpeg。\n",
+        ]
+
+        # 🎯 针对具体错误信息提供额外提示
+        if "libiconv.so.2" in stderr_output:
+            error_msg.append("⚠️ 发现缺少依赖库：libiconv.so.2")
+            error_msg.append("解决方法：在当前 conda 环境中执行：")
+            error_msg.append("   conda install -c conda-forge libiconv\n")
+        elif "no such file or directory" in stderr_output and "ffmpeg" in stderr_output.lower():
+            error_msg.append("⚠️ 系统未找到 ffmpeg 可执行文件。")
+            error_msg.append("解决方法：在当前 conda 环境中执行：")
+            error_msg.append("   conda install -c conda-forge ffmpeg\n")
+        else:
+            error_msg.append("错误详情：")
+            error_msg.append(stderr_output or "未知错误。")
+
+        # 抛出详细异常信息
+        raise ValueError("\n".join(error_msg)) from e
 
 
 def extract_json_from_string(input_string):