# OctoHz CLI 故障排查

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

```bash
octohz <command> --help
```

## 版本太旧

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

```bash
npm install -g octohz@latest
octohz --version
```

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

## 401 Token 错误

检查当前配置：

```bash
octohz config show
```

重新设置：

```bash
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` 对 `&`、`|`、`>` 等字符敏感。长文本建议用文件参数：

```bash
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`，改用文件参数：

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

## 图片上传失败

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

检查：

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

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

## public-doc raw 页脚重复

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

推荐流程：

```bash
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`。

按提示执行：

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

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

## 502 或 5xx

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

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

## JSON 输出解析失败

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

```bash
octohz project onboard 1 > /tmp/onboard.json
```


---

**分类**：Octohz CLI（命令行界面）
**链接**：https://octohz.com/docs?doc=81