Base64 編碼會把二進位影像檔轉成單行純 ASCII 文字,這樣才能在 n8n 裡透過 JSON 承載、HTTP 請求和 Code 節點傳遞。若要在 n8n 工作流程中將影像轉成 base64,請在瀏覽器型編碼器(例如 Image to Base64 Converter)中開啟本機的 PNG、JPEG、GIF 或 WebP 檔案,在純 Base64 字串與完整 data URL 之間擇一,執行轉換,確認偵測到的格式與解碼後的尺寸,再把文字複製到工作流程中。有幾個透過 n8n 連線的第三方服務,當字串包含換行、空格,或與實際檔案位元組不符的 data URL 前綴時,會拒絕接收影像承載,因此編碼器必須依位元組來驗證容器,而不是依賴檔名。該轉換器同時強制設定 5 MiB 的輸入上限、最多 6,990,531 字元的輸出上限,以及邊長 20,000 像素、總面積 40,000,000 像素的邊緣限制,這些在 n8n 的 Code 節點內組裝承載時全都必須考慮。
為什麼 n8n 工作流程需要 Base64 影像字串
n8n 以 JSON 或二進位項目的形式在節點之間傳遞資料,而並非每個下游服務都能接受二進位項目。視覺模型的 API、OCR 引擎(例如 CapSolver)、ERP 整合(例如 Odoo),以及許多 webhook 端點,都期望影像以字串屬性的形式內嵌傳入。這些整合的標準模式是:一個觸發節點、一個拉取檔案的 Read Binary File 或 HTTP Request 節點、一個把位元組轉成字串的 Code 或 Function 節點,最後是一個 JSON 主體中含有該字串的外送 HTTP Request 節點。
當檔案抵達接收端服務時,通常必須同時滿足兩個條件:該字串必須是不含換行或空白字元的單一連續行;而所使用的 data URL 前綴,則必須與檔案的實際容器相符。一個被改檔名為 photo.jpg 的 PNG,所期待的仍是 data:image/png;base64,而不是 data:image/jpeg;base64,若前綴與解碼後的位元組不一致,許多視覺 API 會拒絕呼叫。
在 Code 節點中處理這件事,適合已經在流程中的檔案;但在開發階段,你通常會想要一條可以貼進 Set 節點、模板字面值、JSON fixture 或測試 webhook 的參考字串。一個在本機執行、絕不上傳檔案、並從位元組驗證容器的瀏覽器編碼器,就是在串接執行階段路徑前取得該參考值最乾淨的方式。
取得一條乾淨的 Base64 字串給 n8n 使用(逐步教學)
- 在準備複製內容的同一個瀏覽器分頁中開啟 Image to Base64 Converter,這樣剪貼簿結果才不會被其他應用程式擋住。
- 點選檔案輸入欄位,挑一張你打算透過 n8n 傳送的 PNG、JPEG、GIF 或 WebP 檔案。此工具最多讀取 5,242,880 位元組;只要超過一個位元組,就會在讀取主體前直接拒絕。
- 選擇輸出模式:若你的下游服務需要原始字串,請選純 Base64;若需要帶前綴的完整 data:image/...;base64,... 值,則選 data URL。
- 執行轉換,並等候預覽、偵測到的位元組格式、解碼後的尺寸與檔案大小出現。
- 檢查偵測到的格式字串。它必須與檔案的實際容器相符。即使是改檔名為 .jpg 的 PNG,回報的仍會是 image/png,而這個值也會出現在 data URL 前綴中。
- 點選複製按鈕。產生的文字就會進入你的剪貼簿,不會帶任何換行、額外空白或包裝。
- 把該字串貼到你的 n8n Set 節點欄位、Code 節點變數,或 JSON fixture 中。
若在成功轉換後切換檔案或輸出模式,先前的預覽、輸出、錯誤與複製狀態會自動清除。請在每次變動後重新複製,以免貼到過期的值。若剪貼簿寫入被拒絕,可見文字仍可選取,你可以用鍵盤快捷鍵手動複製。
把輸出貼進 n8n 的 Code 節點或 Set 節點
在 n8n 中,轉換後的字串通常會落到三個位置之一:在 Set 節點中作為字串屬性(例如 image_base64)的值、在 Code 節點運算式中被包進 JSON 主體,或是作為靜態工作流程值,用於在換成即時二進位串流前先測試整合。瀏覽器轉換器所產生的參考字串,讓你在串接執行階段編碼路徑前,就能確認下游呼叫能正常運作。
當你從已測試的參考字串,進展到在 n8n 內部進行執行階段轉換時,可加入一個 Code 節點來讀取二進位項目,並透過 Buffer.from(data).toString('base64') 對緩衝區進行編碼。常見的模式如下:
const item = $input.item; const buffer = await this.helpers.getBinaryDataBuffer(0, item.binary.data.fieldName); const b64 = buffer.toString('base64'); return { json: { image_base64: b64, mime: item.binary.data.mimeType } };
使用轉換器產生的值,就能確認你的 HTTP Request 節點所送出的承載是接收端服務能接受的。若服務拒絕該呼叫,首要檢查的就是 MIME 字串。許多服務會驗證 data URL 前綴是否與容器相符,而轉換器對已驗證位元組所做的偵測,正是釐清此類不一致最簡便的方式。至於反向作業,也就是 n8n 工作流程接收一條 base64 字串並必須把它轉回影像檔的部分,Decode a Base64 Image from an n8n Workflow 指南中介紹了對應的 Code 節點模式。
影響 n8n 承載的格式與大小限制
每一次容器檢查都是依實際檔案位元組進行;檔名、檔案選擇器的篩選條件、以及作業系統回報的 MIME 型態,都不能決定格式。這正是你在把值貼進 n8n 承載時想要的特性——data URL 前綴必然與位元組一致,而非與檔名一致。
| 容器 | 檔案位元組中的偵測訊號 | 產生的 data URL 前綴 |
|---|---|---|
| PNG | 八位元組簽章、合法的第一個 IHDR chunk、結尾的 IEND 邊界 | data:image/png;base64, |
| JPEG | SOI 標記、合法的後續標記、結尾的 EOI 標記 | data:image/jpeg;base64, |
| GIF | GIF87a 或 GIF89a 標頭、邏輯螢幕描述子、結尾的 trailer | data:image/gif;base64, |
| WebP | 與檔案大小相符的 RIFF 長度、WEBP FourCC、合法的 VP8、VP8L 或 VP8X 第一個 chunk | data:image/webp;base64, |
完成偵測後,轉換器會在瀏覽器中透過 createImageBitmap 解碼檔案(並附上 HTMLImageElement 作為 fallback)。即使某個損毀的承載只是模擬出標頭,只要瀏覽器回報的尺寸不為正,就不會產生任何輸出——也就是說,在產生任何文字之前,具誤導性的前綴或殘缺的簽章會先被擋下。
| 限制 | 精確數值 | 為何對 n8n 很重要 |
|---|---|---|
| 最大輸入檔案大小 | 5,242,880 位元組(5 MiB) | 更大的檔案會在讀取主體前被拒絕 |
| 最大 Base64 輸出長度 | 6,990,508 字元 | 輸入上限再多一個位元組,就會讓輸出超過此限制 |
| 最大 data URL 輸出長度 | 6,990,531 字元 | 已含最長的支援 data URL 前綴 |
| 解碼後的最大邊長 | 每邊 20,000 像素 | 任一邊超過即會被拒絕 |
| 解碼後的最大總像素數 | 40,000,000 | 即使邊長符合,超過此值仍會被拒絕 |
輸出上限是輸入上限與 RFC 4648 字元表的直接推論。依該標準,每三個輸入位元組會對應到四個輸出字元,使用大寫字母、小寫字母、數字、加號與斜線。當最後一組只剩一個或兩個位元組時,編碼器會補上一個或兩個等號,讓解碼端能還原原始長度。套用到最大可接受的輸入上:5,242,880 位元組除以三,可得到 1,747,626 個完整組別,餘數為 2,因此會產生 1,747,627 組共 6,990,508 字元的純 Base64。再加上最長的 data URL 前綴,就是轉換器所強制設定的 6,990,531 字元上限。你可以透過 RFC 4648 直接驗證分組與填補的各種情況。
Base64 也會在任何前綴加入之前,讓資料量增加大約三分之一,所以 1 MiB 的影像在 n8n 的 JSON 主體中會變成大約 1.33 MiB 的文字。對 JSON 屬性而言,數 MB 的影像通常不是好的選擇;若承載只是為了測試或製作 fixture,通常一小段樣本就夠了。
編碼前可考慮的相關轉換
Image to Base64 Converter 會在 Base64 承載中保留原始已驗證的檔案位元組。它不會繪製到 canvas、不會縮放、不會重新壓縮、不會重新上色、不會壓平透明度、不會移除中繼資料、不會修復損壞,也不會最佳化檔案大小,更不會從動畫 GIF 中挑選某一個影格。動畫 GIF 與 WebP 的位元組,當接收端支援時,在承載中仍會保持動畫。若你需要在編碼前縮小檔案,請先用專門的工具處理後再編碼。
- 在編碼前,可使用 Image Compressor 在瀏覽器中壓縮 JPG、PNG 或 WebP。
- 若有特定像素尺寸需求,請使用 Image Resizer;本編碼器並不調整大小。
- 至於 n8n 中的反向工作流程,請參考 Decode a Base64 Image from an n8n Workflow 指南。
此轉換器只接受這四種容器。即使瀏覽器或副檔名把它們視為影像,SVG、AVIF、HEIC、BMP、TIFF、PDF 與任意文字皆不在支援範圍。若需以 base64 形式使用,請先轉成 PNG、JPEG、GIF 或 WebP。
若要在 n8n 中於執行階段編碼,請使用對 $input.item.binary 進行處理的 Code 節點,讓每次工作流程執行都能處理實際傳入的檔案。若要產生一條要貼進工作流程的靜態字串,瀏覽器轉換器會是更安全的選擇,因為它在交給你任何可複製的文字之前,會先驗證容器與解碼後的像素。即使檔案仍保留在本機,也應把來源不明的影像視為不受信任的內容:瀏覽器成功解碼只能證明技術上可讀,並不代表其作者身分、無障礙性、著作權狀態,也不能保證未藏有隱匿資料。