OctoHz CLI 故障排查

本文收集 octohz 使用中最常见的问题。完整命令参数请先看：

octohz <command> --help

版本太旧

如果文档里有命令，但本机 octohz --help 看不到，先升级：

npm install -g octohz@latest
octohz --version

例如 fengshui 命令需要 octohz 2.7.0 或更新版本。

401 Token 错误

检查当前配置：

octohz config show

重新设置：

octohz config set-token <apiToken>
octohz config set-private-key <privateKey>
octohz config set-admin-token <adminToken>

400 参数错误

400 通常是字段缺失或格式错误。不要原样重试，按错误提示改参数。

常见例子：

• 日期必须是 YYYY-MM-DD
• 数字字段不要带中文单位
• 分类有的命令支持 slug，有的只支持数字 ID
• JSON 参数必须是合法 JSON，不能写 ...

Windows 特殊字符

Windows cmd.exe 对 &、|、> 等字符敏感。长文本建议用文件参数：

octohz publish --description-file /tmp/desc.md
octohz doc add --content-file /tmp/note.md
octohz public-doc update 77 --content-file /tmp/doc.md

如果一定要在 Windows 传特殊字符，优先使用 PowerShell。

Markdown 换行没有生效

Shell 里的 \n 不一定会变成真实换行。长 Markdown 不要用 --content 或 --description，改用文件参数：

octohz doc add --title "笔记" --content-file /tmp/note.md

图片上传失败

正文中的本地图片会在提交前自动上传。任何一张图片失败，整篇文档会拒绝提交。

检查：

• 文件路径是否存在
• 图片格式是否支持
• 文件是否过大
• Markdown 图片语法是否正确

封面图和图标通常只支持 jpg/png/gif/webp，不支持 SVG。

public-doc raw 页脚重复

public-doc get --raw 的输出末尾可能带系统自动页脚。用 raw 作为底稿回写前，要删除页脚。

推荐流程：

octohz public-doc get 77 --raw > /tmp/doc.md
# 删除末尾系统页脚后再编辑
octohz public-doc update 77 --title "标题" --content-file /tmp/doc.md

project entries 未显示

老项目如果没有激活 entries 聚合，project get 或 project onboard 可能提示 migrationRequired。

按提示执行：

octohz project migrate-entries <id> --dry
octohz project migrate-entries <id>

新项目通常不需要这一步。

502 或 5xx

站点可能正在部署或重启。等 15 到 30 秒后再试。

如果持续失败，查看项目归档 recent events 或服务器日志。

JSON 输出解析失败

上传进度、警告等信息可能走 stderr。自动化脚本应只解析 stdout，并检查命令退出码。

octohz project onboard 1 > /tmp/onboard.json