排错
Shoplazza CLI 的常见问题及解决办法。智能体相关的问题见 AI Toolkit 排错。
shoplazza: command not found
二进制不在 PATH 上。若用 npm 安装,确保全局 npm bin 目录在 PATH 上;若用 shell 脚本或二进制安装,默认装到 /usr/local/bin(make install 则为 ~/.local/bin)——把该目录加入 PATH。验证:
shell
shoplazza version
认证失败或 token 过期
查看当前状态:
shell
shoplazza auth status
若 token 缺失或过期,重新认证:
shell
shoplazza auth login --store-domain my-store.myshoplazza.com --domain products,orders
"scope 不足"报错
CLI 在每次调用前校验 OAuth scope。带上所需域重新登录——见认证 → 作用域映射:
shell
shoplazza auth login --store-domain my-store.myshoplazza.com --domain products,orders,customers
命令返回错误信封
错误以结构化信封打印到 stderr,带 hint:
json
{ "error": { "type": "api", "message": "Product not found", "hint": "Check the product ID and try again" }, "request_id": "req_abc123" }
读 hint 获知下一步,并把退出码对应到失败类型——见退出码。上报问题时带上 request_id。
不确定命令要哪些参数
内省 schema 或用内置 help:
shell
shoplazza schema products.create --view request
shoplazza products +search --help
诊断环境
shell
shoplazza doctor check
若你的版本尚无诊断,shoplazza auth status 是有用的兜底。
输出混进了管道
只有 stdout 承载数据(JSON);进度与警告走 stderr。若管道看起来乱了,多半是你把 stderr 也捕获了——重定向它(2>/dev/null)或参见输出约定。