在實際 Java 項目里手把手構(gòu)建 Java 項目腳本并不是為了炫技而是為了消滅“本地能跑、CI 上就掛”的尷尬。不同開發(fā)者在本地敲著不同的命令有人先 clean 再 package有人順手跳過測試有人更新版本號后忘記拷貝產(chǎn)物也有人只在某個模塊里構(gòu)建最終提交到 Jenkins 后行為完全不一致。構(gòu)建腳本的定位就是把代碼版本、構(gòu)建參數(shù)、依賴處理、編譯、測試、打包、產(chǎn)物歸檔、部署觸發(fā)和失敗告警這些固定動作封裝成統(tǒng)一入口。目標很明確無論本地手動執(zhí)行還是由 Jenkins 定時觸發(fā)同樣的參數(shù)組合必須產(chǎn)生同樣的結(jié)果失敗時必須能定位到具體階段。下面從零寫一個能在本地和 CI 環(huán)境共同使用的build.sh以 Maven 項目為例覆蓋最常見的 Java 構(gòu)建流程。腳本會支持環(huán)境參數(shù)、模塊參數(shù)、跳過測試、產(chǎn)物校驗、歸檔以及部署旁路。隨后會說明如何在 Jenkins 等 CI 平臺中調(diào)用這個腳本并解決“構(gòu)建失敗如何發(fā)送郵件”和“手動選擇模塊構(gòu)建、定時執(zhí)行構(gòu)建”這兩個很常見的需求。1. 先搞清楚 Java 項目構(gòu)建腳本到底管哪些事1.1 構(gòu)建腳本與構(gòu)建工具、CI 平臺的分工很多 Java 項目里有一個常見誤解項目已經(jīng)用了 Maven 或 Gradle為什么還要再寫一套腳本要理清這個問題需要先分清楚三層工具的職責Maven / Gradle 是構(gòu)建工具負責“編譯、測試、打包”這個具體過程。Shell / PowerShell 腳本負責“編排和開關(guān)控制”決定用什么參數(shù)、在哪個目錄執(zhí)行、成功之后怎么處理產(chǎn)物、失敗之后怎么報錯。Jenkins / GitLab CI 是調(diào)度平臺負責“什么時候觸發(fā)、誰來觸發(fā)、日志放在哪里、失敗后通知誰”。三者不是替代關(guān)系。Maven 本身解決“怎么把.java變成.jar”但無法干凈地解決“從 Git 拉取代碼并切到指定分支”、“生成帶時間戳和 commit 信息的版本號”、“把 jar 同步到備份目錄”、“失敗后調(diào)用告警接口”這類跨工具動作。腳本正是把這些跨工具動作串起來的一層膠水。1.2 一個相對完整的 Java 構(gòu)建流程包含哪些階段一個能上線的 Java 構(gòu)建流程通常不止mvn package一步。下面的表格是我在項目中整理出的階段和檢查點階段動作典型結(jié)果代碼準備git fetch、git checkout、必要時清理本地修改本地工作區(qū)與目標分支對齊版本計算讀取pom.xml版本 Git commit 環(huán)境 時間戳可追溯的BUILD_VERSION依賴處理Maven 下載或復用本地倉庫依賴依賴解析完成編譯測試mvn clean test或跳過測試測試報告、target/classes打包mvn packagejar / war 產(chǎn)出產(chǎn)物校驗檢查文件存在、非空、大小、哈希jar 和 sha256 文件歸檔發(fā)布拷貝到發(fā)布目錄、制品庫或遠程服務(wù)器部署包、發(fā)布記錄每個階段都要有檢查點。如果編譯失敗還繼續(xù)拷貝舊 jar或者測試失敗還繼續(xù)部署都是生產(chǎn)事故的隱患。腳本的價值就是把這些檢查點固定下來不讓“人工記憶”成為構(gòu)建規(guī)則的一部分。1.3 腳本化帶來的三個直接收益行為一致開發(fā)、測試、生產(chǎn)環(huán)境統(tǒng)一使用同一個入口參數(shù)通過腳本參數(shù)或環(huán)境變量傳入避免“別人電腦上命令不一樣”。參數(shù)可復用同一個build.sh本地快速構(gòu)建用-e dev -sCI 用-e prod不需要為 Jenkins 單獨維護一套命令。失敗可感知腳本返回非 0 退出碼CI 平臺才能準確識別失敗狀態(tài)郵件或機器人告警才能被觸發(fā)。沒有腳本的裸mvn命令在 CI 中往往只能拿到一句含糊的異常無法知道發(fā)生在編譯前、編譯中還是打包后。2. 環(huán)境準備與腳本目錄設(shè)計2.1 最小環(huán)境清單寫腳本之前先確認運行環(huán)境。不同項目對 JDK 版本要求不同具體以項目的pom.xml為準。這里給出的是通用清單工具建議要求用途JDK與pom.xml中maven.compiler.source對應(yīng)的版本編譯 Java 代碼Maven3.6 或更高版本依賴管理和打包Git2.x讀取 commit 信息、切換分支BashLinux / macOS 自帶即可Windows 建議用 Git Bash 或 WSL執(zhí)行構(gòu)建腳本rsync可選遠程部署時使用增量同步產(chǎn)物curl可選自行發(fā)送告警時使用調(diào)用通知 API這里要特別提醒如果原始項目沒有明確 Maven 版本落地前要先用mvn -v確認。Maven 3.6 與 3.9 在部分插件行為上有差異直接寫死“最高版本”并不穩(wěn)妥。macOS 自帶的 Bash 是 3.2 版本關(guān)聯(lián)數(shù)組等高級語法不支持。為了讓腳本在更多機器上可運行建議避免使用關(guān)聯(lián)數(shù)組使用普通變量、數(shù)組和case分支即可。2.2 推薦的項目結(jié)構(gòu)布局構(gòu)造腳本不應(yīng)該散落在項目根目錄下推薦用一個scripts目錄統(tǒng)一管理your-java-project/ ├── pom.xml ├── src/ │ ├── main/ │ └── test/ ├── scripts/ │ ├── build.sh │ └── lib/ │ └── common.sh ├── target/ │ └── release/ └── build.properties說明scripts/build.sh是構(gòu)建入口開發(fā)者和 CI 都調(diào)用它。target/release存放最終歸檔產(chǎn)物。它會被.gitignore忽略不進入 Git。build.properties保存項目內(nèi)部通用參數(shù)比如默認遠端服務(wù)器、歸檔保留數(shù)量等。如果是多環(huán)境項目也可以拆成dev.properties、prod.properties。腳本通過dirname ${BASH_SOURCE[0]}定位自己的目錄再cd ..找到項目根目錄。這樣腳本無論在哪個目錄下執(zhí)行都不會因為“當前路徑不對”而找不到pom.xml。2.3 對外參數(shù)約定建議把腳本參數(shù)設(shè)計成穩(wěn)定、清晰的一組開關(guān)參數(shù)含義默認值典型值-m, --module name只構(gòu)建指定 Maven 模塊空構(gòu)建整個項目user-service-s, --skip-tests跳過測試執(zhí)行falsetrue-e, --env env構(gòu)建環(huán)境devdev、test、prod-h, --help查看幫助無無這樣設(shè)計的好處是本地開發(fā)可以用./scripts/build.sh -e dev -s快速驗證編譯CI 環(huán)境可以用./scripts/build.sh -e test完整跑測試發(fā)布流水線可以用./scripts/build.sh -e prod并在稍后的部署步驟中走審批系統(tǒng)。腳本本身不需要因為環(huán)境不同而改內(nèi)部邏輯只用參數(shù)控制行為。3. 編寫一個可運行的 build.sh3.1 腳本骨架與執(zhí)行安全選項先給出腳本的頭部部分。它決定腳本的“安全底線”#!/usr/bin/env bash set -euo pipefail IFS$\n\t PROJECT_HOME$(cd $(dirname ${BASH_SOURCE[0]})/.. pwd) MODULE_NAME SKIP_TESTSfalse APP_ENVdev ARTIFACT_DIR${PROJECT_HOME}/target/release BUILD_VERSION關(guān)鍵點set -e表示腳本中任何命令返回非 0 時立刻退出避免失敗后繼續(xù)執(zhí)行后續(xù)步驟。set -u表示使用未定義變量時報錯防止把$MODULE_NAME漏判為空后拼出錯誤命令。set -o pipefail表示管道中有一個命令失敗整條管道就算失敗。例如mvn package 21 | tee build.log中如果mvn失敗tee可能仍然返回 0沒有pipefail會導致腳本誤判成功。IFS$\n\t避免包含空格的文件名在遍歷時被拆成多個詞。PROJECT_HOME通過腳本自身路徑計算而不是寫死/home/user/project。這樣項目移動目錄后腳本依然有效。這里有一個容易被忽視的坑set -e并不是萬能的。如果某條命令寫進if條件、左側(cè)或||右側(cè)它的失敗不會導致腳本退出。因此需要在這種場景下顯式處理。3.2 參數(shù)解析和幫助信息為了讓腳本具備基本的可用性先加入幫助函數(shù)和參數(shù)解析info() { echo [INFO] $(date %Y-%m-%d %H:%M:%S) $* } error() { echo [ERROR] $(date %Y-%m-%d %H:%M:%S) $* 2 } usage() { cat EOF 用法: ./scripts/build.sh [選項] 選項: -m, --module name 只構(gòu)建指定Maven模塊多模塊項目有效 -s, --skip-tests 跳過測試執(zhí)行 -e, --env env 構(gòu)建環(huán)境: dev/test/prod默認 dev -h, --help 顯示幫助 EOF } while [[ $# -gt 0 ]]; do case $1 in -m|--module) MODULE_NAME${2:-} if [[ -z ${MODULE_NAME} ]]; then error 參數(shù) $1 需要模塊名 exit 1 fi shift 2 ;; -s|--skip-tests) SKIP_TESTStrue shift ;; -e|--env) APP_ENV${2:-} if [[ -z ${APP_ENV} ]]; then error 參數(shù) $1 需要環(huán)境名 exit 1 fi shift 2 ;; -h|--help) usage exit 0 ;; *) error 未知參數(shù): $1 usage exit 1 ;; esac done日志函數(shù)里把時間信息帶到每一條輸出在 CI 日志中定位階段時很有用。解析參數(shù)使用case而不是手寫if是因為case更容易擴展后續(xù)增加開關(guān)時只需要加一個分支。3.3 生成可追溯的版本號構(gòu)建產(chǎn)物最怕兩個問題一是不知道是從哪個代碼提交構(gòu)建出來的二是不同時間的產(chǎn)物互相覆蓋。所以版本號里至少要包含項目版本、環(huán)境、Git commit 短哈希和時間戳get_build_version() { local base_version base_version$(grep -m1 version ${PROJECT_HOME}/pom.xml | sed s/.*version\(.*\)\/version.*/\1/) local git_short_hash git_short_hash$(git -C ${PROJECT_HOME} rev-parse --short HEAD 2/dev/null || echo nogit) echo ${base_version}-${APP_ENV}-${git_short_hash}-$(date %Y%m%d%H%M%S) }生成結(jié)果類似1.0.0-prod-a1b2c3d-20250515103000說明grep -m1 version取pom.xml中第一個version。單模塊項目通常就是項目版本。多模塊項目如果父pom.xml有多個version建議換成基于artifactId解析的方式。git rev-parse --short HEAD獲取當前提交的短哈希如果 Git 不可用則回退為nogit保證腳本不會硬性中斷。時間戳用%Y%m%d%H%M%S避免文件名中的冒號在 Windows 或某些 Linux 文件系統(tǒng)中產(chǎn)生問題。BUILD_VERSION在腳本主流程中只計算一次后續(xù)歸檔、部署都使用同一個值避免二次調(diào)用時時間戳不同導致文件對應(yīng)不上。3.4 執(zhí)行 Maven 構(gòu)建包含模塊和跳過測試邏輯Maven 命令本身很簡單但參數(shù)需要動態(tài)拼裝。在 Bash 中不要用字符串拼接后讓 Shell 重新解析推薦使用數(shù)組run_maven_build() { local mvn_args(clean package) if [[ ${SKIP_TESTS} true ]]; then mvn_args(-DskipTests) fi if [[ -n ${MODULE_NAME} ]]; then mvn_args(-pl ${MODULE_NAME} -am) fi info 開始 Maven 構(gòu)建參數(shù): ${mvn_args[*]} cd ${PROJECT_HOME} mvn ${mvn_args[]} info Maven 構(gòu)建完成 }關(guān)鍵點默認執(zhí)行clean package保證每次構(gòu)建從干凈狀態(tài)開始避免舊 class 文件殘留。-DskipTests跳過測試執(zhí)行但仍會編譯測試代碼。如果需要完全跳過測試編譯可以使用-Dmaven.test.skiptrue。非必要不建議用后者因為測試代碼的編譯錯誤也是一種重要反饋。多模塊項目指定-pl時同時加上-am表示“也會構(gòu)建依賴的相關(guān)模塊”避免只構(gòu)建指定模塊導致找不到依賴。數(shù)組方式傳遞參數(shù)即使模塊名或參數(shù)值中包含空格也不會被 Shell 錯誤拆分。3.5 驗證和歸檔構(gòu)建產(chǎn)物mvn package成功不代表產(chǎn)物一定有效可能因為配置錯誤生成了pom.xml結(jié)尾的占位文件或者 jar 文件被其他插件改寫成了 0 字節(jié)。因此需要專門函數(shù)做校驗和歸檔verify_and_archive() { local jar_file jar_file$(find ${PROJECT_HOME}/target -type f -name *.jar \ ! -name *-sources.jar ! -name *-javadoc.jar 2/dev/null | head -n 1 || true) if [[ -z ${jar_file} || ! -s ${jar_file} ]]; then error 沒有找到有效的 jar 文件或 jar 文件為空 return 1 fi mkdir -p ${ARTIFACT_DIR} local dest${ARTIFACT_DIR}/${BUILD_VERSION}.jar cp ${jar_file} ${dest} if command -v sha256sum /dev/null 21; then sha256sum ${dest} ${dest}.sha256 else shasum -a 256 ${dest} ${dest}.sha256 fi info 歸檔產(chǎn)物: ${dest} cat ${dest}.sha256 }這段函數(shù)做了幾件事在target目錄下查找 jar但排除-sources.jar和-javadoc.jar避免拿到源碼包或文檔包。head -n 1只取第一個 jar。實際項目中如果存在target下多個 jar建議再根據(jù)模塊名精確匹配。! -s檢查文件是否存在且非空防止拷貝空文件。生成.sha256校驗文件后續(xù)部署時可以通過校驗確認文件沒有在傳輸中被破壞。產(chǎn)物命名使用BUILD_VERSION不同構(gòu)建版本不會互相覆蓋便于保留歷史版本。3.6 可選遠程部署或發(fā)布部署動作與“構(gòu)造”應(yīng)該分離。很多團隊把“構(gòu)建”和“發(fā)布”分成兩個步驟因為發(fā)布涉及權(quán)限、審批、回滾等額外流程。腳本可以提供遠程部署函數(shù)但生產(chǎn)環(huán)境要禁用自動部署deploy_to() { local server_user${1} local server_host${2} local remote_dir${3} if [[ ${APP_ENV} prod ]]; then info 生產(chǎn)環(huán)境不通過腳本自動部署請走發(fā)布系統(tǒng)或人工審批 return 0 fi if ! command -v rsync /dev/null 21; then error 需要 rsync 才能部署 return 1 fi local dest${ARTIFACT_DIR}/${BUILD_VERSION}.jar info 同步至 ${server_user}${server_host}:${remote_dir} rsync -avz ${dest} ${dest}.sha256 ${server_user}${server_host}:${remote_dir}/ }這里的人工決定是測試環(huán)境可以通過rsync快速同步生產(chǎn)環(huán)境必須進入發(fā)布系統(tǒng)。生產(chǎn)發(fā)布一旦出錯最容易的恢復方式就是回滾到上一個版本而自動部署在大多數(shù)團隊里并不適合直接交給普通構(gòu)建腳本完成。3.7 完整 build.sh 示例把前面所有函數(shù)組合成一個可執(zhí)行腳本。可以用vim或nano新建scripts/build.sh然后粘貼以下內(nèi)容#!/usr/bin/env bash set -euo pipefail IFS$\n\t PROJECT_HOME$(cd $(dirname ${BASH_SOURCE[0]})/.. pwd) MODULE_NAME SKIP_TESTSfalse APP_ENVdev ARTIFACT_DIR${PROJECT_HOME}/target/release BUILD_VERSION info() { echo [INFO] $(date %Y-%m-%d %H:%M:%S) $* } error() { echo [ERROR] $(date %Y-%m-%d %H:%M:%S) $* 2 } usage() { cat EOF 用法: ./scripts/build.sh [選項] 選項: -m, --module name 只構(gòu)建指定Maven模塊多模塊項目有效 -s, --skip-tests 跳過測試執(zhí)行 -e, --env env 構(gòu)建環(huán)境: dev/test/prod默認 dev -h, --help 顯示幫助 EOF } while [[ $# -gt 0 ]]; do case $1 in -m|--module) MODULE_NAME${2:-} if [[ -z ${MODULE_NAME} ]]; then error 參數(shù) $1 需要模塊名 exit 1 fi shift 2 ;; -s|--skip-tests) SKIP_TESTStrue shift ;; -e|--env) APP_ENV${2:-} if [[ -z ${APP_ENV} ]]; then error 參數(shù) $1 需要環(huán)境名 exit 1 fi shift 2 ;; -h|--help) usage exit 0 ;; *) error 未知參數(shù): $1 usage exit 1 ;; esac done get_build_version() { local base_version base_version$(grep -m1 version ${PROJECT_HOME}/pom.xml | sed s/.*version\(.*\)\/version.*/\1/) local git_short_hash git_short_hash$(git -C ${PROJECT_HOME} rev-parse --short HEAD 2/dev/null || echo nogit) echo ${base_version}-${APP_ENV}-${git_short_hash}-$(date %Y%m%d%H%M%S) } run_maven_build() { local mvn_args(clean package) if [[ ${SKIP_TESTS} true ]]; then mvn_args(-DskipTests) fi if [[ -n ${MODULE_NAME} ]]; then mvn_args(-pl ${MODULE_NAME} -am) fi info 開始 Maven 構(gòu)建參數(shù): ${mvn_args[*]} cd ${PROJECT_HOME} mvn ${mvn_args[]} info Maven 構(gòu)建完成 } verify_and_archive() { local jar_file jar_file$(find ${PROJECT_HOME}/target -type f -name *.jar \ ! -name *-sources.jar ! -name *-javadoc.jar 2/dev/null | head -n 1 || true) if [[ -z ${jar_file} || ! -s ${jar_file} ]]; then error 沒有找到有效的 jar 文件或 jar 文件為空 return 1 fi mkdir -p ${ARTIFACT_DIR} local dest${ARTIFACT_DIR}/${BUILD_VERSION}.jar cp ${jar_file} ${dest} if command -v sha256sum /dev/null 21; then sha256sum ${dest} ${dest}.sha256 else shasum -a 256 ${dest} ${dest}.sha256 fi info 歸檔產(chǎn)物: ${dest} cat ${dest}.sha256 } deploy_to() { local server_user${1} local server_host${2} local remote_dir${3} if [[ ${APP_ENV} prod ]]; then info 生產(chǎn)環(huán)境不通過腳本自動部署請走發(fā)布系統(tǒng)或人工審批 return 0 fi if ! command -v rsync /dev/null 21; then error 需要 rsync 才能部署 return 1 fi local dest${ARTIFACT_DIR}/${BUILD_VERSION}.jar info 同步至 ${server_user}${server_host}:${remote_dir} rsync -avz ${dest} ${dest}.sha256 ${server_user}${server_host}:${remote_dir}/ } main() { mkdir -p ${ARTIFACT_DIR} BUILD_VERSION$(get_build_version) info 構(gòu)建版本: ${BUILD_VERSION} info 項目根目錄: ${PROJECT_HOME} run_maven_build verify_and_archive deploy_to deploy your-server.example.com /opt/apps/your-project/releases } main $保存后執(zhí)行chmod x scripts/build.sh ./scripts/build.sh -e dev -s執(zhí)行成功后在target/release下應(yīng)該能看到帶版本號的 jar 和.sha256文件。4. 在 Jenkins 等 CI 環(huán)境中使用并實現(xiàn)失敗郵件通知4.1 腳本在 CI 環(huán)境中的注意事項腳本能本地執(zhí)行不等于能直接在 Jenkins 節(jié)點上執(zhí)行。CI 環(huán)境與本地環(huán)境有幾個明顯差異環(huán)境變量不同。Jenkins 節(jié)點上可能沒有配置JAVA_HOME或MAVEN_HOME導致腳本報mvn: command not found。工作空間路徑每次構(gòu)建可能變化。腳本通過BASH_SOURCE定位項目根目錄天然能適應(yīng)工作區(qū)路徑變化。執(zhí)行用戶不同。Jenkins 節(jié)點通常以jenkins用戶運行可能沒有主目錄權(quán)限下載 Maven 依賴時容易寫入失敗。敏感信息不能出現(xiàn)在腳本參數(shù)里。密碼、私鑰、云平臺憑據(jù)應(yīng)該通過 Jenkins 的憑據(jù)綁定或環(huán)境變量注入而不是寫在build.sh中。建議在 Jenkins 節(jié)點上先手動運行一次腳本確認java -version、mvn -v、git -C都能正常執(zhí)行再創(chuàng)建 Pipeline Job。4.2 讓構(gòu)建失敗信息進入 Jenkins 郵件構(gòu)建失敗發(fā)郵件并不是腳本發(fā)明的功能Jenkins 本身就有郵件通知能力。最常用的是Editable Email Notification插件。使用 Pipeline 時可以在post塊中定義失敗動作pipeline { agent any options { timestamps() } parameters { choice(name: ENV, choices: [dev, test, prod], description: 構(gòu)建環(huán)境) string(name: MODULE, defaultValue: , description: 需要構(gòu)建的Maven模塊留空表示全部) booleanParam(name: SKIP_TESTS, defaultValue: false, description: 是否跳過測試) } stages { stage(構(gòu)建) { steps { script { env.BUILD_ENV params.ENV env.BUILD_MODULE params.MODULE env.BUILD_SKIP_TESTS params