若要在 Java 中將檔案轉換為 Base64,請使用 java.nio.file.Files 將檔案讀入位元組陣列,再將其傳遞給 java.util.Base64.getEncoder().encodeToString(bytes);;自 Java 8 起,標準程式庫內建 java.util.Base64,無需第三方相依套件,編碼器會逐位元組保留每個位元組,包括零位元組與任意二進位序列;輸出使用 RFC 4648 標準字母表 A–Z、a–z、0–9、加號與斜線,最後一組一律以一個或兩個等號填補,使結果長度為四的倍數。由於編碼將三個輸入位元組表示為四個輸出字元,因此 1024 位元組的檔案會產生恰好 1368 個 Base64 字元(含填補),即該輸入長度的標準填補大小。同一個類別也提供 getDecoder()、getUrlEncoder() 與 getMimeEncoder(),因此只需一個 import 就能使用反向解碼、URL 安全或換行的變體。若要快速驗證而無需撰寫測試程式,基於瀏覽器的檔案轉 Base64 轉換器可在不上傳位元組的情況下,從本地檔案產生相同的標準文字,這在將 Java 輸出與參考字串進行比對時非常實用。

convert file to base64 in java
使用 java.util.Base64 將檔案轉換為 Base64

Java 自 Java 8 起內建的 Base64 支援

自 Java 8 起,標準程式庫納入 java.util.Base64,位於 java.base 模組中,因此類別路徑上不需要額外的相依套件。三個編碼器工廠透過靜態方法公開:getEncoder() 傳回標準的 RFC 4648 編碼器,getUrlEncoder() 傳回 URL 與檔名安全變體(將加號替換為減號、斜線替換為底線),getMimeEncoder() 則傳回每隔 76 個字元換行,並在最後一行後附加 CRLF 的編碼器,符合歷史上的 MIME 規範。另有三個對應的解碼器以構成完整的 API。

標準編碼器接受位元組陣列並產生單一 ASCII 字串,使用標準字母表;當輸入長度不是三的倍數時,會以一個或兩個 = 字元作為填補。由於實作以位元組而非字元運作,因此絕不會解讀內容:JPEG、PDF、加密資料或可執行檔皆可原封不動通過。不會進行行尾轉換、影像重新編碼、UTF-8 正規化、檔頭檢查或詮釋資料重寫。此類別可逆,將編碼後的字串傳遞給 getDecoder().decode() 會逐位元地還原原始位元組陣列。

如何在 Java 中將檔案轉換為 Base64

從磁碟上的檔案到 Base64 字串的最短實用路徑,是使用 java.nio.file.Files 載入位元組,並使用 java.util.Base64 進行編碼。以下步驟假設使用 Java 8 或更新版本的工具鏈,且 JVM 可讀取該檔案路徑。

  1. 匯入類別。加入 import java.nio.file.Files;、import java.nio.file.Path;、import java.nio.file.Paths; 與 import java.util.Base64;,然後將主體包裹在處理 java.io.IOException 的 try-catch 中。
  2. 解析路徑。使用 Path path = Paths.get("invoice.pdf"); 建立 Path;視需要將參數替換為絕對路徑,或從引數、組態、環境變數讀取的路徑。
  3. 讀取位元組。呼叫 byte[] data = Files.readAllBytes(path);;這會將整個檔案載入記憶體,在現代 JVM 上對於數百 MB 以內的檔案是可接受的,也是遠低於大多數瀏覽器轉換器所採用 10 MB 門檻之檔案的標準選擇。
  4. 使用標準編碼器編碼。呼叫 String b64 = Base64.getEncoder().encodeToString(data);;結果為標準字母表的 ASCII 字串,以 = 填補至四的倍數長度。
  5. 使用該字串。將 b64 傳遞給 JSON 欄位、HTTP 標頭、資料庫欄位、屬性檔或測試固件;將其視為一般 ASCII 字串處理,並記住其大小約比來源大三分之一。
  6. 確認大小。以 4 * ceil(bytes.length / 3) 計算預期字元數;若實際長度不符,表示編碼器並非 RFC 4648 標準,接收端系統可能會拒絕。

對於 1024 位元組的檔案,預期的 Base64 長度為 4 * ceil(1024 / 3) = 4 * 342 = 1368 個字元,包含最後一組的兩個填補符號。編碼會使酬載增加約三分之一,因此 1 MB 的檔案會變成約 1.33 MB 的文字。請據此規劃日誌行、工單欄位與資料庫欄位。

java.util.Base64 中的編碼器與解碼器變體

方法字母表填補換行典型用途
getEncoder()A–Z a–z 0–9 + /必須為 =無RFC 4648 標準輸出、JSON 欄位、標頭
getUrlEncoder()A–Z a–z 0–9 - _必須為 =無查詢字串、檔名、URL 中的權杖
getMimeEncoder()A–Z a–z 0–9 + /必須為 =每 76 字元換行並加上結尾 CRLF電子郵件本文、MIME 附件、舊式傳輸
getDecoder()僅標準 + /嚴格拒絕空白字元getEncoder() 的反向
getUrlDecoder()僅 URL 安全 - _嚴格拒絕空白字元getUrlEncoder() 的反向
getMimeDecoder()僅標準 + /嚴格忽略換行getMimeEncoder() 的反向

