退出代码
GetWebP CLI 使用语义退出代码,因此 shell 脚本和 CI 管道可以对不同的失败模式做出反应,而无需解析输出文本。
退出代码
GetWebP CLI 使用语义退出代码,因此 shell 脚本和 CI 管道可以对不同的失败模式做出反应,而无需解析输出文本。
参考表#
| 退出代码 | 名称 | 含义 |
|---|---|---|
0 | Success | 所有操作成功完成(或没有要处理的内容) |
1 | GenericError | 未分类的错误:未捕获的异常、未处理的 Promise 拒绝、未知运行时错误 |
2 | UsageError | 无效 argv:未知标志、缺少必需参数、错误的标志值、互斥标志 |
3 | PartialFailure | 至少一个文件失败而其他文件成功(多文件命令) |
4 | AuthError | 许可证无效、过期、启动时已被撤销或设备限制已超 |
5 | NetworkError | API 请求失败、超时或 TLS 故障 |
6 | FreeLimitReached | 免费层级 20 文件限制已达——某些文件被跳过 |
75 | LicenseRevokedMidSession | 许可证在活跃的 watch 会话期间过期或被撤销 |
76 | DiskFull | watch 会话期间磁盘满,重试预算耗尽 |
130 | SIGINT | 用户使用 Ctrl+C 中断(128 + 信号 2) |
143 | SIGTERM | 进程被外部终止(128 + 信号 15) |
注意(v1.2.0 重新编号): 退出代码在 v1.2.0 中重新编号。如果您有来自旧版本的脚本:旧版
2(PartialFailure)现在是3,旧版3(AuthError)现在是4,旧版4(NetworkError)现在是5。新增代码2、6、75和143。
详细场景#
退出 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
;;
esacCI 管道:网络错误时重试#
#!/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 1GitHub 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
fiNDJSON 输出和退出代码#
使用 --json 时,退出代码和 NDJSON 事件协同工作。最后一个事件的 type 和 @level 确认结果:
| 退出代码 | 最终事件类型 | @level |
|---|---|---|
0 | convert.completed | info |
1 | convert.failed 或 fatal_error | error |
2 | convert.failed | error |
3 | convert.completed | info(检查 data.failedCount) |
4 | convert.failed | error |
5 | convert.failed | error |
6 | convert.truncated | warn |
错误事件的 data.code 字段提供机器可读的错误代码。查看 JSON 输出 了解完整的 NDJSON 架构。