Update the Dependency Handling Scheme

README.md

@@ -392,23 +392,41 @@ uv pip install -r requirements.txt
 
 ### 3. 安装 PDF 导出所需系统依赖（可选）
 
-> ⚠️ **注意**：如果您需要使用 PDF 导出功能，请按照以下步骤安装系统依赖。如果不需要 PDF 导出功能，可以跳过此步骤，系统其他功能不受影响。
+> ⚠️ **注意**：如果您需要使用 PDF 导出功能，请按照以下步骤安装系统依赖。如果不需要 PDF 导出功能，可以跳过此步骤，系统其他功能不受影响。在此部分操作之前，建议重新运行“2. 安装依赖包”的代码。
 
 <details>
 <summary><b>📦 macOS 系统安装步骤</b></summary>
 
+> 🔴 **重要提示**：macOS 用户必须完成以下**两个步骤**，缺一不可！仅安装系统依赖而不设置环境变量会导致 `cannot load library 'libgobject-2.0-0'` 错误。
+
 ```bash
-# 1. 安装系统依赖（在宿主机上执行）
+# 步骤 1: 安装系统依赖
 brew install pango gdk-pixbuf libffi
 
-# 2. 设置环境变量（必需）
+# 步骤 2: 设置环境变量（⚠️ 必须执行！）
+# 方法一：临时设置（仅当前终端会话有效）
 export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
 
-# 或永久添加到 ~/.zshrc
+# 方法二：永久设置（推荐）
 echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
 source ~/.zshrc
 ```
 
+**验证安装**：
+
+```bash
+# 测试 PDF 依赖是否正确配置
+python -m ReportEngine.utils.dependency_check
+# 应该显示：✓ Pango 依赖检测通过，PDF 导出功能可用
+```
+
+**常见问题**：
+
+- 如果仍然提示找不到库，请确保：
+  1. 已执行 `source ~/.zshrc` 重新加载配置
+  2. 在新终端中运行应用（确保环境变量已生效）
+  3. 使用 `echo $DYLD_LIBRARY_PATH` 验证环境变量已设置
+
 </details>
 
 <details>

ReportEngine/flask_interface.py

@@ -1047,8 +1047,9 @@ def export_pdf(task_id: str):
         if not pango_available:
             return jsonify({
                 'success': False,
-                'error': 'PDF 导出功能不可用：缺少 Pango 系统依赖',
+                'error': 'PDF 导出功能不可用：缺少系统依赖',
-                'details': '请查看 requirements.txt 文件中的 "===== PDF生成 =====" 部分了解如何安装 Pango',
+                'details': '请查看根目录 README.md 第393行「PDF 导出依赖」部分了解如何安装依赖',
+                'help_url': 'https://github.com/666ghj/BettaFish#3-安装-pdf-导出所需系统依赖可选',
                 'system_message': pango_message
             }), 503
 
@@ -1135,8 +1136,9 @@ def export_pdf_from_ir():
         if not pango_available:
             return jsonify({
                 'success': False,
-                'error': 'PDF 导出功能不可用：缺少 Pango 系统依赖',
+                'error': 'PDF 导出功能不可用：缺少系统依赖',
-                'details': '请查看 requirements.txt 文件中的 "===== PDF生成 =====" 部分了解如何安装 Pango',
+                'details': '请查看根目录 README.md 第393行「PDF 导出依赖」部分了解如何安装依赖',
+                'help_url': 'https://github.com/666ghj/BettaFish#3-安装-pdf-导出所需系统依赖可选',
                 'system_message': pango_message
             }), 503
 

ReportEngine/renderers/pdf_renderer.py

@@ -16,9 +16,19 @@ try:
     from weasyprint import HTML, CSS
     from weasyprint.text.fonts import FontConfiguration
     WEASYPRINT_AVAILABLE = True
-except ImportError:
+except (ImportError, OSError) as e:
     WEASYPRINT_AVAILABLE = False
