（圖片來源：使用 AI 技術生成）
前言：為什麼我們需要從原始碼編譯？
如果你曾用過 Carrot2，可能會發現官方提供的二進位（Binary）版本對中文使用者並不友善。這並非功能不足，而是官方發行版為了保持輕量，預設僅打包了通用語系。主要原因有幾點：
- 官方版本語系限制：預設僅內建歐美語系（英、法、德等），對於需要分詞器（Tokenizer）支援的 CJK（中日韓）模組，必須透過編譯流程手動連結相關的 Lucene 分析組件。
- Web UI 語言選單問題：Carrot2 的前端 Workbench 介面語言清單是「寫死」在程式碼中的。即便後端支援了中文，選單裡若找不到選項，使用者也無法強制發送中文處理請求。
- CSV 檔案解析錯誤：官方使用的 SheetJS (XLSX) 解析邏輯在處理純文字 CSV 時，對於 UTF-8 編碼且不含 BOM 的 CJK 內容常會判定失誤，導致上傳後的預覽與分群結果出現亂碼，這必須從前端原始碼層級修正檔案讀取流。
- 自定義字典需求：中文分詞往往需要精細的過濾，例如排除「新聞」、「轉發」等雜質標籤。從原始碼編譯可以讓你將這些專屬的停用詞（Stopwords）直接內建到 Distribution 中，實現隨開即用的專業分析環境。
在上一篇教學中，我介紹了手動補元 JAR 模組與插入 JS 補丁的「快速修補」方法。雖然這對非開發者較易上手，但存在版本更新時需重複配置的局限。為了打造穩定且完美結合的中日韓語言支援版本，本篇將引導你從「原始碼層級」進行深度改寫與編譯。
自行編譯的好處：
- 一勞永逸：一次處理好編譯邏輯，未來升級版本只需合併代碼即可快速產出新版。
- 完整封裝：將 CJK 語言模組與前端介面修正打包成單一 ZIP，部署時無需解壓縮即可用。
- 效能優化：可預先在原始碼中調整演算法的預設參數（如字群密度、標籤加權）。
- 標準化環境：完全支援 DevContainer，確保跨平台開發環境的一致性。
開發環境準備（推薦使用 DevContainer）
為了避免不同作業系統之間的 Java 版本、Gradle 環境或路徑問題搞死人，我強烈建議使用 VS Code 的 DevContainer，這能提供一個乾淨且預設配置好的 Linux 編譯環境。
方案一：DevContainer（VS Code 一鍵環境）
在專案目錄下建立 .devcontainer/devcontainer.json：
{
"name": "Carrot2 CJK Build Environment",
"image": "mcr.microsoft.com/devcontainers/java:1-21-bullseye",
"features": {
"ghcr.io/devcontainers/features/java:1": {
"version": "none",
"installMaven": "true",
"installGradle": "true"
},
"ghcr.io/devcontainers/features/git:1": {}
},
"forwardPorts": [8080],
"postCreateCommand": "git config --global core.autocrlf false",
"customizations": {
"vscode": {
"extensions": [
"vscjava.vscode-java-pack",
"ms-vscode.vscode-gradle",
"esbenp.prettier-vscode"
]
}
}
}
操作方式：
git clone https://github.com/carrot2/carrot2.gitcd carrot2code .- 當 VS Code 偵測到設定檔時，點擊右下角提示的「在容器中重新開啟 (Reopen in Container)」。
方案二：本地環境直接安裝（macOS/Linux）
如果你偏好直接在機器上跑，請確保工具鏈版本正確：
- 安裝 Java 21+：Carrot2 v4 需要較新版的 JDK。建議使用 SDKMAN 管理：
sdkman use java 21.0.4-tem。 - 準備 Gradle：專案根目錄下有
./gradlew腳本，它會自動下載對應的 Gradle 版本，無需手動安裝系統級別的 Gradle。 - 下載原始碼與子模組：
由於 Carrot2 依賴一些外部組件，必須使用遞迴下載：git clone --recurse-submodules https://github.com/carrot2/carrot2.git
cd carrot2
接下來，我們將進入核心實作階段。本節將詳細說明如何修改程式碼與執行編譯之步驟，請訂閱解鎖全文，取得完整技術細節。
核心修改一：啟用 CJK 語言模組
Carrot2 的 DCS (Document Clustering Server) 是透過 Gradle 進行模組化建置的。預設的依賴配置排除了 CJK 相關的 Lucene 庫，我們需要手動將其加入編譯依賴鏈。
