EPUB 使用指南

EPUB 無法匯入閱讀器，最常見的容器問題

有些 EPUB 在電腦上可以正常開啟，放到電子紙閱讀器或書庫軟體卻被拒絕。問題往往不在書的內容，而是 EPUB 外層容器沒有按照標準封裝。

EPUB 不是單純的 ZIP 檔案

EPUB 的副檔名雖然是 .epub，但本質上是一個遵循 W3C 公布容器規範的 ZIP 封存。OCF（OEBPS Container Format）定義了 EPUB 的 ZIP 內部必須滿足的條件：mimetype 必須是第一個 entry、必須使用不壓縮的 Stored 方法儲存、內容必須精確為 application/epub+zip。這些條件缺少任何一項，都可能在閱讀器上造成匯入失敗。

舉例來說，macOS 的 Finder 在解壓縮 EPUB 時會自動產生 __MACOSX 資料夾與 ._* 隱藏檔案，這些不屬於 EPUB 標準的內容會讓某些閱讀器的驗證程式直接拒絕匯入。Windows 的內建 ZIP 工具雖然可以開啟 EPUB，但重新壓縮時往往把 mimetype 放在錯誤的位置，導致 EPUB 變成無效的容器。

檢查 EPUB 容器是否合格

一個合格的 EPUB 容器必須滿足以下條件：ZIP 檔案的第一個 entry 是 mimetype，且內容只能是 application/epub+zip，不帶 BOM 或換行。ZIP 的根目錄必須包含 META-INF/container.xml，這個檔案會指向實際的 Package Document，通常是 content.opf。如果容器缺少 container.xml 或指向的 OPF 檔案不存在，閱讀器就無法找到書籍內容的起始點。

EPUB Tools 在檢查時會逐一驗證這些條件：讀取 ZIP 的 entry 清單，確認 mimetype 的順序與內容，解析 container.xml 並確認它指向的 OPF 檔案可以讀取。如果 OPF 中的 manifest 列出的檔案實際不存在於 ZIP 中，工具也會標記為警告，但不會自動移除這些 entry，因為這可能涉及書籍內容層級的修改。

常見的容器錯誤與修復方式

第一類錯誤是 mimetype 問題。有些工具在建立 EPUB 時會在 mimetype 前加入額外的 entry，例如 macOS 的 Finder 在壓縮時會先寫入一個 ._mimetype 的 Apple Double 檔案。修復方法是重建一個全新的 ZIP 容器，將 mimetype 以 Stored 方式放在第一個位置，再依序寫入其他檔案。

第二類錯誤是 container.xml 遺失或指向錯誤。有些 EPUB 在經過郵件附件或雲端硬碟傳輸後，container.xml 會被改成空檔案或指向不存在的路徑。修復時需要掃描 ZIP 內所有 .opf 檔案，根據合理的路徑猜測哪一個是正確的 Package Document，然後重建 container.xml。

第三類錯誤是 系統垃圾檔案污染。.DS_Store、Thumbs.db、__MACOSX 與 ._* 檔案不屬於 EPUB 標準，也不會影響閱讀器讀取內容，但有些閱讀器的匯入流程會因為這些「非預期」的 entry 而判定 EPUB 格式錯誤。修復時可以直接將這些檔案排除在重建的 ZIP 之外。

風險與限制

容器層級的修復不會修改書籍的文字、圖片、CSS、字型或 metadata，但仍有少數情況需要注意。如果 EPUB 使用了 ZIP 64 延伸格式（超過 4GB 或內部檔案超過 65535 個），部分瀏覽器實作的 ZIP 處理程式可能無法正確讀取。此外，如果 EPUB 的 content.opf 遺失且 ZIP 內完全找不到任何 .opf 檔案，工具無法自動重建 OPF，因為書籍的結構資訊已經不存在。

EPUB Tools 在瀏覽器記憶體中完成所有處理，不會將書籍上傳到任何伺服器。瀏覽器版會產生新的 EPUB 檔案供下載；如果需要保持原始檔案路徑不變，請使用開源專案提供的 Python 本機版本，該版本支援交易式原地替換與批次修復。

在 ZIP 的底層結構中，每個 entry 都包含一個 local file header，記錄了檔案名稱、壓縮方式、CRC-32 校驗碼、壓縮前後大小等資訊。mimetype 之所以必須是第一個 entry，是因為部分閱讀器在讀取 EPUB 時，只會讀取 ZIP 的第一個 local file header 來判斷檔案類型，而不會掃描整個 ZIP 的 Central Directory。如果第一個 entry 不是 mimetype，閱讀器可能直接判定檔案格式錯誤，而不會繼續讀取其他內容。這種設計在嵌入式裝置上特別重要，因為這些裝置的記憶體與運算資源有限，無法負擔完整掃描 ZIP 結構的開銷。

此外，mimetype 的 local file header 中不能包含 extra field，因為某些閱讀器會檢查 extra field 是否存在。標準的 EPUB 工具在建立容器時，會刻意將 mimetype 的 extra field 長度設為零，以確保最大相容性。EPUB Tools 在重建容器時，會使用底層的位元組操作來精確控制 local file header 的每一個欄位，而不是依賴高階的 ZIP 函式庫，因為許多高階函式庫無法控制 extra field 的存在與否，這可能導致修復後的 EPUB 仍然無法通過部分閱讀器的嚴格驗證。

開始檢查 EPUB