# 常见问题排查

先按输出判断类型：`[捕获]`/`[套件]` 前缀的警告是**提示**（不中断）；`SystemExit` / 致命错误则中断。核心是先分清是「没登录 / 套件没捕到 / 回放 401 / 查不到」。

## 登录态与浏览器

### 跳转到 Google 登录页
- 现象：脚本报「当前会话未登录，已跳转到 Google 登录页」，或捕获时停在 accounts.google。
- 原因：没复用已登录 YouTube Studio 的会话，开了全新会话。
- 解决：改用 `--user-data-dir + --channel`（方式 A，需先关闭对应浏览器），或 `--connect http://localhost:9222`（方式 B，浏览器开在调试端口）。

### 启动/连接浏览器失败
- 现象：`[!] 启动/连接浏览器失败: ...`。
- 原因：方式 A 时浏览器未关闭（用户数据目录被占用）；方式 B 时调试端口没起。
- 解决：方式 A 关闭 Chrome/Edge 后重试；方式 B 先 `chrome.exe --remote-debugging-port=9222`（或 msedge）再运行。

### channel 不匹配
- 现象：启动后用 --user-data-dir 报告浏览器品牌不符。
- 原因：`--channel` 与用户数据目录指向的浏览器不是同一品牌（chrome / msedge）。
- 解决：`--channel` 必须与 `--user-data-dir` 指向的浏览器一致。

### CDP 附加后页面是空白/不是目标所有者
- 现象：连上 9222 但页面停在别的标签或未登录。
- 原因：`connect_over_cdp` 取的是第一个 context 的新标签，可能与已有登录标签不同步。
- 解决：确保浏览器已登录目标所有者；必要时先用浏览器手动打开所有者 URL 确认登录态。

## 套件捕获（`_capture_bundle`）

### 捕获不到 search_groups 请求
- 现象：`[捕获] ... 未捕获到 search_groups 请求` / `TimeoutError`。
- 原因：没触发搜索，或页面不是高级模式分析页，或搜索框选择器没猜中。
- 解决：在浏览器里于该所有者分析页**顶部搜索/筛选框输入任意词并回车**（只需一次）。脚本会提示并等待（默认 180 秒，可 `--wait-seconds` 调大）。若选择器每次都猜不中，可先手动搜索确认页面是高级模式。

### 警告：externalOwnerId 与 URL ownerId 不一致
- 现象：`[捕获] 警告：请求体 externalOwnerId=... 与 URL ownerId=... 不一致，以请求体为准`。
- 原因：URL 指向的 owner 与当前页面 delegation 语境不同（切换所有者后会残留）。
- 解决：确认 URL 是目标所有者；页面确实停在目标所有者高级模式页再捕获。

### 警告：缺 Authorization/Cookie/delegation
- 现象：`[捕获] 警告：缺少 Authorization（SAPISIDHASH）头 / ...`。
- 原因：捕获到的请求头不全，或请求体缺 `context.user.delegationContext`。
- 解决：重新捕获一次，或确认页面是在已登录的目标所有者分析页发起的群组搜索。

## 回放查询

### 回放全量 401
- 现象：结果备注大量 `HTTP401（鉴权失败：套件缺 Authorization/Cookie 或已过期，请重新捕获）`。
- 原因：套件过期（鉴权头是逐请求计算的），或头不全。
- 解决：重新用 `--url` 在线捕获套件（更新到 `--save-bundles`），再回放。查 `references/input-guide.md` 第 2 节核对 headers。

### HTTP403 / 无权限
- 现象：`HTTP403（无权限或 delegation 语境不符）`。
- 原因：delegation 语境不属于当前登录账号，或该所有者无授权。
- 解决：确认登录账号对该内容管理器有权限，重新捕获正确所有者的套件。

### HTTP429 / 限流
- 现象：`HTTP429（限流：调低 --max-workers 或稍后重试）`。
- 原因：并发太高或请求过频繁。
- 解决：降低 `--max-workers`，稍后重试。

### 网络错（ERR）
- 现象：备注 `网络错: ...`。
- 原因：网络不通 / 域名被拦 / 代理导致请求失败。
- 解决：检查网络与代理，重试。

## 匹配结果

### 某名字显示「无结果」
- 现象：备注含 `无结果`。
- 原因：该所有者下没有匹配的群组，或名字与 displayName 不完全一致。
- 解决：换所有者再试，或用更短关键词重跑；若名字疑似错字，用品牌名做短词触发变体候选。

### 名字只在候选里（大小写/空格差异）
- 现象：备注含候选 `名=ID`，但没有精确命中。
- 原因：列表里的 displayName 与输入存在大小写/空格差异。
- 解决：直接采用候选 groupId，或把名单里的名字改成与 displayName 完全一致后重跑。

### 同名群组跨所有者都有
- 现象：多个所有者都返回候选，或都命中但归属不同。
- 原因：不同内容管理器可各有一个「X 漫剧-N」。
- 解决：以**精确 displayName** 命中为准核对实体归属；跨所有者同名时确认要的是哪个 ownerId 下的 groupId。

### 名单不识别 / 空名单
- 现象：`[!] 名单为空或无法解析：...`，或 `无法识别名字列`。
- 原因：列名不在别名表，或文件结构不对。
- 解决：按 `references/input-guide.md` 第 1 节整理：用别名列名（群组名称/group_name/实体名称/名称），或改为单列文件。

## 输出问题

### 输出行数为 0 / 找不到输出文件
- 现象：`[输出] 精确命中 0/N`，或默认路径没找到。
- 解决：确认 `--names` 能解析出名单；`--out` 显式指定路径。缺 openpyxl 时 `.xlsx` 自动回退为 `.csv`（脚本会提示）。

### 缺依赖报 ModuleNotFoundError
- 现象：`ModuleNotFoundError: No module named 'requests'` 或 `'playwright'` 或 `'openpyxl'`。
- 解决：项目根 `uv sync` 后统一用 `uv run` 前缀执行；或单独 `pip install requests playwright openpyxl`。