-    logger.warning("WeasyPrint未安装，PDF导出功能将不可用")
+    # 判断错误类型以提供更友好的提示
+    if isinstance(e, OSError):
+        logger.warning(
+            "PDF 导出依赖缺失（系统库未安装或环境变量未设置），"
+            "PDF 导出功能将不可用。其他功能不受影响。"
+        )
+    else:
+        logger.warning("WeasyPrint未安装，PDF导出功能将不可用")
+except Exception as e:
+    WEASYPRINT_AVAILABLE = False
+    logger.warning(f"WeasyPrint 加载失败: {e}，PDF导出功能将不可用")
 
 from .html_renderer import HTMLRenderer
 from .pdf_layout_optimizer import PDFLayoutOptimizer, PDFLayoutConfig

ReportEngine/utils/dependency_check.py

@@ -3,9 +3,57 @@
 用于检测 PDF 生成所需的系统依赖
 """
 import sys
+import platform
 from loguru import logger
 
 
+def _get_platform_specific_instructions():
+    """
+    获取针对当前平台的安装说明
+
+    Returns:
+        str: 平台特定的安装说明
+    """
+    system = platform.system()
+
+    if system == "Darwin":  # macOS
+        return (
+            "║  🍎 macOS 系统解决方案：                                       ║\n"
+            "║                                                                ║\n"
+            "║  1. 安装系统依赖：                                             ║\n"
+            "║     brew install pango gdk-pixbuf libffi                       ║\n"
+            "║                                                                ║\n"
+            "║  2. 设置环境变量（重要！）：                                   ║\n"
+            "║     export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH ║\n"
+            "║                                                                ║\n"
+            "║  3. 永久生效（推荐）：                                         ║\n"
+            "║     echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc ║\n"
+            "║     source ~/.zshrc                                            ║\n"
+        )
+    elif system == "Linux":
+        return (
+            "║  🐧 Linux 系统解决方案：                                       ║\n"
+            "║                                                                ║\n"
+            "║  Ubuntu/Debian:                                                ║\n"
+            "║    sudo apt-get install libpango-1.0-0 libpangoft2-1.0-0 \\    ║\n"
+            "║                         libgdk-pixbuf2.0-0 libffi-dev libcairo2 ║\n"
+            "║                                                                ║\n"
+            "║  CentOS/RHEL:                                                  ║\n"
+            "║    sudo yum install pango gdk-pixbuf2 libffi-devel cairo       ║\n"
+        )
+    elif system == "Windows":
+        return (
+            "║  🪟 Windows 系统解决方案：                                     ║\n"
+            "║                                                                ║\n"
+            "║  下载并安装 GTK3 Runtime：                                     ║\n"
+            "║  https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases ║\n"
+        )
+    else:
+        return (
+            "║  请查看 README.md 了解您系统的安装方法                        ║\n"
+        )
+
+
 def check_pango_available():
     """
     检测 Pango 库是否可用
@@ -25,19 +73,27 @@ def check_pango_available():
     except OSError as e:
         # Pango 库未安装或无法加载
         error_msg = str(e)
-        if 'pango' in error_msg.lower():
+        platform_instructions = _get_platform_specific_instructions()
+
+        if 'gobject' in error_msg.lower() or 'pango' in error_msg.lower() or 'gdk' in error_msg.lower():
             return False, (
                 "╔════════════════════════════════════════════════════════════════╗\n"
-                "║  ⚠️  Pango 依赖未安装或无法加载                                ║\n"
+                "║  ⚠️  PDF 导出依赖缺失                                          ║\n"
                 "║                                                                ║\n"
                 "║  📄 PDF 导出功能将不可用（其他功能不受影响）                  ║\n"
-                "║  📖 详细安装说明请查看：根目录下的 README.md                  ║\n"
+                "║                                                                ║\n"
+                f"{platform_instructions}"
+                "║                                                                ║\n"
+                "║  📖 完整文档：根目录 README.md 第393行「PDF 导出依赖」        ║\n"
                 "╚════════════════════════════════════════════════════════════════╝"
             )
         return False, f"⚠ PDF 依赖加载失败: {error_msg}"
     except ImportError as e:
         # weasyprint 未安装
-        return False, f"⚠ WeasyPrint 未安装: {e}"
+        return False, (
+            "⚠ WeasyPrint 未安装\n"
+            "解决方法: pip install weasyprint"
+        )
     except Exception as e:
         # 其他未知错误
         return False, f"⚠ PDF 依赖检测失败: {e}"