> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/zh/zi-yuan/troubleshooting.md).

# 故障排查

下面的每个问题，都是 Squish CLI / MCP server 的真实失败模式，并附上实际存在时的错误文本。一般规则：CLI 在成功时退出 `0` ，在 `1` 失败时会在 stderr 输出消息；MCP 调用会把同样的消息作为工具错误返回，而不是崩溃。

## 未安装 ffmpeg 或 ffprobe

**现象** —— 每次运行都会立刻失败（exit 1），并显示：

```
需要 ffmpeg + ffprobe（Squish 会用它们抽帧）。
  macOS：brew install ffmpeg
  Ubuntu：sudo apt-get install ffmpeg
不能安装？托管 API 可以在不安装本地工具的情况下进行 squish——每天免费额度，无需信用卡：
  https://getsquish.app/developers
```

**原因** —— Squish 会调用系统里的 `ffmpeg`/`ffprobe` ，并先用 `-version` 对两者做预检查，然后才处理视频；如果 PATH 里缺了其中任何一个，它会尽早失败，而不是在运行中途挂掉。

**修复** —— 安装 ffmpeg（`brew install ffmpeg` 在 macOS 上， `sudo apt-get install ffmpeg` 在 Ubuntu 上），并确保你的 agent/MCP client 运行的环境继承了包含它的 PATH。如果你没法在本地安装， [托管 API](/squish/zh/ru-men/quickstart-api.md) 可以在远程完成同样的工作。

## Node 版本低于 20

**现象** — `npm`/`npx` 会在获取时打印一条 `EBADENGINE` “Unsupported engine” 警告， `@getsquish/squish`，CLI 运行时可能会失败。

**原因** —— 这个包声明了 `"engines": { "node": ">=20" }`；较旧的 Node 版本不受支持。

**修复** —— 升级到 Node 20 或更高版本（`node --version` 可检查）。

## MCP server 没有出现在 client 里

**现象** —— `squish_video` 在添加配置后，这个 tool 从未出现在 Claude Code、Claude Desktop、Cursor 或其他 MCP client 中。

**原因和修复** （按检查顺序）：

1. **配置拼写错误或文件不对** —— 该块必须位于 `mcpServers`下面，并且要有 `"command": "npx"` 和 `"args": ["-y", "@getsquish/squish", "mcp"]`，而且要放在你的 client 实际读取的配置文件里。对照 [MCP 快速入门](/squish/zh/ru-men/quickstart-mcp.md).
2. **Client 未重启** —— 大多数 client 会在启动时读取 MCP 配置；每次改完配置后都要重启 client。
3. **首次下载延迟** —— 第一次 `npx -y @getsquish/squish` 会从 npm 下载包，这可能会超过某些 client 对 server 启动的等待时间。先在终端里预热一次缓存： `npx -y @getsquish/squish mcp` 应该启动并停在 stdio 等待（按 Ctrl-C 停止）。如果这条命令在终端里就失败了，先修复那个错误——因为 client 启动的也是同一个进程。

## 使用错误（错误的标志或输入）

**现象** —— CLI 会退出 1，并把具体问题和 usage 行打印到 stderr：

```
usage: squish <video> [--density 3x3|4x4|5x5|6x6] [--start <t>] [--end <t>] [--out <dir>] [--json]
       squish mcp                 启动 MCP server（stdio）
       <t> = 秒数（90）或像表格上标注的时间码（1:30、1:07.3）
```

**原因** —— 真实消息及其触发条件如下：

| 错误                                              | 触发条件                                        |
| ----------------------------------------------- | ------------------------------------------- |
| `unknown flag: <flag>`                          | CLI 没有的标志——对照 usage 行检查拼写。                  |
| `missing <video> input`                         | 没有提供视频路径。                                   |
| `one video per run — got a second input: <arg>` | 两个位置参数——CLI 每次运行只接受一个视频。未加引号的带空格路径也会导致这个问题。 |
| `--density 必须是 3x3\|4x4\|5x5\|6x6 之一`           | 密度超出了支持的四种网格。                               |
| `--start 需要一个时间值——秒数（90）或时间码（1:30）`             | `--start`/`--end` ，但提供的值缺失或无法解析。            |
| `--out 需要一个目录`                                  | `--out` 后面没有值。                              |
| `squish mcp 不接受任何参数`                            | 在 `squish mcp` 后面还有额外参数——这个子命令不需要任何参数。      |

**修复** —— 修正标志或数值；消息会准确指出哪里错了。

## 窗口错误（`--start` / `--end`)

**现象** —— 带窗口的运行会被以下某条拒绝（exit 1，消息在 stderr；与 MCP tool error 的文本相同）：

* `start (…) 位于剪辑结束处或之后（…）` — `--start` 指向或越过了剪辑末尾。
* `window is empty — end (…) must be after start (…)` — `end` ≤ `start`。不会生成任何内容；这次运行会直接被拒绝。
* `start 必须是 ≥ 0 的时间` —— 负数的起始时间。
* `窗口太小，无法区分地址：跨越 M 毫秒共有 N 个单元格（engine 以毫秒精度搜索——在此密度下最小约为 K 毫秒）；请放大窗口或降低密度` —— 窗口比 **每个单元 2 毫秒** 可寻址下限还窄（例如，3×3 的 9 个单元格低于 18 ms，6×6 的 36 个单元格低于 72 ms）。低于这个下限时，相邻单元格会挤到无法区分的时间戳里，所以 engine 会拒绝，而不是假装可以处理。

**不是错误** —— 一个 `end` 超过剪辑时长的值会静默裁剪到末尾（“从 5:00 到剪辑结束”是个自然的请求）。带窗口的 `--json` run 会在 `"window": { "start": …, "end": … }` 中回显解析后的边界，这样你就能看到实际用了什么。

**修复** —— 把窗口放宽、降低密度，或者修正消息中指出的那个边界。记住时间码是相对于源视频的绝对值：请按你从表格上缩放时标注的值原样传入。

## `无法从 <input> 读取时长`

**现象** —— 在预检后，运行会立刻以以上消息失败。

**原因** — `ffprobe` 无法提取正的时长：这个文件不是视频、已损坏，或者其格式不被你本地的 ffmpeg 版本解码支持。

**修复** —— 先确认文件能在本地播放；如果可以，再检查你的 ffmpeg 版本是否支持它的编解码器（`ffprobe <file>` 会显示原始报错），或者重新编码为常见格式，比如 MP4/H.264。

## 找不到输出

**现象** —— 运行成功了（exit 0），但你在找 sheets。

**原因** —— 默认情况下，sheets 会生成在 **输入视频旁边** 作为 `<basename>.sheet-N.jpg` （例如 `clip.mov` → `clip.sheet-1.jpg` 在同一目录下）。

**修复** —— 传入 `--out <dir>` （CLI）或 `out_dir` （MCP）来选择目标位置。使用 `--json`时， `files[]` 数组会列出每个写出的 sheet 的绝对路径——请解析这个结果，不要猜。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/zh/zi-yuan/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.