EPUB 使用指南

批次修復的安全性——錯誤隔離與交易式處理

當你一次處理數十本甚至上百本 EPUB 時，安全性是最重要的考量。如果一本書的修復過程中發生錯誤，會不會影響到其他已經修復完成的書？原始檔案會不會被破壞？EPUB Tools 的批次修復流程從設計上就確保了錯誤隔離與資料保護。

錯誤隔離：每本書獨立處理

EPUB Tools 的批次處理核心原則是「每本書獨立運作」。當你選擇一個包含多本 EPUB 的資料夾時，工具會先掃描資料夾，找出所有副檔名為 .epub 的檔案，以及所有包含 META-INF/container.xml 的資料夾。每一本書被視為一個獨立的處理單元，擁有自己的處理狀態、錯誤訊息與修復結果。

這個設計意味著，如果第 5 本書因為 ZIP 64 格式無法讀取而失敗，第 1 到第 4 本書的修復結果不會受到任何影響。失敗的書不會阻塞整個處理佇列，工具會繼續處理第 6 本、第 7 本，直到所有書都處理完畢。在處理完成後，使用者可以查看每本書的個別狀態，並選擇性地下載成功修復的檔案。

交易式處理：要嘛全部完成，要嘛完全不動

在瀏覽器版本中，修復流程是「先全部讀取，再全部處理，最後一次提供下載」。每本書的修復過程都在記憶體中進行，原始檔案從來不會被修改。這是一個「唯讀」的處理模式：工具讀取原始 EPUB 的內容，在記憶體中建立新的 ZIP 容器，然後將修復後的結果提供給使用者下載。原始檔案從頭到尾都沒有被寫入或改變。

Python 本機版本則支援更進階的交易式處理。當使用者啟用原地替換模式時，工具會先將修復後的 EPUB 寫入到一個暫存目錄，確認暫存檔案可以正常讀取後，才用 os.replace() 原子性地替換原始檔案。如果替換過程中發生任何錯誤（例如磁碟空間不足），工具會自動回復到原始檔案，不會留下半損毀的檔案。

備份機制：多層保護

EPUB Tools 提供了三層備份保護。第一層是瀏覽器版本的記憶體處理：原始檔案永遠不會被修改，使用者可以在任何時候重新載入頁面，從頭開始。第二層是 Python 版本的原始備份：在進行原地替換之前，工具會將原始 EPUB 複製到一個 .backup 目錄中，備份檔案的名稱包含時間戳記，方便使用者回溯到特定版本。第三層是使用者的作業系統備份：如果使用者啟用了 Time Machine（macOS）或檔案歷程記錄（Windows），任何意外修改都可以透過系統層級的備份來還原。

需要注意的是，瀏覽器版本的記憶體是短暫的。重新整理頁面或關閉瀏覽器標籤頁後，所有修復結果就會消失。因此建議在批次修復完成後，立即下載所有修復後的 EPUB 檔案，並將它們儲存到安全的位置。

失敗處理與日誌

每本書在處理過程中會產生詳細的處理日誌，記錄每一個步驟的結果。如果一本書的修復失敗，日誌中會包含失敗的具體原因，例如「mimetype 內容無效但無法自動修復」或「ZIP 檔案已損毀，無法讀取 entry 清單」。使用者可以根據這些日誌來判斷哪些書需要手動處理，或是需要進一步的檢查工具。

日誌內容不會包含書籍的實際內容，只包含容器結構的檢查結果。這確保了即使在使用者共享日誌以尋求協助時，也不會暴露書籍的文字或圖片內容。

限制與注意事項

批次修復有其限制。第一，如果 EPUB 使用了 ZIP 的加密功能（密碼保護或 AES 加密），工具無法讀取這些檔案，必須跳過。第二，如果 EPUB 的檔案名稱編碼不是 UTF-8，在部分瀏覽器上可能無法正確顯示。第三，批次修復的效能取決於瀏覽器的記憶體限制，一次處理超過數百本 EPUB 時，瀏覽器可能因為記憶體用量過高而變慢或崩潰。建議將大型書庫分批次處理，每次不超過 100 本。

此外，EPUB Tools 的容器修復不會處理書籍的內容驗證。如果 EPUB 的 content.opf 中的 manifest 遺漏了某些檔案，工具不會自動補上，只會在檢查結果中標記為警告。使用者需要手動確認這些警告是否影響閱讀體驗。

開始檢查 EPUB