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

退出代码

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

参考表 #

退出代码	名称	含义
`0`	成功	所有文件处理成功（或没有要处理的内容）
`1`	常规错误	未分类的错误：缺少参数、无效选项、激活失败、未知运行时错误
`2`	部分失败	至少一个文件失败而其他文件成功
`3`	认证错误	许可证无效、已过期或设备不匹配
`4`	网络错误	API 请求失败或超时

详细场景 #

退出 0 -- 成功 #

所有图像转换无错误。
未找到匹配的文件（空输入目录）。CLI 将此视为无操作成功。
getwebp status 正常完成。
getwebp auth <key> 成功激活。
getwebp logout 成功解绑。

退出 1 -- 常规错误 #

未提供输入路径（getwebp convert 无参数）。
许可证激活失败（getwebp auth <invalid-key>）。
注销失败（例如 not_activated、device_not_found）。
未捕获的异常或未处理的承诺拒绝。

处理方法： 检查 stderr（或使用 --json 时的 JSON message 字段）了解详情。通常不可重试，除非采取用户操作。

退出 2 -- 部分失败 #

批量转换，其中某些文件转换而其他文件失败（例如损坏的输入、特定文件的权限被拒绝）。
当任何结果具有 status: "error" 时，resolveExitCode() 函数返回 2。

处理方法： 解析 --json 输出以识别哪些文件失败。仅重试失败的文件，或调查每个文件的错误。

退出 3 -- 认证错误 #

许可证密钥无效或已撤销。
许可证已过期。
设备指纹与激活记录不匹配。

处理方法： 使用 getwebp auth <key> 重新激活，在 getwebp.com/pricing 续期许可证，或在 getwebp.com/dashboard 检查设备绑定。

退出 4 -- 网络错误 #

无法访问 GetWebP API 服务器。
请求超时。

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

特殊退出代码 #

退出代码	含义
`130`	用户使用 Ctrl+C 中断（SIGINT）。标准 Unix 约定：128 + 信号编号。

Shell 脚本示例 #

基本：任何错误时失败 #

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

基于退出代码的分支 #

#!/bin/bash
 
getwebp convert ./images --json > results.json
code=$?
 
case $code in
  0)
    echo "All images converted successfully."
    ;;
  1)
    echo "Error: check arguments or license." >&2
    exit 1
    ;;
  2)
    echo "Warning: some files failed. Check results.json for details." >&2
    # 管道继续 -- 部分输出仍然可用
    ;;
  3)
    echo "License error. Re-activate with: getwebp auth <key>" >&2
    exit 1
    ;;
  4)
    echo "Network error. Retrying in 30s..." >&2
    sleep 30
    getwebp convert ./images --json > results.json
    ;;
  *)
    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.json
  code=$?
 
  if [ $code -eq 0 ]; then
    echo "Success on attempt $i."
    exit 0
  elif [ $code -eq 4 ] && [ $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.json
  continue-on-error: true
 
- name: Check conversion result
  run: |
    code=${PIPESTATUS[0]:-$?}
    if [ "$code" -eq 2 ]; then
      echo "::warning::Partial conversion failure -- check conversion.json"
    elif [ "$code" -ne 0 ]; then
      echo "::error::getwebp exited with code $code"
      exit 1
    fi

JSON 输出和退出代码 #

使用 --json 时，退出代码和 JSON 负载协同工作：

退出代码	JSON `success`	JSON `status`
`0`	`true`	`"success"`
`1`	`false`	`"error"`
`2`	`false`	`"error"`
`3`	`false`	`"error"`
`4`	`false`	`"error"`

JSON error 字段提供机器可读的错误代码（例如 missing_input、network_unreachable、invalid_token）。查看 json-output.md 了解完整的 JSON 架构。

另请参阅 #

README -- 概述和快速入门
命令参考 -- 所有命令和选项
JSON 输出 -- CI 和 AI 代理的结构化输出架构

文档

退出代码