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

2025-10-14 06:33:37 +08:00 · 2025-08-20 18:39:38 +08:00
parent c039fac36c
commit da4e1db20d
2 changed files with 234 additions and 20 deletions
--- a/release-web/README.md
+++ b/release-web/README.md
@@ -9,8 +9,10 @@
 - 🚀 **自动化发布**: 支持任意发布命令进行版本管理和发布
 - 🌍 **环境变量支持**: 支持传递任意数量的环境变量给发布命令
 - 📦 **智能版本处理**: 自动获取版本号，确保输出格式一致（无 `v` 前缀）
+- 📊 **状态监控**: 实时监控发布状态，支持成功/失败状态输出和退出码
 - 🔧 **简洁配置**: 最小化配置，专注于发布核心功能
 - ✅ **灵活使用**: 可配置发布命令，适应不同项目需求
+- 🛡️ **错误控制**: 可配置发布失败时的行为（中断或继续）

 ## 快速开始

@@ -84,10 +86,11 @@ Action 自动处理各种版本格式，确保输出一致：
 ## 输入参数

 | 参数名            | 描述                         | 必需 | 默认值                            |
-| ----------------- | ------------------------- | ---- | --------------------------------- |
+| ----------------- | ---------------------------- | ---- | --------------------------------- |
 | `release-command` | 发布命令                     | ❌   | `npm run release -- --release -V` |
 | `node-debug`      | 是否启用 Node.js 调试模式    | ❌   | `false`                           |
 | `version-file`    | 自定义版本文件路径           | ❌   | `/tmp/last-version`               |
+| `fail-on-error`   | 发布失败时是否让 action 失败 | ❌   | `true`                            |

 ## 环境变量支持

@@ -121,9 +124,11 @@ Action 支持通过 `env` 传递**任意数量**的环境变量给发布命令
 ## 输出参数

 | 参数名              | 描述                                   |
-| ------------------- | ------------------------ |
+| ------------------- | -------------------------------------- |
 | `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
--- a/release-web/action.yml
+++ b/release-web/action.yml
@@ -22,6 +22,11 @@ inputs:
    required: false
    default: '/tmp/last-version'
    
+  fail-on-error:
+    description: '发布失败时是否让 action 失败 (true/false)'
+    required: false
+    default: 'true'
+
 outputs:
  version:
    description: '发布的版本号'
@@ -31,22 +36,46 @@ outputs:
    description: '版本号（点号替换为横线）'
    value: ${{ steps.get_var.outputs.version_with_dash }}
  
+  release-status:
+    description: '发布命令执行状态 (success/failure)'
+    value: ${{ steps.release_build.outputs.status }}
+  
+  exit-code:
+    description: '发布命令退出码（仅在失败时有值）'
+    value: ${{ steps.release_build.outputs.exit_code }}
+
 runs:
  using: 'composite'
  steps:
    - name: 发布构建
+      id: release_build
      shell: bash
      run: |
        echo "🚀 开始发布构建..."
        echo "执行命令: ${{ inputs.release-command }}"
+        
+        # 设置错误处理，防止命令失败时立即退出
+        set +e
        ${{ inputs.release-command }}
+        RELEASE_EXIT_CODE=$?
+        set -e
+        
+        # 根据退出码设置状态
+        if [ $RELEASE_EXIT_CODE -eq 0 ]; then
+          echo "status=success" >> $GITHUB_OUTPUT
          echo "✅ 发布构建完成"
+        else
+          echo "status=failure" >> $GITHUB_OUTPUT
+          echo "❌ 发布构建失败 (退出码: $RELEASE_EXIT_CODE)"
+          echo "exit_code=$RELEASE_EXIT_CODE" >> $GITHUB_OUTPUT
+        fi
      env:
        NODE_DEBUG: ${{ inputs.node-debug == 'true' && 'release-it:*' || '' }}

    - name: 获取版本信息
      id: get_var
      shell: bash
+      if: steps.release_build.outputs.status == 'success'
      run: |
        echo "📝 获取版本信息..."
        VERSION=""
@@ -108,8 +137,41 @@ runs:

    - name: 发布总结
      shell: bash
+      if: always()
      run: |
-        echo "🎉 发布流程完成！"
+        echo "📋 发布流程总结"
+        echo ""
+        echo "📊 发布状态: ${{ steps.release_build.outputs.status }}"
+        
+        if [[ "${{ steps.release_build.outputs.status }}" == "success" ]]; then
+          echo "🎉 发布构建成功完成！"
          echo ""
          echo "📋 发布信息:"
          echo "  - 版本号: ${{ steps.get_var.outputs.version }}"
+          echo "  - 带横线版本: ${{ steps.get_var.outputs.version_with_dash }}"
+        else
+          echo "❌ 发布构建失败"
+          echo ""
+          echo "📋 错误信息:"
+          echo "  - 状态: 失败"
+          if [[ -n "${{ steps.release_build.outputs.exit_code }}" ]]; then
+            echo "  - 退出码: ${{ steps.release_build.outputs.exit_code }}"
+          fi
+          echo "  - 建议: 请检查发布命令和项目配置"
+        fi
+
+    - name: 检查发布结果
+      shell: bash
+      if: always()
+      run: |
+        if [[ "${{ steps.release_build.outputs.status }}" == "failure" ]]; then
+          if [[ "${{ inputs.fail-on-error }}" == "true" ]]; then
+            echo "❌ 发布失败，根据 fail-on-error=true 设置，终止 action 执行"
+            exit 1
+          else
+            echo "⚠️  发布失败，但根据 fail-on-error=false 设置，action 将继续完成"
+            echo "💡 您可以通过 outputs.release-status 检查发布状态"
+          fi
+        else
+          echo "✅ 发布成功，action 正常完成"
+        fi