feat: 增强 Web 项目发布构建的 GitHub Action,添加发布失败时的错误处理选项,支持状态监控和退出码输出,更新文档以反映新功能和使用示例。

This commit is contained in:
Lyda
2025-08-20 18:39:38 +08:00
parent c039fac36c
commit da4e1db20d
2 changed files with 234 additions and 20 deletions

View File

@@ -9,8 +9,10 @@
- 🚀 **自动化发布**: 支持任意发布命令进行版本管理和发布
- 🌍 **环境变量支持**: 支持传递任意数量的环境变量给发布命令
- 📦 **智能版本处理**: 自动获取版本号,确保输出格式一致(无 `v` 前缀)
- 📊 **状态监控**: 实时监控发布状态,支持成功/失败状态输出和退出码
- 🔧 **简洁配置**: 最小化配置,专注于发布核心功能
-**灵活使用**: 可配置发布命令,适应不同项目需求
- 🛡️ **错误控制**: 可配置发布失败时的行为(中断或继续)
## 快速开始
@@ -83,11 +85,12 @@ Action 自动处理各种版本格式,确保输出一致:
## 输入参数
| 参数名 | 描述 | 必需 | 默认值 |
| ----------------- | ------------------------- | ---- | --------------------------------- |
| `release-command` | 发布命令 | ❌ | `npm run release -- --release -V` |
| `node-debug` | 是否启用 Node.js 调试模式 | ❌ | `false` |
| `version-file` | 自定义版本文件路径 | ❌ | `/tmp/last-version` |
| 参数名 | 描述 | 必需 | 默认值 |
| ----------------- | ---------------------------- | ---- | --------------------------------- |
| `release-command` | 发布命令 | ❌ | `npm run release -- --release -V` |
| `node-debug` | 是否启用 Node.js 调试模式 | ❌ | `false` |
| `version-file` | 自定义版本文件路径 | ❌ | `/tmp/last-version` |
| `fail-on-error` | 发布失败时是否让 action 失败 | ❌ | `true` |
## 环境变量支持
@@ -120,10 +123,12 @@ Action 支持通过 `env` 传递**任意数量**的环境变量给发布命令
## 输出参数
| 参数名 | 描述 |
| ------------------- | ------------------------ |
| `version` | 发布的版本号 |
| `version-with-dash` | 版本号(点号替换为横线) |
| 参数名 | 描述 |
| ------------------- | -------------------------------------- |
| `version` | 发布的版本号 |
| `version-with-dash` | 版本号(点号替换为横线) |
| `release-status` | 发布命令执行状态 (`success`/`failure`) |
| `exit-code` | 发布命令退出码(仅在失败时有值) |
## 使用场景
@@ -210,16 +215,107 @@ steps:
APP_ENV: ${{ matrix.app_env }}
```
### 4. 状态检查和错误处理
演示如何处理发布状态和错误:
```yaml
steps:
- uses: actions/checkout@v4
- name: 发布项目
id: release
uses: actions/xgj/release-web@main
with:
fail-on-error: false # 发布失败时不中断 workflow
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
# 总是执行的清理步骤
- name: 清理临时文件
if: always()
run: |
echo "清理临时文件..."
rm -rf temp/ dist/temp/
# 根据发布状态执行不同操作
- name: 处理发布结果
if: always()
run: |
echo "发布状态: ${{ steps.release.outputs.release-status }}"
if [[ "${{ steps.release.outputs.release-status }}" == "success" ]]; then
echo "✅ 发布成功,版本: ${{ steps.release.outputs.version }}"
echo "开始部署流程..."
else
echo "❌ 发布失败,退出码: ${{ steps.release.outputs.exit-code }}"
echo "发送失败通知..."
# 这里可以添加通知逻辑
fi
# 只在成功时执行的部署步骤
- name: 部署到生产环境
if: steps.release.outputs.release-status == 'success'
run: |
echo "部署版本 ${{ steps.release.outputs.version }} 到生产环境"
kubectl set image deployment/app app=registry.com/app:${{ steps.release.outputs.version }}
# 失败时的回退操作
- name: 回退操作
if: steps.release.outputs.release-status == 'failure'
run: |
echo "执行回退操作..."
# 回退到上一个稳定版本的逻辑
```
### 5. 严格模式发布(默认行为)
适用于生产环境,发布失败时立即停止:
```yaml
steps:
- uses: actions/checkout@v4
- name: 发布项目
id: release
uses: actions/xgj/release-web@main
with:
fail-on-error: true # 默认值,发布失败时中断 workflow
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
APP_ENV: "production"
# 这个步骤只有在发布成功时才会执行
- name: 部署到生产环境
run: |
echo "部署版本 ${{ steps.release.outputs.version }}"
kubectl apply -f k8s/
```
## 工作流程
1. **发布构建**: 执行指定的发布命令进行版本发布
2. **智能版本获取**: 通过多种方法自动获取版本号
- 捕获命令执行状态和退出码
- 设置 `release-status` 输出(`success`/`failure`
- 失败时记录 `exit-code` 输出
2. **智能版本获取**: 只在发布成功时执行,通过多种方法自动获取版本号
- 优先从版本文件读取(`/tmp/last-version` 或自定义路径)
- 回退到最新 git tag自动去除 `v` 前缀)
- 回退到 `package.json` 中的版本
- 最后尝试从提交信息解析(支持 `v1.2.3``1.2.3` 格式)
- **所有方法都确保输出不包含 `v` 前缀**
3. **发布总结**: 输出发布信息和结果
3. **发布总结**: 显示详细的发布状态信息
- 成功时:显示版本号和发布信息
- 失败时:显示错误状态和退出码
4. **状态检查**: 根据 `fail-on-error` 参数决定最终行为
- `true`(默认):发布失败时让 action 失败,中断 workflow
- `false`:发布失败时继续完成,允许后续步骤执行
## 依赖要求
@@ -282,12 +378,28 @@ CMD ["npm", "start"]
## 错误处理
Action 会在以下情况报错并退出:
### 发布失败处理
- 缺少必需的 `gitea-token` 参数
- 指定的 `Dockerfile` 不存在
- `/tmp/last-version` 文件不存在(发布命令未正确执行)
- Docker 构建失败
Action 提供灵活的错误处理机制:
**严格模式** (`fail-on-error: true` - 默认)
- 发布命令失败时action 立即失败并中断 workflow
- 适用于生产环境,确保发布质量
**宽松模式** (`fail-on-error: false`)
- 发布命令失败时action 继续完成并返回状态信息
- 允许执行清理、通知等后续操作
- 可通过 `outputs.release-status` 检查发布结果
### 常见错误情况
Action 会在以下情况报错:
- 发布命令执行失败(返回非零退出码)
- 无法获取版本信息(所有版本获取方法都失败)
- 版本文件不存在且无其他版本源
## 安全注意事项
@@ -300,6 +412,46 @@ Action 会在以下情况报错并退出:
### 常见问题
### Q: 如何处理发布失败的情况?
A: Action 提供了多种方式处理发布失败:
1. **检查发布状态**
```yaml
- name: 发布项目
id: release
uses: actions/xgj/release-web@main
- name: 检查发布结果
run: |
if [[ "${{ steps.release.outputs.release-status }}" == "failure" ]]; then
echo "发布失败,退出码: ${{ steps.release.outputs.exit-code }}"
# 执行失败处理逻辑
fi
```
2. **宽松模式处理**
```yaml
- name: 发布项目
uses: actions/xgj/release-web@main
with:
fail-on-error: false # 失败时不中断
- name: 清理操作
if: always()
run: echo "总是执行清理"
```
### Q: 如何获取发布失败的详细信息?
A: 通过输出参数获取:
- `release-status`: `success` 或 `failure`
- `exit-code`: 失败时的命令退出码
- 检查 action 日志中的详细错误信息
### Q: 无法获取版本信息
```bash