文档

退出代码

GetWebP CLI 使用语义退出代码,因此 shell 脚本和 CI 管道可以对不同的失败模式做出反应,而无需解析输出文本。

退出代码

GetWebP CLI 使用语义退出代码,因此 shell 脚本和 CI 管道可以对不同的失败模式做出反应,而无需解析输出文本。


参考表#

退出代码名称含义
0Success所有操作成功完成(或没有要处理的内容)
1GenericError未分类的错误:未捕获的异常、未处理的 Promise 拒绝、未知运行时错误
2UsageError无效 argv:未知标志、缺少必需参数、错误的标志值、互斥标志
3PartialFailure至少一个文件失败而其他文件成功(多文件命令)
4AuthError许可证无效、过期、启动时已被撤销或设备限制已超
5NetworkErrorAPI 请求失败、超时或 TLS 故障
6FreeLimitReached免费层级 20 文件限制已达——某些文件被跳过
75LicenseRevokedMidSession许可证在活跃的 watch 会话期间过期或被撤销
76DiskFullwatch 会话期间磁盘满,重试预算耗尽
130SIGINT用户使用 Ctrl+C 中断(128 + 信号 2)
143SIGTERM进程被外部终止(128 + 信号 15)

注意(v1.2.0 重新编号): 退出代码在 v1.2.0 中重新编号。如果您有来自旧版本的脚本:旧版 2(PartialFailure)现在是 3,旧版 3(AuthError)现在是 4,旧版 4(NetworkError)现在是 5。新增代码 2675143


详细场景#

退出 0 -- 成功#

  • 所有图像转换无错误。
  • 未找到匹配的文件(空输入目录)。CLI 将此视为无操作成功。
  • getwebp status 正常完成。
  • getwebp auth <key> 成功激活。
  • getwebp logout 成功解绑。
  • getwebp watch 收到 SIGINT 并优雅关闭(SIGINT 具体退出代码为 130)。

退出 1 -- GenericError#

  • 激活以未分类的服务器错误失败。
  • 注销因意外原因失败。
  • 未捕获的异常或未处理的 Promise 拒绝。

处理方法: 检查 stderr(或使用 --json 时的 NDJSON data.code 字段)了解详情。通常不可重试,除非采取用户操作。

退出 2 -- UsageError#

  • 传递了未知标志(例如 getwebp convert --unknown)。
  • 缺少必需参数(例如 getwebp auth 无密钥)。
  • 无效的标志值(例如 --quality abc)。
  • 互斥标志组合(例如 --quiet --verbose)。

处理方法: 修复命令语法。无需重试。

退出 3 -- PartialFailure#

  • 批量转换,其中某些文件转换而其他文件失败(例如损坏的输入、特定文件的权限被拒绝)。

处理方法: 解析 --json 输出(convert.completed 事件的 data.results 数组)以识别哪些文件失败。仅重试失败的文件,或调查每个文件的错误。

退出 4 -- AuthError#

  • 许可证密钥无效或启动时已被撤销。
  • 许可证已过期。
  • 设备限制已达(所有插槽在使用中)。

处理方法: 使用 getwebp auth <key> 重新激活,在 getwebp.com/pricing 续期许可证,或通过 getwebp logout仪表板 释放设备插槽。

退出 5 -- NetworkError#

  • 无法访问 GetWebP API 服务器。
  • 请求超时。
  • TLS 证书故障。

处理方法: 可重试。等待并使用指数退避重试。检查网络连接和防火墙规则。

退出 6 -- FreeLimitReached#

  • 免费计划 20 文件限制在 convert 运行期间被达到。超出限制的文件被跳过。
  • 这不是失败——已处理的文件已成功。退出代码表示运行被截断。

处理方法:getwebp.com/pricing 升级到 Pro 以移除限制。

退出 75 -- LicenseRevokedMidSession#

  • 许可证在 getwebp watch 运行时被撤销或过期。监视会话被终止。

处理方法: 重新激活或续期许可证,然后重新启动 watch

退出 130 -- SIGINT#

  • 用户按下了 Ctrl+C。CLI 执行优雅关闭(在退出前排空进行中的转换)。

退出 143 -- SIGTERM#

  • 进程收到了 SIGTERM(例如来自进程管理器或 kill <pid>)。

Shell 脚本示例#

基本:任何错误时失败#

#!/bin/bash
set -e
 
getwebp convert ./images -o ./dist
echo "All images converted."

基于退出代码的分支#

#!/bin/bash
 
getwebp convert ./images --json > results.ndjson
code=$?
 
case $code in
  0)
    echo "All images converted successfully."
    ;;
  1)
    echo "Error: check stderr for details." >&2
    exit 1
    ;;
  2)
    echo "Usage error: fix the command syntax." >&2
    exit 1
    ;;
  3)
    echo "Warning: some files failed. Check results.ndjson for details." >&2
    # 管道继续 -- 部分输出仍然可用
    ;;
  4)
    echo "License error. Re-activate with: getwebp auth <key>" >&2
    exit 1
    ;;
  5)
    echo "Network error. Retrying in 30s..." >&2
    sleep 30
    getwebp convert ./images --json > results.ndjson
    ;;
  6)
    echo "Free plan limit reached. Some files were skipped. Upgrade at getwebp.com/pricing" >&2
    ;;
  *)
    echo "Unexpected exit code: $code" >&2
    exit 1
    ;;
esac

CI 管道:网络错误时重试#

#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=10
 
for i in $(seq 1 $MAX_RETRIES); do
  getwebp convert ./images -o ./dist --json > results.ndjson
  code=$?
 
  if [ $code -eq 0 ]; then
    echo "Success on attempt $i."
    exit 0
  elif [ $code -eq 5 ] && [ $i -lt $MAX_RETRIES ]; then
    echo "Network error. Retry $i/$MAX_RETRIES in ${RETRY_DELAY}s..." >&2
    sleep $RETRY_DELAY
    RETRY_DELAY=$((RETRY_DELAY * 2))
  else
    echo "Failed with exit code $code on attempt $i." >&2
    exit $code
  fi
done
 
exit 1

GitHub Actions 示例#

- name: Convert images
  run: |
    getwebp convert ./src/images -o ./dist/images --json > conversion.ndjson
  continue-on-error: true
 
- name: Check conversion result
  run: |
    code=${PIPESTATUS[0]:-$?}
    if [ "$code" -eq 3 ]; then
      echo "::warning::Partial conversion failure — check conversion.ndjson"
    elif [ "$code" -eq 6 ]; then
      echo "::warning::Free plan limit reached — some files were skipped"
    elif [ "$code" -ne 0 ]; then
      echo "::error::getwebp exited with code $code"
      exit 1
    fi

NDJSON 输出和退出代码#

使用 --json 时,退出代码和 NDJSON 事件协同工作。最后一个事件的 type@level 确认结果:

退出代码最终事件类型@level
0convert.completedinfo
1convert.failedfatal_errorerror
2convert.failederror
3convert.completedinfo(检查 data.failedCount
4convert.failederror
5convert.failederror
6convert.truncatedwarn

错误事件的 data.code 字段提供机器可读的错误代码。查看 JSON 输出 了解完整的 NDJSON 架构。


另请参阅#