Merge pull request #2380 from KurobaKaitou/main

chore: 补充在 Linux 环境下进行源码部署时出现缺失动态库的解决方案以及保留检测 ffmpeg 环境时的原有报错信息

docs/Deployment_all.md

@@ -355,6 +355,9 @@ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/
 
 conda install libopus -y
 conda install ffmpeg -y
+
+# 在 Linux 环境下进行部署时,如出现类似缺失 libiconv.so.2 动态库的报错 请通过以下命令进行安装
+conda install libiconv
 ```
 
 请注意，以上命令，不是一股脑执行就成功的，你需要一步步执行，每一步执行完后，都检查一下输出的日志，查看是否成功。

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):