Fix the Issue Where Dependencies for PDF Generation are Installed but not Recogn…

…ized by the Program (Perhaps?)

Fix the Issue Where Dependencies for PDF Generation are Installed but not Recogn…
…ized by the Program (Perhaps?)
马一丁
Commit 37dc8e0a5dd02189c0aad2dfaa56c5edd5e695d4 37dc8e0a 1 parent a22be6d7
Showing 5 changed files with 270 additions and 22 deletions
README-EN.md
README.md
ReportEngine/flask_interface.py
ReportEngine/renderers/pdf_renderer.py
ReportEngine/utils/dependency_check.py
--- a/README-EN.md
View file @37dc8e0
+++ b/README-EN.md
View file @37dc8e0
@@ -396,10 +396,14 @@ uv venv --python 3.11 # Create Python 3.11 environment
 brew install pango gdk-pixbuf libffi
 # 2. Set environment variable (required)
+# Apple Silicon
 export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
+# Intel Mac
+export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH
 # Or permanently add to ~/.zshrc
 echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
+# Intel users: echo 'export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
 source ~/.zshrc
 ```
@@ -439,7 +443,18 @@ sudo yum install -y pango gdk-pixbuf2 libffi-devel cairo
 # Visit: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
 # Download the latest .exe file and install
-# 2. Restart command line or IDE
+# 2. Add the GTK installation bin directory to PATH (open a new terminal afterwards)
+# Default path example (replace with your custom install path if different)
+set PATH=C:\Program Files\GTK3-Runtime Win64\bin;%PATH%
+
+# Optional: persist the setting
+setx PATH "C:\Program Files\GTK3-Runtime Win64\bin;%PATH%"
+
+# If installed to a custom path, replace with your actual path, or set GTK_BIN_PATH=<your-bin-path>, then reopen the terminal
+
+# 3. Verify in a new terminal
+python -m ReportEngine.utils.dependency_check
+# You should see “✓ Pango dependency check passed”
 ```
 </details>
--- a/README.md
View file @37dc8e0
+++ b/README.md
View file @37dc8e0
@@ -389,7 +389,7 @@ conda activate your_conda_name
 uv venv --python 3.11 # 创建3.11环境
 ```
-### 3. 安装 PDF 导出所需系统依赖（可选）
+### 2. 安装 PDF 导出所需系统依赖（可选）
 > ⚠️ **注意**：如果您需要使用 PDF 导出功能，请按照以下步骤安装系统依赖。如果不需要 PDF 导出功能，可以跳过此步骤，系统其他功能不受影响。
@@ -404,10 +404,15 @@ brew install pango gdk-pixbuf libffi
 # 步骤 2: 设置环境变量（⚠️ 必须执行！）
 # 方法一：临时设置（仅当前终端会话有效）
+# Apple Silicon
 export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
+# Intel Mac
+export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH
 # 方法二：永久设置（推荐）
 echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
+# Intel 用户请改为:
+# echo 'export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc
 source ~/.zshrc
 ```
@@ -462,7 +467,18 @@ sudo yum install -y pango gdk-pixbuf2 libffi-devel cairo
 # 访问：https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
 # 下载最新版本的 .exe 文件并安装