請選擇符合接收端預期的編碼器。常見的錯誤是將 MIME 換行輸出傳送給不會去除換行的 JSON 解析器,或將 URL 安全輸出傳送給只認識加號與斜線的解碼器。有疑慮時,標準的 getEncoder() 加 getDecoder() 配對是最安全的預設選擇。

在 Java 中將 Base64 解碼回檔案

反向流程與編碼路徑互為鏡像。讀取編碼後的字串,將其交給 getDecoder().decode(),再將產生的位元組陣列寫入磁碟。

  1. 移除輸入可能被包裹的任何容器:僅在確認前綴格式正確時,才移除 data: URL 前綴及其後的逗號;僅在酬載是由 getMimeEncoder() 產生時,才移除 MIME 換行。
  2. 呼叫 byte[] bytes = Base64.getDecoder().decode(encoded);;解碼器要求使用標準字母表與 = 填補,且會拒絕空白字元、缺少填補或非零填補位元。
  3. 使用 Path out = Paths.get("decoded.bin"); 建立目的路徑;選擇能反映實際格式(而非 Base64 前綴)的檔名與副檔名。
  4. 呼叫 Files.write(out, bytes); 將位元組寫入磁碟;Files.write 會建立檔案或覆寫既有檔案。
  5. 當完整性至關重要時,請使用適當的應用程式或諸如 SHA-256 等加密雜湊來驗證結果,因為副檔名並不會檢查位元組內容。

嚴格解碼很重要,因為相同的酬載可能以多種看似有效的形式書寫。java.util.Base64 中的解碼器透過重新編碼結果並進行比對,以強制執行標準形式;非標準的輸入會拋出 IllegalArgumentException,而非靜默地產生不同的位元組陣列。

使用本地瀏覽器工具驗證 Java 輸出

在跨服務傳送 Base64 之前,確認 Java 輸出與參考字串逐位元相同會有所助助。本地瀏覽器的「檔案轉 Base64 轉換器」可接受最大 10 MB 的檔案,並產生相同的標準 RFC 4648 填補文字,全程在當前分頁內完成,不會上傳位元組,這在與規格或測試固件中的預期值進行比對時非常實用。在反向方面,相同的工具接受不含空白字元的標準 Base64,由您提供檔名與 MIME 類型,並產生可供下載與檢查的臨時 Blob URL。

保留不做
來源的精確位元組內容轉碼影像或重寫媒體
零位元組與任意二進位內容正規化行尾
原始檔案格式與標頭檢查或推斷檔案格式
RFC 4648 要求的填補新增 data: URL 前綴
標準的零填補位元插入 76 字元的換行

由於瀏覽器透過W3C File API以 ArrayBuffer 形式讀取檔案,且絕不將位元組傳送至伺服器,因此您可在與 Java 程式碼相同的可信機器上使用。對於包含憑證、個人資料、簽章金鑰或可執行酬載的檔案,請避免使用共用或不可信的機器:Base64 是編碼而非防護,其產生的字串仍可能攜帶原始檔案的所有內容。若要深入了解標準輸出與嚴格解碼器行為,RFC 4648 標準輸出逐步解說與本指南相輔相成。

填補與填補位元的陷阱

RFC 4648 標準輸出以零、一或兩個 = 字元作結,使編碼長度為四的倍數。當最後一組包含一個輸入位元組時,會產生兩個字元與兩個填補符號;當包含兩個輸入位元組時,則產生三個字元與一個填補符號。省略填補或接受格式錯誤填補的解碼器,可能會掩蓋輸入中的真實差異。更嚴格的問題在於非零填補位元:最後一個字元中未使用的位元不承載資訊,因此標準編碼器一律寫入零;若發送端寫入非零值以夾帶資料,解碼器必須拒絕該輸入。RFC 4648 定義了字母表、填補與鎖定正確性的測試向量,包括空字串、f、fo、foo、foob、fooba 與 foobar。

  • 混用字母表。URL 安全與標準字母表不可互換。預期接收加號與斜線的接收端,在遇到減號與底線時將會失敗。
  • 保留換行字元。getEncoder() 絕不會插入換行,但許多複製貼上的來源會在 76 字元處換行;嚴格的 getDecoder() 會拒絕這些輸入,除非您改用 getMimeDecoder() 或先去除換行。
  • 輕信檔名。解碼後的位元組本身沒有內建的副檔名;將 decoded.bin 改名為 decoded.pdf 並不會使其成為 PDF。請以正確的應用程式開啟檔案,或計算其雜湊值。
  • 混淆編碼與安全性。Base64 是可逆的。它並非加密、雜湊、簽章、壓縮、淨化或惡意程式掃描。請為這些工作分別使用真正的對應機制。

若您正在權衡各種方案,Base64 轉 Hex 解說:位元組層級逐步剖析對此有詳細說明。