故障排除

GetWebP CLI 常见问题的解决方案，按类别组织。每个条目遵循问题 / 原因 / 解决方案的模式，这样您可以快速找到您的修复方案。

目录 #

安装问题
许可证和激活问题
转换问题
网络问题
调试模式
已知问题
仍然卡住了吗？

安装问题 #

"command not found: getwebp"#

原因： 二进制文件不在您的系统 PATH 上，或它没有正确重命名。

解决方案：

# macOS / Linux：移动到 PATH 上的目录
sudo mv getwebp-macos-arm64 /usr/local/bin/getwebp
chmod +x /usr/local/bin/getwebp
 
# 验证
getwebp --version

在 Windows 上，将文件重命名为 getwebp.exe，并将其放在 C:\Windows\System32 中或将其文件夹添加到系统 PATH 环境变量。

"permission denied" 运行 getwebp 时 (macOS / Linux)#

原因： 二进制文件没有执行权限。

解决方案：

chmod +x /usr/local/bin/getwebp

macOS Gatekeeper 阻止二进制文件（"无法打开，因为开发者无法验证"）#

原因： macOS 隔离从互联网下载的未签名二进制文件。

解决方案：

xattr -cr /usr/local/bin/getwebp

然后再次运行 getwebp --version。如果 macOS 仍然阻止它，请转到系统设置 > 隐私与安全，并点击 GetWebP 消息旁边的仍然允许。

Node.js 版本不兼容（从源代码构建）#

原因： 如果您从源代码构建 GetWebP 而不是使用预构建的二进制文件，该项目需要支持 ES 模块和 fetch 的最小 Node.js 版本。

解决方案：

使用 Node.js 18.x 或更高版本（推荐 20.x LTS）。
运行 node --version 检查您的当前版本。
使用版本管理器如 nvm 或 fnm 切换版本。

大多数用户应该从 getwebp.com/download 下载预构建的二进制文件，而不是从源代码构建。

许可证和激活问题 #

"激活失败：无效的许可证密钥"#

原因： 许可证密钥输入错误、已经被退款或已被撤销。

解决方案：

仔细检查您的购买确认电子邮件中的密钥。密钥的格式为 XXXX-XXXX-XXXX-XXXX。
复制粘贴密钥以避免拼写错误：
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```
如果密钥最近购买，请等待几分钟以完成支付处理。
在仪表板检查您的许可证状态。

退出代码： 1（常规错误）

"激活失败"由于达到设备限制 #

原因： 您的许可证密钥已在最大数量的设备上激活。Pro 允许最多 3 个 CLI 设备和 3 个 WordPress 站点。

解决方案：

检查当前设备绑定：
```
getwebp status
```
输出显示 Devices: X / Y used。
从您不再使用的设备注销以释放插槽：
```
getwebp logout
```
或通过在线仪表板解绑设备。
然后在新设备上激活：
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```

许可证显示为已过期 #

原因： 许可证订阅已过期或未续期。

解决方案：

使用以下验证过期时间：
```
getwebp status
```
在 getwebp.com/pricing 续期您的许可证。
续期后，重新激活：
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```

退出代码： 3（认证错误）

重新安装或更换硬件后"令牌无效或已过期"#

原因： GetWebP 将许可证与从机器的硬件 ID 派生的设备指纹联系起来。重新安装操作系统、更换硬件或将配置文件复制到另一台机器会使存储的令牌失效。

解决方案：

在当前设备上重新激活许可证：
```
getwebp auth XXXX-XXXX-XXXX-XXXX
```
如果您用尽了设备插槽，请从旧设备上的 getwebp logout 或通过仪表板释放一个。

注销失败："无法访问服务器"#

原因： logout 命令需要网络访问以服务器端解绑设备。没有连接，本地凭据不会被清除。

解决方案：

检查您的互联网连接并重试：
```
getwebp logout
```
如果网络访问不可用，请改为通过在线仪表板解绑设备。

退出代码： 4（网络错误）

注销失败："此设备上未找到活跃许可证"#

原因： 此设备上当前没有激活许可证，或令牌已被清除。

解决方案： 无需操作。该设备已在免费计划上。使用以下验证：

getwebp status

转换问题 #

"错误：请指定输入路径"#

原因： convert 命令在未指定文件或目录的情况下运行。

解决方案：

# 提供路径作为位置参数
getwebp convert ./images
 
# 或使用 -i 标志
getwebp convert -i ./images

退出代码： 1 | JSON 错误代码： missing_input

网络问题 #

激活或注销期间"无法访问服务器"#

原因： CLI 无法连接到 api.getwebp.com。这可能由于没有互联网连接、防火墙、公司代理或 DNS 问题造成。

解决方案：

测试基本连接：
```
curl -I https://api.getwebp.com
```
如果在公司代理后面，配置您系统的 HTTP 代理设置。GetWebP 使用系统 fetch 实现，它尊重 HTTPS_PROXY 和 HTTP_PROXY 环境变量：
```
export HTTPS_PROXY=http://proxy.corp.example:8080
getwebp auth XXXX-XXXX-XXXX-XXXX
```
如果 DNS 是问题所在，请尝试使用公共 DNS 解析器（例如 1.1.1.1 或 8.8.8.8）。
等待并重试。API 有 5 秒超时。瞬时故障是可重试的。

退出代码： 4（网络错误） | JSON 错误代码： network_unreachable

状态显示"缓存"的数据 #

原因： getwebp status 无法访问服务器，因此显示了本地缓存中的最后已知状态。

解决方案： 这是离线时的预期行为。缓存的状态对转换仍然有效（许可证 JWT 在本地验证）。要刷新，恢复网络访问并运行：

getwebp status

调试模式 #

在报告错误或诊断意外问题时，使用 --debug 查看详细的内部日志。

启用调试输出 #

getwebp convert ./images --debug

--debug 标志隐含 --verbose。调试消息前缀为 [debug] 并写入 stderr，因此不会干扰 stdout 上的 --json 输出。

调试输出显示什么 #

文件扫描： 发现了哪些文件以及有多少个匹配。
处理管道： 每个文件的开始/结束，带有状态（success、error、skipped）。
许可证检查： 令牌验证结果和心跳活动。
配置： 配置文件位置和机器 ID 解析。

已知问题 #

符号链接被跳过 #

GetWebP 为了安全性跳过符号链接。如果您的图像目录包含符号链接，链接的文件将不被处理。

解决方案： 将实际文件复制或移动到目标目录，或指向 GetWebP 实际文件路径。

WebP 到 WebP 自覆盖被跳过 #

将 .webp 文件转换而不指定单独的输出目录时，输入和输出路径相同。GetWebP 检测到这一点并跳过文件以防止数据丢失。

解决方案： 使用 -o 指定不同的输出目录：

getwebp convert ./images -o ./images-reencoded

主机名更改后无法解密配置文件 #

~/.config/getwebp-nodejs/config.json 的配置文件使用机器的硬件 ID 加密。如果硬件 ID 更改（例如，在无法读取硬件 ID 的系统上主机名更改），存储的令牌变得不可读。

解决方案： 重新激活许可证：

getwebp auth XXXX-XXXX-XXXX-XXXX

如果需要，您可以使用 GETWEBP_CONFIG_DIR 环境变量覆盖配置目录。

仍然卡住了吗？#

使用 --debug 运行并保存输出：

getwebp convert ./images --debug 2>debug.log

检查您的退出代码以缩小类别：
```
echo $?
```
查看退出代码了解每个代码的含义。
访问仪表板检查您的许可证和设备状态。

文档

故障排除