-# 2. 重启命令行或 IDE
+# 2. 将 GTK 安装目录下的 bin 添加到 PATH（安装后请重新打开终端）
+# 默认路径示例（如果安装在其他目录，请替换成你的实际路径）
+set PATH=C:\Program Files\GTK3-Runtime Win64\bin;%PATH%
+
+# 可选：永久添加到 PATH
+setx PATH "C:\Program Files\GTK3-Runtime Win64\bin;%PATH%"
+
+# 如果安装在自定义目录，请替换为实际路径，或设置环境变量 GTK_BIN_PATH=你的bin路径，再重新打开终端
+
+# 3. 验证（新终端执行）
+python -m ReportEngine.utils.dependency_check
+# 输出包含 “✓ Pango 依赖检测通过” 表示配置正确
 ```
 </details>
--- a/ReportEngine/flask_interface.py
View file @37dc8e0
+++ b/ReportEngine/flask_interface.py
View file @37dc8e0
@@ -1191,8 +1191,8 @@ def export_pdf(task_id: str):
             return jsonify({
                 'success': False,
                 'error': 'PDF 导出功能不可用：缺少系统依赖',
-                'details': '请查看根目录 README.md 第393行「PDF 导出依赖」部分了解如何安装依赖',
-                'help_url': 'https://github.com/666ghj/BettaFish#3-安装-pdf-导出所需系统依赖可选',
+                'details': '请查看根目录 README.md “源码启动”的第二步（PDF 导出依赖）了解安装方法',
+                'help_url': 'https://github.com/666ghj/BettaFish#2-安装-pdf-导出所需系统依赖可选',
                 'system_message': pango_message
             }), 503
@@ -1280,8 +1280,8 @@ def export_pdf_from_ir():
             return jsonify({
                 'success': False,
                 'error': 'PDF 导出功能不可用：缺少系统依赖',
-                'details': '请查看根目录 README.md 第393行「PDF 导出依赖」部分了解如何安装依赖',
-                'help_url': 'https://github.com/666ghj/BettaFish#3-安装-pdf-导出所需系统依赖可选',
+                'details': '请查看根目录 README.md “源码启动”的第二步（PDF 导出依赖）了解安装方法',
+                'help_url': 'https://github.com/666ghj/BettaFish#2-安装-pdf-导出所需系统依赖可选',
                 'system_message': pango_message
             }), 503
--- a/ReportEngine/renderers/pdf_renderer.py
View file @37dc8e0
+++ b/ReportEngine/renderers/pdf_renderer.py
View file @37dc8e0
@@ -13,33 +13,57 @@ from pathlib import Path
 from typing import Any, Dict
 from datetime import datetime
 from loguru import logger
+from ReportEngine.utils.dependency_check import (
+    prepare_pango_environment,
+    check_pango_available,
+)
 # 在导入WeasyPrint之前，尝试补充常见的macOS Homebrew动态库路径，
 # 避免因未设置DYLD_LIBRARY_PATH而找不到pango/cairo等依赖。
 if sys.platform == 'darwin':
-    brew_lib = Path('/opt/homebrew/lib')
-    if brew_lib.exists():
-        current = os.environ.get('DYLD_LIBRARY_PATH', '')
-        if str(brew_lib) not in current.split(':'):
-            os.environ['DYLD_LIBRARY_PATH'] = f"{brew_lib}{':' + current if current else ''}"
+    mac_libs = [Path('/opt/homebrew/lib'), Path('/usr/local/lib')]
+    current = os.environ.get('DYLD_LIBRARY_PATH', '')
+    inserts = []
+    for lib in mac_libs:
+        if lib.exists() and str(lib) not in current.split(':'):
+            inserts.append(str(lib))
+    if inserts:
+        os.environ['DYLD_LIBRARY_PATH'] = ":".join(inserts + ([current] if current else []))
+
+# Windows: 自动补充常见 GTK/Pango 运行时路径，避免 DLL 加载失败
+if sys.platform.startswith('win'):
+    added = prepare_pango_environment()
+    if added:
+        logger.debug(f"已自动添加 GTK 运行时路径: {added}")
 try:
     from weasyprint import HTML, CSS
     from weasyprint.text.fonts import FontConfiguration
     WEASYPRINT_AVAILABLE = True
+    PDF_DEP_STATUS = "OK"
 except (ImportError, OSError) as e:
     WEASYPRINT_AVAILABLE = False
-    # 判断错误类型以提供更友好的提示
+    # 判断错误类型以提供更友好的提示，并尝试输出缺失依赖的详细信息
+    try:
+        _, dep_message = check_pango_available()
+    except Exception:
+        dep_message = None
+
     if isinstance(e, OSError):
-        logger.warning(
+        msg = dep_message or (
             "PDF 导出依赖缺失（系统库未安装或环境变量未设置），"
             "PDF 导出功能将不可用。其他功能不受影响。"
         )
+        logger.warning(msg)
+        PDF_DEP_STATUS = msg
     else:
-        logger.warning("WeasyPrint未安装，PDF导出功能将不可用")
+        msg = dep_message or "WeasyPrint未安装，PDF导出功能将不可用"
+        logger.warning(msg)
+        PDF_DEP_STATUS = msg
 except Exception as e:
     WEASYPRINT_AVAILABLE = False
-    logger.warning(f"WeasyPrint 加载失败: {e}，PDF导出功能将不可用")
+    PDF_DEP_STATUS = f"WeasyPrint 加载失败: {e}，PDF导出功能将不可用"
+    logger.warning(PDF_DEP_STATUS)
 from .html_renderer import HTMLRenderer
 from .pdf_layout_optimizer import PDFLayoutOptimizer, PDFLayoutConfig
@@ -73,7 +97,11 @@ class PDFRenderer:
         self.layout_optimizer = layout_optimizer or PDFLayoutOptimizer()
         if not WEASYPRINT_AVAILABLE:
-            raise RuntimeError("WeasyPrint未安装，请运行: pip install weasyprint")
+            raise RuntimeError(
+                PDF_DEP_STATUS
+                if 'PDF_DEP_STATUS' in globals() else
+                "WeasyPrint未安装，请运行: pip install weasyprint"
+            )
         # 初始化图表转换器
         try:
--- a/ReportEngine/utils/dependency_check.py
View file @37dc8e0
+++ b/ReportEngine/utils/dependency_check.py
View file @37dc8e0
@@ -2,9 +2,12 @@
 检测系统依赖工具
 用于检测 PDF 生成所需的系统依赖
 """
+import os
 import sys
 import platform
+from pathlib import Path
 from loguru import logger
+from ctypes import util as ctypes_util
 def _get_platform_specific_instructions():
@@ -24,10 +27,12 @@ def _get_platform_specific_instructions():
             "║     brew install pango gdk-pixbuf libffi                       ║\n"
             "║                                                                ║\n"
             "║  2. 设置环境变量（重要！）：                                   ║\n"
-            "║     export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH ║\n"
+            "║     Apple Silicon: export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH ║\n"
+            "║     Intel Mac:   export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH     ║\n"
             "║                                                                ║\n"
             "║  3. 永久生效（推荐）：                                         ║\n"
             "║     echo 'export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc ║\n"
+            "║     或 echo 'export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH' >> ~/.zshrc ║\n"
             "║     source ~/.zshrc                                            ║\n"
         )
     elif system == "Linux":
@@ -40,13 +45,24 @@ def _get_platform_specific_instructions():
             "║                                                                ║\n"
             "║  CentOS/RHEL:                                                  ║\n"
             "║    sudo yum install pango gdk-pixbuf2 libffi-devel cairo       ║\n"
+            "║                                                                ║\n"
+            "║  若仍提示缺库：export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH ║\n"
+            "║                 sudo ldconfig                                  ║\n"
         )
     elif system == "Windows":
         return (
             "║  🪟 Windows 系统解决方案：                                     ║\n"
             "║                                                                ║\n"
-            "║  下载并安装 GTK3 Runtime：                                     ║\n"
-            "║  https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases ║\n"
+            "║  1. 安装 GTK3 Runtime：                                        ║\n"
+            "║     https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases ║\n"
+            "║                                                                ║\n"
+            "║  2. 将 GTK 安装目录下的 bin 加入 PATH（需新开终端）：         ║\n"
+            "║     set PATH=C:\\Program Files\\GTK3-Runtime Win64\\bin;%PATH%  ║\n"
+            "║     （若自定义路径，请替换为实际安装路径）                     ║\n"
+            "║                                                                ║\n"
+            "║  3. 验证：在新终端运行                                         ║\n"
+            "║     python -m ReportEngine.utils.dependency_check              ║\n"
+            "║     看到 ✓ 提示即表示 PDF 导出可用                             ║\n"
         )
     else:
         return (
@@ -54,6 +70,158 @@ def _get_platform_specific_instructions():
         )
+def _ensure_windows_gtk_paths():
+    """
+    为 Windows 自动补充 GTK/Pango 运行时搜索路径，解决 DLL 未找到问题。
+
+    Returns:
+        str | None: 成功添加的路径（没有命中则为 None）
+    """
+    if platform.system() != "Windows":
+        return None
+
+    candidates = []
+    seen = set()
+
+    def _add_candidate(path_like):
+        if not path_like:
+            return
+        p = Path(path_like)
+        # 如果传入的是安装根目录，尝试拼接 bin
+        if p.is_dir() and p.name.lower() == "bin":
+            key = str(p.resolve()).lower()
+            if key not in seen:
+                seen.add(key)
+                candidates.append(p)
+        else:
+            for maybe in (p, p / "bin"):
+                key = str(maybe.resolve()).lower()
+                if maybe.exists() and key not in seen:
+                    seen.add(key)
+                    candidates.append(maybe)
+
+    # 用户自定义提示优先
+    for env_var in ("GTK3_RUNTIME_PATH", "GTK_RUNTIME_PATH", "GTK_BIN_PATH", "GTK_BIN_DIR", "GTK_PATH"):
+        _add_candidate(os.environ.get(env_var))
+
+    program_files = os.environ.get("ProgramFiles", r"C:\\Program Files")
+    program_files_x86 = os.environ.get("ProgramFiles(x86)", r"C:\\Program Files (x86)")
+    default_dirs = [
+        Path(program_files) / "GTK3-Runtime Win64",
+        Path(program_files_x86) / "GTK3-Runtime Win64",
+        Path(program_files) / "GTK3-Runtime Win32",
+        Path(program_files_x86) / "GTK3-Runtime Win32",
+        Path(program_files) / "GTK3-Runtime",
+        Path(program_files_x86) / "GTK3-Runtime",
+    ]
+
+    # 常见自定义安装位置（其他盘符 / DevelopSoftware 目录）
+    common_drives = ["C", "D", "E", "F"]
+    common_names = ["GTK3-Runtime Win64", "GTK3-Runtime Win32", "GTK3-Runtime"]
+    for drive in common_drives:
+        root = Path(f"{drive}:/")
+        for name in common_names:
+            default_dirs.append(root / name)
+            default_dirs.append(root / "DevelopSoftware" / name)
+
+    # 扫描 Program Files 下所有以 GTK 开头的目录，适配自定义安装目录名
+    for root in (program_files, program_files_x86):
+        root_path = Path(root)
+        if root_path.exists():
+            for child in root_path.glob("GTK*"):
+                default_dirs.append(child)
+
+    for d in default_dirs:
+        _add_candidate(d)
+
+    # 如果用户已把自定义路径加入 PATH，也尝试识别
+    path_entries = os.environ.get("PATH", "").split(os.pathsep)
+    for entry in path_entries:
+        if not entry:
+            continue
+        # 粗筛包含 gtk 或 pango 的目录
+        if "gtk" in entry.lower() or "pango" in entry.lower():
+            _add_candidate(entry)
+
+    for path in candidates:
+        if not path or not path.exists():
+            continue
+        if not any(path.glob("pango*-1.0-*.dll")) and not (path / "pango-1.0-0.dll").exists():
+            continue
+
+        try:
+            if hasattr(os, "add_dll_directory"):
+                os.add_dll_directory(str(path))
+        except Exception:
+            # 如果添加失败，继续尝试 PATH 方式
+            pass
+
+        current_path = os.environ.get("PATH", "")
+        if str(path) not in current_path.split(";"):
+            os.environ["PATH"] = f"{path};{current_path}"
+
+        return str(path)
+
+    return None
+
+
+def prepare_pango_environment():
+    """
+    初始化运行所需的本地依赖搜索路径（当前主要针对 Windows 和 macOS）。
+
+    Returns:
+        str | None: 成功添加的路径（没有命中则为 None）
+    """
+    system = platform.system()
+    if system == "Windows":
+        return _ensure_windows_gtk_paths()
+    if system == "Darwin":
+        # 自动补全 DYLD_LIBRARY_PATH，兼容 Apple Silicon 与 Intel
+        candidates = [Path("/opt/homebrew/lib"), Path("/usr/local/lib")]
+        current = os.environ.get("DYLD_LIBRARY_PATH", "")
+        added = []
+        for c in candidates:
+            if c.exists() and str(c) not in current.split(":"):
+                added.append(str(c))
+        if added:
+            os.environ["DYLD_LIBRARY_PATH"] = ":".join(added + ([current] if current else []))
+            return os.environ["DYLD_LIBRARY_PATH"]
+    return None
+
+
+def _probe_native_libs():
+    """
+    使用 ctypes 查找关键原生库，帮助定位缺失组件。
+
+    Returns:
+        list[str]: 未找到的库标识
+    """
+    system = platform.system()
+    targets = []
+
+    if system == "Windows":
+        targets = [
+            ("pango", ["pango-1.0-0"]),
+            ("gobject", ["gobject-2.0-0"]),
+            ("gdk-pixbuf", ["gdk_pixbuf-2.0-0"]),
+            ("cairo", ["cairo-2"]),
+        ]
+    else:
+        targets = [
+            ("pango", ["pango-1.0"]),
+            ("gobject", ["gobject-2.0"]),
+            ("gdk-pixbuf", ["gdk_pixbuf-2.0"]),
+            ("cairo", ["cairo", "cairo-2"]),
+        ]
+
+    missing = []
+    for key, variants in targets:
+        found = any(ctypes_util.find_library(v) for v in variants)
+        if not found:
+            missing.append(key)
+    return missing
+
+
 def check_pango_available():
     """
     检测 Pango 库是否可用
@@ -61,6 +229,9 @@ def check_pango_available():
     Returns:
         tuple: (is_available: bool, message: str)
     """
+    added_path = prepare_pango_environment()
+    missing_native = _probe_native_libs()
+
     try:
         # 尝试导入 weasyprint 并初始化 Pango
         from weasyprint import HTML
@@ -74,6 +245,21 @@ def check_pango_available():
         # Pango 库未安装或无法加载
         error_msg = str(e)
         platform_instructions = _get_platform_specific_instructions()
+        windows_hint = ""
+        if platform.system() == "Windows":
+            path_display = added_path or "未找到默认路径"
+            # 控制长度，避免破坏提示框宽度
+            if len(path_display) > 38:
+                path_display = path_display[:35] + "..."
+            windows_hint = f"║  已尝试自动添加 GTK 路径: {path_display:<38}║\n"
+            arch_note = "║  🔍 若已安装仍报错：确认 Python/GTK 位数一致，重开终端        ║\n"
+        else:
+            arch_note = ""
+
+        missing_note = ""
+        if missing_native:
+            missing_str = ", ".join(missing_native)
+            missing_note = f"║  未识别到的依赖: {missing_str:<46}║\n"
         if 'gobject' in error_msg.lower() or 'pango' in error_msg.lower() or 'gdk' in error_msg.lower():
             return False, (
@@ -82,12 +268,15 @@ def check_pango_available():
                 "║                                                                ║\n"
                 "║  📄 PDF 导出功能将不可用（其他功能不受影响）                  ║\n"
                 "║                                                                ║\n"
+                f"{windows_hint}"
+                f"{arch_note}"
+                f"{missing_note}"
                 f"{platform_instructions}"
                 "║                                                                ║\n"
-                "║  📖 完整文档：根目录 README.md 第393行「PDF 导出依赖」        ║\n"
+                "║  📖 完整文档：根目录 README.md ‘源码启动’的第二步            ║\n"
                 "╚════════════════════════════════════════════════════════════════╝"
             )
-        return False, f"⚠ PDF 依赖加载失败: {error_msg}"
+        return False, f"⚠ PDF 依赖加载失败: {error_msg}；缺失/未识别: {', '.join(missing_native) if missing_native else '未知'}"
     except ImportError as e:
         # weasyprint 未安装
         return False, (