기술 · 실용 가이드
EPUB에서 ‘no item named’ 오류? 책을 고치기 전에 누락된 ZIP 항목부터 추적하세요
스크립트 누락, 장 누락, 대소문자 불일치는 같은 KeyError를 낼 수 있습니다. 네 통제 예제는 ZIP 검사 통과가 EPUB 완전성 검사가 아닌 이유를 보여 줍니다.
EPUB에서 특정 경로의 항목이 없다는 오류는 압축파일 항목 검색 실패를 뜻합니다. 빠진 것이 장인지, 스크립트인지, 참조 철자 오류인지는 알려 주지 않습니다. 변경 전에 원본과 오류 경로 전체를 보존하세요.
Python 3.12.14, EbookLib 0.20.0, lxml 6.1.3에서 직접 만든 로컬 EPUB 3 네 개를 시험했습니다. 대조 파일은 로드됐지만 manifest에 선언된 스크립트 제거, spine의 두 번째 장 제거, 장 참조 한 글자의 대문자 변경은 모두 KeyError를 냈습니다. 네 파일 모두 ZipFile.testzip()을 통과했고 감사 중 원본 해시는 바뀌지 않았습니다.
이는 패키지 검색 시험이며 대조 파일의 완전한 EPUB 적합성이나 기기의 올바른 표시를 입증하지 않습니다. EPUBCheck, Calibre, EpubSplit, 그래픽 리더는 실행하지 않았습니다. 같은 예외를 서로 다른 조사로 연결하는 비교를 제공합니다.
패키지의 참조를 따라 압축파일까지 확인하기
파일을 풀거나 덮어쓰지 않고 압축파일 목록을 확인하세요. Python 명령은 python -m zipfile -l book.epub입니다. META-INF/container.xml에서 패키지 문서 위치를 찾습니다. 예제는 OEBPS/package.opf였으므로 manifest의 Text/chapter2.xhtml은 OEBPS/Text/chapter2.xhtml을 가리켰습니다.
manifest ID, 원래 href, 미디어 유형, 해석한 항목 이름, 정확한 존재 여부, spine 위치를 기록하세요. W3C는 패키지 문서를 그 안 URL의 기준으로 정하고 컨테이너 이름의 대소문자를 구분합니다. 시험은 단순한 로컬 경로만 다뤘습니다. 원격 자원, 인코딩된 이름, 조각 식별자, 다중 렌디션, 잘못된 XML은 해당 URL·패키지 규칙을 따라야 하며 파일시스템 경로를 추측해 합치면 안 됩니다.
본문 누락과 참조 불일치 구분하기
장 누락 예제의 c2는 spine 위치 2에서 없는 OEBPS/Text/chapter2.xhtml을 가리켰습니다. 빈 장을 대신 넣거나 예외를 건너뛴 뒤 결과를 완전하다고 표시하지 마세요. 수정된 원본을 받거나 권한 있는 제작자에게 실제 본문과 링크를 복원해 달라고 해야 합니다.
대소문자 불일치 예제에서 manifest는 Text/Chapter1.xhtml을 요청했지만 압축파일에는 Text/chapter1.xhtml이 있었습니다. 감사는 대소문자가 다른 후보를 보고했으며 자동 선택·이름 변경을 하지 않았습니다. 수정 전에 모든 참조와 제작자의 의도를 확인하세요. 비슷한 이름은 단서이지 동등함의 증거가 아닙니다.
spine 밖의 스크립트도 자동 삭제하면 안 되는 이유
OEBPS/js/unused.js를 제거해도 spine의 두 장이 남아 있는데 EbookLib가 중단됐습니다. 모든 파일을 직접 만든 합성 예제라 이 스크립트가 쓰이지 않음을 알았지만 다른 사람 책의 spine 밖 스크립트는 본문이 참조하거나 기능을 지원할 수 있습니다.
의존 관계를 추적하고 제작자에게 자원을 복원하거나 오래된 선언과 참조를 의도적으로 제거해 달라고 하세요. 누락된 로컬 파일을 허용된 원격 자원으로 분류하거나 같은 이름의 스크립트를 내려받아 넣거나 모든 KeyError를 잡아 계속 진행하지 마세요. 업스트림 이슈 281이 이미 이런 manifest 로드 실패를 설명하므로 새로운 메커니즘을 발견했다는 뜻은 아닙니다.
ZIP·출판물·최종 전달 검사를 나누기
testzip()은 저장된 항목의 CRC와 헤더를 검사하며 출판물에 원래 어떤 항목이 있어야 하는지는 모릅니다. 장 누락을 포함해 네 예제 모두 None을 반환했습니다. EbookLib가 대조 파일을 로드했다는 것은 시험 옵션에서 그 파서가 받아들였다는 뜻이며 완전한 EPUB 적합성은 아닙니다.
Calibre 문서의 Tools → Check book은 끊어진 링크와 OPF 문제를 보고하고 W3C는 EPUBCheck 같은 적합성 검사기를 권장합니다. 작업 사본에서 기존 경로를 사용하고 보고서를 보존하세요. 권한 있는 수정 후 원래 실패한 작업을 다시 실행하고 장 순서와 본문을 비교한 뒤 필요한 읽기 흐름을 시험하세요. 원본과 미해결 자원을 기록해야 합니다. 재시도 성공만으로 글이나 기능이 하나도 사라지지 않았다고 입증할 수는 없습니다.
