5.6 KiB
5.6 KiB
常见问题排查
先按输出判断类型：[捕获]/[套件] 前缀的警告是提示（不中断）；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。