CI/CD / 系统课时
验证本地构建流程
验证本地构建流程
本课把项目在本机完整走一遍:下载依赖、执行测试、生成制品并启动验证。只有这条链路能在干净环境中重复成功,后续流水线失败时,才能判断问题来自代码还是 CI 平台配置。
学习目标
- 明确本地构建必须覆盖的四个阶段
- 编写可重复执行的构建验证脚本
- 根据输出快速区分依赖、测试、打包和启动故障
先确认构建入口
以下示例面向带有 Maven Wrapper 的 Spring Boot Web 项目。仓库根目录应至少包含 mvnw、.mvn、pom.xml 和源码目录,运行机器需要安装 JDK 21 与 curl。
优先使用仓库自带的 ./mvnw,不要直接依赖开发者电脑中的 Maven 版本。Wrapper 会读取项目固定的 Maven 配置,使本地与 CI 使用相同的构建工具。
用脚本串起完整流程
在仓库中创建 scripts/verify-build.sh。脚本按依赖、测试、打包、启动四个阶段执行,任何一步返回非零状态都会立即停止。
#!/usr/bin/env bash
set -euo pipefail
PORT="${PORT:-18080}"
LOG_FILE="${TMPDIR:-/tmp}/local-build.log"
echo "[1/4] Download dependencies"
chmod +x mvnw
./mvnw -q dependency:go-offline
echo "[2/4] Run tests"
./mvnw -q test
echo "[3/4] Package application"
./mvnw -q -DskipTests clean package
mapfile -t JARS < <(
find target -maxdepth 1 -type f -name '*.jar' ! -name 'original-*.jar' | sort
)
JAR_FILE="${JARS[0]:-}"
if [[ -z "$JAR_FILE" ]]; then
echo "No runnable JAR found in target/" >&2
exit 1
fi
echo "[4/4] Start and probe"
java -jar "$JAR_FILE" --server.port="$PORT" >"$LOG_FILE" 2>&1 &
APP_PID=$!
trap 'kill "$APP_PID" 2>/dev/null || true' EXIT
for _ in {1..30}; do
if HTTP_CODE="$(curl -sS -o /dev/null -w '%{http_code}' "http://127.0.0.1:${PORT}/")"; then
echo "HTTP status: ${HTTP_CODE}"
echo "LOCAL BUILD VERIFIED"
exit 0
fi
if ! kill -0 "$APP_PID" 2>/dev/null; then
break
fi
sleep 1
done
cat "$LOG_FILE"
echo "Application did not become reachable" >&2
exit 1执行脚本:
chmod +x scripts/verify-build.sh
./scripts/verify-build.sh预期输出:
[1/4] Download dependencies
[2/4] Run tests
[3/4] Package application
[4/4] Start and probe
HTTP status: <HTTP_STATUS>
LOCAL BUILD VERIFIED<HTTP_STATUS> 可能是 200、401 或 404,实际值取决于项目根路径;本课只验证进程已经监听 HTTP 端口。若项目不是 Web 服务,应把探测步骤替换为该应用真实的启动验收方式。
核对每一步的产物
依赖阶段应能在无交互条件下完成下载;测试阶段必须返回成功状态;打包阶段应在 target 目录生成可运行 JAR;启动阶段必须证明制品能够被当前配置加载。
不要只看到 BUILD SUCCESS 就结束验证。测试通过但 JAR 无法启动,通常意味着运行时配置、资源文件、端口或启动参数仍有问题。
处理典型失败
| 现象 | 优先检查 | 修复方向 |
|---|---|---|
| 依赖下载失败 | 仓库地址、代理、凭据、网络 | 修正 Maven settings.xml 或仓库权限 |
| 测试失败 | 第一条失败用例及其堆栈 | 修复代码或测试环境,不要直接跳过测试 |
| 找不到 JAR | pom.xml 打包类型和插件 |
确认 packaging 与 Spring Boot 打包插件 |
| 应用启动后退出 | local-build.log |
检查配置文件、数据库连接和端口占用 |
构建脚本只负责暴露问题,不应通过无限重试、忽略退出码或强制跳过测试来制造“成功”。
验收可重复性
至少连续执行两次脚本,并在一个新克隆的工作目录中再执行一次。新克隆能够成功,说明构建没有偷偷依赖未提交文件、IDE 配置或本机缓存中的私有内容。
本地验证完成后,把脚本与构建所需配置一并提交到仓库。CI 应直接复用同一条核心命令,而不是在平台配置中重新拼出另一套构建流程。
本课总结
- 可交付的本地构建必须覆盖依赖、测试、打包和启动验证
- Maven Wrapper 与脚本化命令能减少开发机和 CI 环境差异
- 构建失败应保留原始退出码和日志,不能用跳过测试掩盖问题
下一课预告
下一课将把已验证的构建命令写入第一条持续集成流水线,并通过代码提交自动触发执行。