Sidney Zhang
9020752eed
- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明 - 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题 - 添加 CDP 端口连通性预检查及启动指引
7.3 KiB
7.3 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）再运行。
CDP 端口不可达（脚本前置探测）
- 现象：
[!] CDP 端口不可达: http://localhost:9222（Playwright 连接之前就报出）。 - 原因一：浏览器根本没带
--remote-debugging-port=9222启动。按提示命令重启。 - 原因二：带参数启动了但仍不通——有 Chrome/Edge 残留进程占着默认 profile，新实例的调试端口参数被已运行实例吞掉（Chrome 单实例复用机制）。彻底退出所有该浏览器进程（任务管理器确认）后重启；或改用独立目录启动：
chrome.exe --remote-debugging-port=9222 --user-data-dir="C:/yts-cdp"。 - 脚本已在附加前先探测端口并区分这两种情况，遇到即按输出指引处理，无需先跑 Playwright 再排错。
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。 - 解决：重新捕获一次，或确认页面是在已登录的目标所有者分析页发起的群组搜索。
回放查询
回放报 InvalidHeader（Invalid leading whitespace / 伪头）
- 现象：
requests抛InvalidHeader: Invalid leading whitespace, expected field value...。 - 原因：套件 headers 里残留 HTTP/2 伪头（
:authority、:method、:path、:scheme），不能当普通头发送。 - 解决：脚本已双保险——捕获时自动过滤（输出
已过滤 HTTP/2 伪头 N 个），回放时再滤一次兜住旧 bundles.json；新版本无需人工处理。
跳转到 Google 登录页但 profile 里看得到 cookie
- 现象：Cookies 文件里有 SAPISID/SID/__Secure-3PSID 等，页面仍停在 accounts.google。
- 原因：cookie 存在不等于会话有效，Google 已在服务端让该会话过期。
- 解决：由用户在该浏览器手动重新登录一次，之后继续复用该会话；不要试图靠改 cookie 文件修复。
回放全量 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前缀执行；脱离项目时直接uv run <脚本>（脚本头部 PEP 723 声明会自动装依赖，见uv-env-setup技能）；或单独pip install requests playwright openpyxl。