Base64 看起來很簡單：輸入內容，得到一串更長的 ASCII 字元。但實際開發中，Base64 出錯往往不是演算法錯，而是補位缺失、URL-safe 字元集混用、複製了 Data URL 前綴、字元編碼不一致，或者在錯誤的層級解碼。

這篇指南按排錯順序說明如何定位問題。

Base64 到底在做什麼

Base64 是把位元組轉換成 ASCII 字元，讓二進位資料可以通過只接受文字的系統傳輸。常見情境包括：

  • JSON 裡的小圖片或檔案欄位
  • 電子郵件附件
  • HTTP Basic Auth 標頭
  • JWT 片段
  • data:image/png;base64,... 這類 Data URL
  • 日誌、表單或臨時介面裡的二進位傳輸

Base64 不是加密。拿到字串的人都可以解碼。如果內容敏感，應先加密或使用安全傳輸通道，而不是依賴 Base64。

先確認輸入真的是 Base64

有些「Base64 解碼失敗」的根因更早：貼上的內容根本不是 Base64。它可能是 URL 編碼、JSON 字串、十六進位傾印、HTML 實體，或者一段看起來像編碼的錯誤訊息。

改程式碼前先看字元：

  • %2F、%3D、%2B 通常說明還殘留 URL 編碼
  • \xE4 或 0xE4 通常是位元組轉義或十六進位，不是 Base64
  • {、:、" 通常說明貼上的是 JSON，而不是單獨的編碼欄位
  • 空格、Tab 和自動換行在寬鬆解碼器裡可能被忽略，但嚴格解碼器會拒絕

如果值來自 URL 參數，先解 URL 這一層。如果值來自 JSON，先單獨取出欄位值再解碼。

先確認字元集

標準 Base64 使用：

A-Z a-z 0-9 + /

URL-safe Base64 會替換兩個字元：

+ 變成 -
/ 變成 _

JWT 和 URL 參數裡經常使用 Base64URL，而且常常省略補位。把 JWT 片段直接放進嚴格的標準 Base64 解碼器，可能會報錯。此時要麼使用 URL-safe 模式，要麼先規範化字元集和補位。

補位錯誤怎麼判斷

Base64 常用 = 補位，使長度成為 4 的倍數：

TWFu
TWE=
TQ==

有些系統會省略補位，尤其是 URL-safe 編碼。遇到「invalid length」或「incorrect padding」這類錯誤時，先數長度：

  • 長度能被 4 整除：補位大概率沒問題
  • 餘 2：通常補 ==
  • 餘 3：通常補 =
  • 餘 1：通常說明字串被截斷或複製不完整

不要一上來就盲目補 =。先確認日誌、複製、換行、資料庫欄位長度沒有把字串截斷。

解碼 Data URL 前先去掉前綴

圖片 Base64 經常以 Data URL 形式出現：

data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...

逗號前面的部分只是描述 MIME 類型和編碼方式，不是 Base64 內容。真正需要解碼的是逗號後面的字串。把整段一起解碼，要麼失敗，要麼得到無效位元組。

排查圖片上傳時，確認三件事：

  1. MIME 類型是否符合預期檔案格式
  2. Base64 內容是否從逗號後開始
  3. 解碼後的位元組是否能作為對應檔案開啟

Unicode 文字：Base64 編碼的是位元組，不是字元

Base64 處理的是位元組。文字必須先按 UTF-8 等編碼轉成位元組，再進行 Base64 編碼。中文、日文、Emoji 和很多符號，一個字元會佔多個 UTF-8 位元組。

如果傳送方按 UTF-8 編碼，接收方卻按 Latin-1 或其他編碼解釋，Base64 字串本身可能完全正確，但解碼後的文字會亂碼。

遇到亂碼時，檢查：

  • 原始文字是否按 UTF-8 轉成位元組
  • 接收方是否按 UTF-8 解碼
  • 資料是否被重複 Base64 編碼
  • 日誌工具是否截斷或改寫了字串

可以把 UTF-8 轉換工具 和 Base64 編碼解碼工具 結合使用，同時檢查位元組和文字。

API Payload 排錯清單

API 裡的 Base64 欄位失敗時，按這個順序排查：

  1. 欄位裡是否只有編碼值，沒有 JSON 引號、標籤或 Data URL 前綴
  2. 介面需要標準 Base64 還是 URL-safe Base64
  3. 長度是否說明可以安全恢復補位
  4. 用同一個介面提供一個小的已知正確樣本
  5. 對比解碼後的位元組長度是否符合預期
  6. 如果解碼後是 JSON，再用 JSON 工具校驗結構

這樣能把傳輸層問題和業務邏輯問題分開。

JWT 和 token 提醒

JWT 的 header 和 payload 是 Base64URL 編碼，但解碼 JWT 不等於驗證 JWT。JWT 的可讀性是設計的一部分，真正的安全性來自簽章驗證。

除錯 token 時，不要把正式環境 token 貼到不可信工具裡。即使 payload 看起來合理，也必須通過簽章驗證後才能相信其內容。

常見現象與原因

出現非法字元錯誤，通常是包含空格、換行、URL 編碼、Data URL 前綴，或標準/URL-safe 字元集混用。

出現長度錯誤，通常是缺少補位、字串被截斷，或複製時漏了字元。

圖片能解碼但打不開，通常是檔案類型不匹配、把前綴一起解碼，或編碼前內容已損壞。

文字亂碼，通常說明 Base64 是有效的，但原始位元組被用錯誤的字元編碼解釋。

如果同一段輸入在一個解碼器裡可用，在另一個解碼器裡失敗，比較兩者是否啟用了嚴格模式。有些解碼器會忽略空白和缺失補位，有些會按更嚴格規則直接報錯。

推薦工作流

從最小失敗樣本開始。先解碼、看長度、檢查前幾個位元組，再回到產生它的系統裡對比。同一個小樣本能跑通後，再處理完整 Payload。

可以使用 Base64 編碼解碼工具 測試標準和 URL-safe 輸入，再搭配 UTF-8 轉換工具、JSON 格式化工具 和 URL 編碼工具 排查更複雜的介面資料。