{"record":{"id":"406b847593c2be1b","repo":"666ghj/MiroFish","slug":"pymupdf-pip-install-pymupdf","errorCode":null,"errorMessage":"需要安装PyMuPDF: pip install PyMuPDF","messagePattern":"需要安装PyMuPDF: pip install PyMuPDF","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"backend/app/utils/file_parser.py","lineNumber":116,"sourceCode":"        if suffix not in cls.SUPPORTED_EXTENSIONS:\n            raise ValueError(f\"不支持的文件格式: {suffix}\")\n        \n        if suffix == '.pdf':\n            return cls._extract_from_pdf(file_path)\n        elif suffix in {'.md', '.markdown'}:\n            return cls._extract_from_md(file_path)\n        elif suffix == '.txt':\n            return cls._extract_from_txt(file_path)\n        \n        raise ValueError(f\"无法处理的文件格式: {suffix}\")\n    \n    @staticmethod\n    def _extract_from_pdf(file_path: str) -> str:\n        \"\"\"从PDF提取文本\"\"\"\n        try:\n            import fitz  # PyMuPDF\n        except ImportError:\n            raise ImportError(\"需要安装PyMuPDF: pip install PyMuPDF\")\n        \n        text_parts = []\n        with fitz.open(file_path) as doc:\n            for page in doc:\n                text = page.get_text()\n                if text.strip():\n                    text_parts.append(text)\n        \n        return \"\\n\\n\".join(text_parts)\n    \n    @staticmethod\n    def _extract_from_md(file_path: str) -> str:\n        \"\"\"从Markdown提取文本，支持自动编码检测\"\"\"\n        return _read_text_with_fallback(file_path)\n    \n    @staticmethod\n    def _extract_from_txt(file_path: str) -> str:\n        \"\"\"从TXT提取文本，支持自动编码检测\"\"\"","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/app/utils/file_parser.py#L98-L134","documentation":"ImportError raised inside _extract_from_pdf when 'import fitz' (PyMuPDF) fails because the package is not installed in the current environment. PDF extraction is optional functionality whose dependency is only imported on demand, so the error appears exactly when the first PDF is parsed.","triggerScenarios":"Calling extract_text on a .pdf file in an environment where PyMuPDF is not installed — typically because it was left out of requirements.txt/pyproject or the deployment image, while the developer machine had it.","commonSituations":"Dependency declared as optional or forgotten in deployment (Docker image, CI), different virtual environments between dev and prod, or a fresh clone without the extra dependency installed.","solutions":["Install PyMuPDF: pip install PyMuPDF (as the message says)","Add PyMuPDF to the project's locked dependencies if PDF support is required","Alternatively, pre-check importability and return a clear feature-unavailable response to the caller instead of failing mid-parse"],"exampleFix":"# before\n# PyMuPDF missing from requirements.txt; first PDF upload crashes with ImportError\n\n# after\n# requirements.txt\nPyMuPDF==1.24.*","handlingStrategy":"validation","validationCode":"try:\n    import fitz  # noqa: F401\n    PDF_OK = True\nexcept ImportError:\n    PDF_OK = False\n\nif path.suffix == '.pdf' and not PDF_OK:\n    return http_error(501, \"PDF extraction unavailable: PyMuPDF not installed\")","typeGuard":null,"tryCatchPattern":"try:\n    text = FileParser.extract_text(pdf_path)\nexcept ImportError as e:\n    logger.error(\"dependency missing: %s\", e)\n    raise","preventionTips":["Declare PyMuPDF in locked dependencies if PDF support is part of the product","Smoke-test PDF parsing in CI so a missing optional dep is caught pre-deploy","Feature-flag PDF uploads based on importability"],"tags":["dependency","pdf","optional-import"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}