如何在 Java 中向 PDF 添加條碼
是否曾需要自動追蹤發票、驗證合約真偽，或大規模管理庫存文件？學習如何以程式方式向 PDF 添加條碼 可解決這些問題——如果您使用 Java，則有一個穩固且經過實戰驗證的選擇。
手動添加條碼無法擴展。無論您是處理十張發票還是十千張，都需要可靠的方式來向 PDF 添加條碼。這時，一個好的 Java PDF 條碼函式庫就派上用場。
在本指南中，我會示範如何使用 GroupDocs.Signature 這個函式庫向 PDF Java 檔案添加條碼——它負責繁重的工作，同時讓您精細控制位置、大小與條碼類型。完成後，您將了解如何使用 Java 程式碼為 PDF 簽署條碼、處理邊緣情況，並避免開發人員常見的陷阱。
您將學到的內容：
- 為什麼條碼在 PDF 中對工作流程很重要
- 正確設定 GroupDocs.Signature for Java 的方式
- 精準建立與定位條碼簽章
- 錯誤處理與效能最佳化
- 各行各業的實務應用
快速答案
- 應該使用哪個函式庫？ GroupDocs.Signature for Java
- 如何建立條碼簽章 PDF？ 使用
BarcodeSignOptions搭配Signature.sign() - 哪種條碼類型最適合大多數情況？ Code128
- 可以在同一份 PDF 中加入多個條碼嗎？ 可以，呼叫多次
sign()或傳入列表 - 生產環境需要授權嗎？ 需要，有效的 GroupDocs 授權會移除浮水印
為什麼要在 PDF 中加入條碼？
條碼將機器可讀的資料直接嵌入 PDF，實現即時驗證、自動資料擷取，並與 ERP 或庫存系統無縫整合。加入條碼後，靜態文件會變成可掃描取得 ID、追蹤狀態、符合合規需求的可操作資產。
在進入程式碼之前，先說明這個需求的背後原因。PDF 中的條碼不只是為了看起來專業——它們解決了真實的商業問題：
文件驗證 – 條碼可編碼唯一識別碼，使偽造幾乎不可能。掃描條碼時，系統即可即時驗證文件是否合法。
工作流程自動化 – 員工（或客戶）只需掃描條碼，即可取得文件 ID 或追蹤編號，較手動輸入降低約 95 % 的人為錯誤。
與既有系統整合 – 大多數 ERP、庫存與文件管理系統已支援「條碼」；將條碼加入 PDF 後，可直接整合，無需自行開發 API。
合規需求 – 醫療、物流、法律等行業要求文件可追溯。條碼提供符合監管要求的稽核軌跡。
程式化加入條碼的關鍵優勢是一致性與規模。一次定義規則，所有文件皆得到相同處理——不論是處理五個檔案或五萬個。
前置條件
在開始編寫程式碼前，請先確保以下基礎已備妥：
必要的軟件與函式庫
- JDK 8 或更高 已安裝於您的機器（建議使用 JDK 11+ 以獲得更佳效能）
- IntelliJ IDEA、Eclipse 或具 Java 擴充功能的 VS Code 等 IDE
- GroupDocs.Signature for Java 版本 23.12（我們稍後會示範如何加入）
基本知識需求
- 熟悉 Java 基礎（類別、物件、檔案處理）
- 了解 PDF 文件結構（有助但非必須）
- 熟悉相依管理工具（Maven 或 Gradle）
專業提示：如果您是第一次接觸 GroupDocs，先取得免費試用版。它提供 30 天的試驗期，無需立即購買授權，適合概念驗證。
設定 GroupDocs.Signature for Java
將 GroupDocs.Signature 加入專案非常簡單。請依照您的環境選擇相依管理系統：
Maven 設定
將以下內容加入 pom.xml 檔案：
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-signature</artifactId>
<version>23.12</version>
</dependency>
Gradle 設定
對於 Gradle 使用者，請在 build.gradle 中加入此行：
implementation 'com.groupdocs:groupdocs-signature:23.12'
直接下載選項
不想使用建置工具？可直接從 GroupDocs.Signature for Java 釋出頁面 下載 JAR，手動加入專案的 classpath。
授權配置
以下是大多數開發者採用的實務授權流程：
- 先使用免費試用 – 無需信用卡，無任何承諾，適合測試。
- 取得臨時授權 – 若 30 天不足以完成開發，可申請延長的臨時授權。
- 購買正式授權 – 準備上線時，購買符合使用量的授權。
重要：免費試用會在輸出文件上加浮水印。若面向客戶交付，至少需要臨時授權。
初始設定程式碼
Signature 是 GroupDocs.Signature 的主要類別，提供載入、簽署與儲存 PDF 的方法。
這段程式碼的作用：Signature 類別是您的入口點，傳入檔案路徑後會將 PDF 載入記憶體以供處理。很簡單，對吧？
常見錯誤：使用完畢後別忘記關閉 Signature 物件（或使用 try‑with‑resources）。未正確關閉會在長時間執行的應用程式中造成記憶體洩漏。
import com.groupdocs.signature.Signature;
// Initialize Signature object with your document path
Signature signature = new Signature("YOUR_DOCUMENT_DIRECTORY/sample.pdf");
選擇適合的條碼類型
並非所有條碼都一樣。選擇哪種條碼取決於您要編碼的內容以及條碼的掃描環境。
支援的常見條碼類型
- Code128 – 適合字母數字混合資料；常見於運送標籤。
- QR Codes – 需要儲存較多資料（URL、JSON，最多 4 000 個字元）時的最佳選擇。
- Code39 – 比 Code128 簡單但佔用空間較大；適合內部追蹤。
- EAN/UPC – 零售商品的行業標準。
何時使用哪種？
- 需要編碼超過 50 個字元？ → QR Code
- 標準商品識別？ → EAN/UPC
- 一般文件追蹤？ → Code128
- 需要與舊式掃描器最高相容性？ → Code39
專業提示：Code128 是文件管理的最安全預設選擇，兼具可讀性、資料容量與掃描器相容性。
實作指南：建立條碼簽章
現在進入重點——實際在 PDF 中建立並加入條碼。我會把流程拆成可管理的步驟，讓您可以依序跟進（或直接跳到需要的部分）。
步驟 1：設定文件路徑
首先告訴 Java 您的 PDF 位於哪裡，以及簽署後的存放位置：
String filePath = "YOUR_DOCUMENT_DIRECTORY/sample.pdf";
String fileName = new File(filePath).getName();
這段程式碼的作用：您定義輸入檔案路徑並抽取檔名，讓輸出檔案保持有序（在批次處理多個檔案時特別有用）。
實務建議：在正式環境中，這些路徑通常來自設定檔或環境變數，而非硬編碼字串。可考慮使用 System.getenv() 或屬性檔以提升彈性。
步驟 2：設定輸出與條碼選項
BarcodeSignOptions 定義條碼簽章的參數，例如資料、類型、大小與位置。
說明如下：
outputFilePath– 完成的 PDF 儲存位置。子資料夾結構有助於區分不同簽署方式。BarcodeSignOptions("12345678")– 條碼中編碼的資料，可是發票號、追蹤 ID、文件雜湊等。setEncodeType(BarcodeTypes.Code128)– 指定使用的條碼格式。
常見問題：「條碼資料可以包含特殊字元嗎？」使用 Code128 時可以包含字母、數字與大多數標點符號。QR Code 更具彈性。
// Define output file path
String outputFilePath = "YOUR_OUTPUT_DIRECTORY/SignWithMillimeters/" + fileName;
BarcodeSignOptions options = new BarcodeSignOptions("12345678");
options.setEncodeType(BarcodeTypes.Code128);
步驟 3：精確定位條碼
BarcodeSignOptions 也允許您以毫米為單位精確定位條碼，這對列印輸出尤為重要。
為什麼使用毫米：列印文件時，毫米能在不同紙張尺寸與解析度間保持一致的尺寸。（若需求不同，也可使用像素或百分比。）
定位策略：
- 右上角（如運送標籤）：
setLeft(150),setTop(10) - 底部中間（如票券）：根據頁寬計算中心位置
- 緊鄰現有內容：測量 PDF 版面後自行設定
專業提示：先在少量樣本 PDF 上測試定位，不同版面可能需要微調。
// Set position and size in millimeters
options.setLocationMeasureType(MeasureType.Millimeters);
options.setLeft(40); // X‑coordinate from left edge
options.setTop(50); // Y‑coordinate from top edge
options.setSizeMeasureType(MeasureType.Millimeters);
options.setWidth(20); // Width of the barcode
options.setHeight(10); // Height of the barcode
步驟 4：加入邊距以提升品質
邊距可防止條碼與其他內容過於擁擠：
// Define margin settings
Padding padding = new Padding();
padding.setLeft(5); // Left margin in mm
padding.setTop(5); // Top margin in mm
padding.setRight(5); // Right margin in mm
padding.setBottom(5); // Bottom margin in mm
options.setMargin(padding);
這段程式碼的作用：在條碼四周建立 5 mm 的緩衝區，提升掃描可讀性並使外觀更專業。
何時增加邊距：若條碼靠近頁面邊緣，建議將邊距提升至 10 mm。印表機往往對過於靠邊的內容處理不佳。
步驟 5：簽署並儲存文件
真正的關鍵時刻——將條碼寫入 PDF：
// Sign and save the document
SignResult signResult = signature.sign(outputFilePath, options);
背後的運作原理：GroupDocs 會開啟您的 PDF，根據設定渲染條碼，將其嵌入指定位置，最後儲存為新檔案。原始 PDF 保持不變。
回傳值：SignResult 物件包含成功/失敗狀態以及簽署的相關資訊，您可檢查以確認操作是否如預期。
步驟 6：優雅地處理錯誤
程式執行過程中可能會遇到錯誤（路徑錯誤、PDF 損毀、權限不足），請妥善處理：
try {
Signature signature = new Signature(filePath);
SignResult signResult = signature.sign(outputFilePath, options);
System.out.println("Barcode added successfully!");
System.out.println("Output saved to: " + outputFilePath);
} catch (Exception e) {
System.err.println("Error signing document: " + e.getMessage());
throw new GroupDocsSignatureException(e.getMessage());
}
錯誤處理最佳實踐：
- 記錄完整的堆疊追蹤以便除錯（僅記錄訊息不足）
- 提供使用者友善的錯誤訊息，避免過度技術化
- 即使發生錯誤也要釋放資源（使用 try‑with‑resources）
- 對暫時性失敗（網路、檔案被鎖）考慮重試機制
常見錯誤：
FileNotFoundException– 輸入 PDF 路徑錯誤GroupDocsSignatureException– 條碼資料無效或 PDF 版本不支援OutOfMemoryError– 同時處理過多大型 PDF 時記憶體不足
如何在 Java 中建立條碼簽章 PDF
使用 new Signature("source.pdf") 載入 PDF，設定包含資料與條碼類型的 BarcodeSignOptions，再設定位置與尺寸，最後呼叫 sign(outputPath, options)。此方法會回傳 SignResult，告訴您操作是否成功並提供簽章細節。
若您偏好簡潔的步驟清單，請參考以下列表：
- 加入 GroupDocs.Signature 相依（Maven、Gradle 或手動 JAR）。
- 以來源 PDF 路徑初始化
Signature。 - 設定
BarcodeSignOptions– 設定資料、類型、大小與位置。 - 視需要設定邊距 以提升可讀性。
- 呼叫
signature.sign(outputPath, options)以嵌入條碼。 - 處理例外並關閉資源。
遵循這六個步驟，即可在任何 Java 應用程式中可靠地向 PDF Java 文件添加條碼。
常見問題與解決方案
以下整理了開發者實際會碰到的問題（因為文件往往寫得不夠完整）：
問題 1：條碼無法正確掃描
症狀：掃描器讀不出條碼或回傳錯誤資料。
解決方案：
- 增大條碼尺寸（大多數掃描器最小寬度 15 mm）
- 確認條碼資料不含該類型不支援的字元
- 保持條碼與背景之間有足夠對比度
- 使用多款掃描應用測試，有些應用的相容性較好
問題 2：條碼位置在不同文件間偏移
症狀：相同的定位程式碼在不同頁面尺寸的 PDF 上產生不同結果。
解決方案：
- 針對不同頁面尺寸使用計算式，而非硬編碼值
- 檢查來源 PDF 是否有旋轉，旋轉會影響座標
- 採用百分比定位以提升一致性
- 如有可能，先將所有輸入 PDF 正規化為統一頁面尺寸
問題 3：大量批次處理時效能下降
症狀：前 100 份 PDF 處理快速，之後速度變慢。
解決方案：
- 及時關閉
Signature物件（或使用 try‑with‑resources） - 將批次拆成較小的子批次，批次間釋放記憶體
- 考慮使用平行處理提升 CPU 利用率
- 監控堆積使用量，必要時調整 JVM 參數
// Good: Process in chunks
List<String> allFiles = getAllPdfFiles();
int batchSize = 100;
for (int i = 0; i < allFiles.size(); i += batchSize) {
List<String> batch = allFiles.subList(i, Math.min(i + batchSize, allFiles.size()));
processBatch(batch);
System.gc(); // Suggest garbage collection between batches
}
問題 4：輸出檔案大小膨脹
症狀：簽署後的 PDF 比原始檔案大很多。
解決方案：
- GroupDocs 本身不會自動壓縮，若需要可自行處理壓縮
- 若向量條碼足以滿足需求，避免使用高解析度的條碼影像
- 檢查是否不小心嵌入了字型或額外的中繼資料
需要聯絡支援：若嘗試上述方法仍有問題，可前往 GroupDocs 論壇 尋求協助。
實務案例
以下說明各行業如何實際運用此功能：
法律行業：合約管理
律師事務所於合約上加入條碼，將實體文件與案件管理系統連結。掃描條碼即可即時取得完整案件歷史，將處理時間從數分鐘縮短至數秒。
實作技巧：在條碼中編碼文件雜湊，以驗證實體文件未被竄改。
醫療保健：患者記錄
醫院在出院摘要與處方 PDF 上貼上條碼，患者掛號時，工作人員掃描條碼即可自動填入過往就診紀錄。
合規說明：確保條碼實作符合 HIPAA 對資料編碼的要求。
物流：運送標籤
電商平台自動在裝箱單上加入追蹤條碼，倉儲人員掃描即可更新出貨狀態，免除手動資料輸入。
效能考量：此類系統常需每小時處理上千份文件，批次處理與平行執行是關鍵。
金融：發票處理
會計部門在發票上加入條碼，編碼付款條件與供應商 ID。掃描後自動將發票路由至正確的審批流程。
專業提示：結合條碼與 OCR 可達到最大自動化——條碼提供元資料，OCR 解析明細項目。
效能最佳實踐
在大規模處理文件時，以下最佳化措施能顯著提升效能：
記憶體管理
- 使用 try‑with‑resources：確保
Signature物件正確關閉。 - 分批處理：不要一次載入 10 000 份 PDF。
- 監控堆積使用：設定適當的 JVM 參數（
-Xmx、-Xms）。
批次處理策略
List<String> files = getAllPdfFiles();
files.parallelStream().forEach(file -> {
try {
addBarcodeToFile(file);
} catch (Exception e) {
// Handle per‑file errors
}
});
注意：平行處理會佔用更多記憶體，請持續監控並進行調校。
快取簽章物件
若頻繁處理相似文件，可重複使用設定好的簽章選項：
// Create options once
BarcodeSignOptions templateOptions = createStandardOptions();
// Reuse for multiple files
for (String file : files) {
BarcodeSignOptions options = templateOptions.clone();
// Customize per file if needed
processFile(file, options);
}
常見問答
Q: 如何在 Java 中為不同條碼類型建立條碼簽章 PDF？
A: 只要變更 setEncodeType() 的參數。QR Code 使用 BarcodeTypes.QR，EAN‑13 使用 BarcodeTypes.EAN13。GroupDocs 內建支援超過 60 種條碼類型。
Q: 能否在同一份 PDF 中加入多個條碼？
A: 完全可以。對不同的 BarcodeSignOptions 呼叫多次 signature.sign()，或在一次呼叫中傳入選項列表。
Q: 如何在不遺失內容的前提下為既有 PDF 加入條碼？
A: GroupDocs 預設為非破壞性操作，會將條碼作為新圖層加入，不會修改原有文字、圖像或排版。
Q: 條碼能編碼的最大資料量是多少？
A: 依條碼類型而定。Code128 大約可容納 128 個字元，QR Code 最多可容納 4 000 個字元。若需更大容量，可考慮編碼指向資料的 URL。
Q: 生產環境需要授權嗎？
A: 需要。免費試用會在文件上加浮水印。正式部署時，需使用臨時授權（延長測試）或購買正式授權。請參考 GroupDocs 定價頁面 了解最新方案。
Q: 批次處理時該如何處理例外？
A: 為每個檔案的操作獨立包裹 try‑catch，避免單一失敗導致整批中斷。記錄檔名與錯誤資訊，以便日後重新處理。
Q: GroupDocs 能產生 Data Matrix 這類 2D 條碼嗎？
A: 能！使用 BarcodeTypes.DataMatrix。Data Matrix 在製造業很受歡迎，因為即使部分受損或角度不正仍能辨識。
Q: GroupDocs 支援哪些 PDF 版本？
A: 支援 PDF 1.3 至 2.0（涵蓋 99 % 市面上常見的 PDF）。若遇到非常古老的 PDF，建議先轉換為較新版本。
結論
您現在已掌握如何使用 GroupDocs.Signature 以程式方式在 Java PDF 文件中加入條碼。我們從基礎設定說明到上線前的錯誤處理與效能優化，全部涵蓋。
重點回顧
- 條碼提供可操作的資料，實現驗證、自動化與合規。
- GroupDocs 讓您精確控制位置與條碼類型。
- 正確的錯誤處理與資源管理可避免上線後的頭痛問題。
- 大規模文件處理時，效能調校相當重要。
後續步驟：先使用免費試用版完成小規模概念驗證。測試不同條碼類型於實際文件上的效果。驗證成功後，進行批次處理，最終部署至正式環境。
有任何問題或遇到困難嗎？請前往 GroupDocs 支援論壇 發問，社群相當熱心，回應速度也很快。
資源
文件與下載
授權與支援
最後更新： 2026-08-04
測試版本： GroupDocs.Signature 23.12 for Java
作者： GroupDocs
