JavaScript 渲染页面抓取失败时，应先区分网络请求、浏览器执行、页面状态、元素定位、权限验证和反自动化限制，再针对对应层级修复。最有效的排查方法是保存状态码、响应头、控制台日志、失败请求、页面 HTML 和截图，并在相同账号、网络、浏览器版本与运行参数下稳定复现。
先判断失败发生在哪一层
动态页面通常先返回 HTML 外壳，再由 JavaScript 请求接口并生成内容。因此，直接请求页面地址成功，并不代表目标数据已经返回。
问题：HTTP 请求成功，但正文为空
原因：正文由前端脚本异步渲染，原始 HTML 只包含根节点或加载占位符；也可能是页面调用的 JSON 或 GraphQL 接口失败。
解决：分别检查原始响应、浏览器渲染后的 DOM 和接口响应。如果数据直接存在于接口响应中，优先在授权和合规范围内调用接口；如果内容必须经浏览器执行后生成，则使用 Playwright、Puppeteer 或 Selenium，并等待可验证的业务状态。
问题：本地浏览器正常，抓取程序失败
原因：两者可能使用了不同的 Cookie、User-Agent、代理、DNS、时区、语言、浏览器内核或出口 IP，也可能存在无头模式差异。
解决：记录并对比请求头、Cookie、浏览器版本、视口、区域设置和出口网络。先使用可视模式复现，再逐项恢复生产参数，以定位真正的差异。
建立可复现的诊断流程
第一步：记录基础证据
每次失败至少保存目标 URL、最终 URL、HTTP 状态码、重定向链、响应头、关键接口响应、控制台错误、页面错误、失败请求、截图和渲染后的 HTML。不要只依赖最终异常消息。
第二步：确认页面完成条件
使用稳定的业务条件判断页面是否可抓取，例如正文容器出现、列表数量大于零、加载标记消失或目标接口成功返回。避免仅使用固定等待时间，也不要把网络完全空闲作为所有站点的通用完成条件，因为埋点、轮询和广告请求可能长期存在。
第三步：缩小故障范围
按“页面导航、脚本执行、接口请求、权限状态、元素定位、内容提取、数据落库”的顺序逐层验证。每次只改变一个变量，例如是否无头、是否使用代理、是否加载图片或是否复用登录状态。
第四步：构造最小复现
只保留一个 URL、一个浏览器上下文和一个目标字段，关闭并发、重试与复杂中间件。最小复现稳定后，再逐步加入登录、代理、并发和持久化逻辑。
页面打开但抓不到正文
问题：选择器始终找不到元素
原因：选择器可能已经失效，目标元素尚未出现，页面发生重定向，内容位于 iframe 或 Shadow DOM 中，或者站点针对不同设备返回了不同结构。
解决：先截图并检查最终 URL，再保存渲染后的 DOM。优先使用稳定的 id、data 属性、ARIA 属性或结构关系定位，减少对随机类名和深层 CSS 路径的依赖。定位成功后，再等待元素可见或内容非空。
问题：能定位元素，但文本为空
原因：节点可能先创建后填充，内容通过伪元素、Canvas 或子组件显示，也可能被虚拟列表移出 DOM。
解决：等待文本长度、属性值或子节点数量满足条件。若信息绘制在 Canvas 中，应优先查找其数据源或页面接口；只有在确有授权且不存在结构化数据源时，才考虑 OCR。
问题：抓到了加载中、暂无数据或错误提示
原因：程序把占位状态误判为完成状态，或接口失败后页面仍然返回了可匹配的容器。
解决：将成功条件设置为目标内容出现，同时检查错误提示、登录提示和空状态。成功、业务空数据与技术失败必须分别记录，避免错误重试或写入无效数据。
等待超时或页面长期加载
问题：等待 networkidle 一直超时
原因：页面可能持续发送统计、WebSocket、长轮询或广告请求，网络不会进入完全空闲状态。
解决：导航阶段可等待 DOMContentLoaded，随后等待目标元素或关键接口。把导航超时、接口超时和元素等待超时分开设置，以便识别真正的瓶颈。
问题：增加固定等待后仍不稳定
原因：固定等待只能掩盖竞态条件，无法适应网络波动、缓存差异和接口失败。
解决：改用条件等待，并为关键步骤设置明确上限。超时后保存现场信息，再根据错误类型决定是否重试。
问题：重试很多次仍然失败
原因：认证失败、选择器失效、参数错误和访问被拒绝通常不是瞬时故障，无差别重试只会增加负载。
解决：仅对超时、连接中断、临时服务错误等可恢复故障进行有限重试，并采用指数退避与随机抖动。对于 401、403、明确验证码和结构变化，应停止任务并进入专项处理。
浏览器可见但无头模式失败
问题：有头模式成功，无头模式内容为空
原因：浏览器版本、启动参数、字体、图形能力、视口或自动化特征不同，页面逻辑也可能依赖可见状态。
解决：固定浏览器及驱动版本，统一视口、语言、时区和字体环境；对比两种模式的截图、控制台日志和接口响应。不要只修改 User-Agent，因为多数环境差异并非单一请求头造成。
问题：容器或服务器中失败
原因：常见因素包括缺少系统依赖、字体不完整、共享内存不足、沙箱配置不兼容、证书异常或进程权限受限。
解决：使用框架官方支持的浏览器镜像或安装清单，检查系统日志和浏览器启动日志，并为容器配置足够的内存与共享内存。只有在理解安全影响后，才调整沙箱相关参数。
接口请求失败或数据为空
问题：页面框架加载成功，关键接口返回 401 或 403
原因：请求缺少会话 Cookie、访问令牌、CSRF 信息、来源校验字段或必要权限。
解决：从浏览器网络面板确认请求流程，检查令牌来源、有效期和 Cookie 作用域。优先完成网站提供的正式登录流程或使用官方 API，不要通过绕过访问控制获取数据。
问题：接口返回 200，但业务数据为空
原因：HTTP 成功不等于业务成功。请求参数、地区、账号权限、分页游标或业务状态可能不正确。
解决：解析响应中的业务状态码、错误字段和分页信息，并与浏览器中成功请求的参数逐项比较。对空列表设置合理终止条件，防止无限翻页。
问题：GraphQL 请求失败
原因：查询文本、变量、操作名、持久化查询哈希或鉴权信息可能已经变化。
解决：核对请求体和响应中的 errors 字段，不要只判断 HTTP 状态码。接口契约允许时，使用正式客户端或公开文档生成请求，减少手工拼装错误。
登录状态失效与权限不足
问题：保存的 Cookie 无法复用
原因：Cookie 可能过期、绑定设备环境，或缺少 localStorage、sessionStorage 中的认证信息；跨域登录还可能涉及多个域名。
解决：使用浏览器框架提供的存储状态能力保存完整上下文，加载后先访问账号页验证登录状态。发现失效时重新执行授权登录流程，不要无限复用过期状态。
问题：任务执行一段时间后跳回登录页
原因：会话过期、账号被登出、并发会话互相挤占，或刷新令牌流程失败。
解决：为登录页 URL、登录表单和 401 响应设置监控。将重新认证作为独立流程，并限制账号并发；涉及多因素认证时，应采用站点允许的服务账号或官方集成方案。
懒加载、滚动加载和分页内容缺失
问题：只能抓到首屏内容
原因：后续内容需要滚动进入视口、触发 IntersectionObserver、点击加载更多或请求下一页游标。
解决：分段滚动并等待列表数量增长，直到出现结束标记、连续多轮无新增或达到业务上限。每轮记录列表数量和分页游标，避免仅凭页面高度判断完成。
问题：滚动后前面的节点消失
原因：虚拟列表只保留视口附近节点，直接在最后统一读取 DOM 会丢失早期项目。
解决：每次滚动后立即提取当前可见条目，并使用稳定业务主键去重。若存在合法可用的分页接口，直接按游标抓取通常更稳定。
问题：分页重复或漏页
原因：页码或游标更新错误、请求并发导致顺序混乱，数据源在抓取期间发生变化，或末页条件判断不正确。
解决：记录每次请求的页码、游标、返回数量和首尾数据标识。使用业务主键去重，并在接口支持时固定排序字段或时间范围。
iframe、Shadow DOM 与新窗口内容缺失
问题：页面上看得到，主文档中却找不到
原因：目标内容可能位于 iframe、开放式 Shadow DOM、新标签页或弹窗中。
解决：检查 frame 列表和元素树，切换到正确 frame 后定位；对于开放式 Shadow DOM，使用框架支持的穿透定位方式；点击会打开新页面时，应先监听新页面事件再执行点击。
问题：跨域 iframe 无法直接读取
原因：浏览器同源策略限制了页面脚本访问跨域 frame，但自动化框架通常可以在其支持范围内切换 frame 并操作页面。
解决：通过自动化框架提供的 frame API 定位目标框架，并确认其已经导航完成。若内容受权限或访问控制保护，应使用正式授权方式获取。
验证码、限流与反自动化拦截
问题：出现 403、429、验证码或访问异常
原因：请求频率过高、并发过大、账号或 IP 触发限制，或访问行为违反站点规则。
解决：立即降低并发与频率，读取 Retry-After 等响应信息，并检查 robots.txt、服务条款和 API 使用政策。优先申请官方 API、数据导出或合作访问权限，不应尝试绕过验证码或访问控制。
问题：偶发空白页，刷新后恢复
原因：可能是临时限流、CDN 节点异常、接口超时或前端资源加载失败。
解决：按状态码和失败请求分类统计，不要把所有空白页归为选择器问题。对可恢复错误有限重试，并保留失败样本用于分析。
中文乱码、内容截断与数据重复
问题：抓取结果出现乱码
原因：响应编码识别错误、服务端声明与实际编码不一致，或在字符串与字节之间进行了错误转换。
解决：检查 Content-Type、页面 meta charset 和原始字节。浏览器渲染后的 DOM 通常已经完成解码；直接调用接口时，应按明确编码解析并保留原始响应以便核对。
问题：文本不完整或缺少展开内容
原因：正文被“展开”按钮折叠，内容分批加载，或者提取的是可见文本而非完整文本。
解决：确认业务需要的是可见内容还是完整节点内容。按页面交互点击展开并等待内容更新，同时记录展开前后长度，避免误判。
问题：结果大量重复
原因：分页游标未更新、滚动事件重复触发、任务重试后重复入库，或不同 URL 指向同一内容。
解决：使用站点业务 ID 作为首选唯一键；缺少 ID 时，可结合规范化 URL、标题、发布时间和内容摘要生成去重键。数据库层应设置唯一约束，以防应用层漏判。
批量抓取中的崩溃和资源泄漏
问题：运行一段时间后越来越慢
原因：页面、上下文、事件监听器或下载对象没有释放，也可能是截图、日志和响应体长期保存在内存中。
解决：在 finally 中关闭页面和上下文，限制同时打开的页面数量，避免无界队列。持续监控内存、CPU、浏览器进程数、任务耗时和失败率。
问题：并发提高后失败率激增
原因：本机资源、目标服务承载能力、账号会话或代理连接池存在上限。
解决：逐级增加并发并记录吞吐与错误率，找到稳定区间。对每个域名、账号和代理分别限流，并为队列设置背压。
生产环境修复清单
页面与浏览器
- 固定浏览器与自动化框架版本。
- 使用业务条件判断渲染完成。
- 失败时保存截图、最终 URL 和 DOM。
- 使用稳定选择器，并为页面改版建立告警。
网络与接口
- 记录状态码、重定向、关键响应头和业务错误码。
- 区分超时、权限失败、限流和业务空数据。
- 只对可恢复错误进行有限重试。
- 遵守目标站点的访问政策与数据使用要求。
认证与数据
- 执行任务前验证登录状态与数据权限。
- 设置明确的分页终止条件和唯一键。
- 保存失败样本，但避免日志泄露 Cookie、令牌和个人信息。
- 为接口字段和页面结构变化增加监控。
常见问题
抓取 JavaScript 页面一定要用无头浏览器吗？
不一定。数据可通过稳定、授权的接口获取时，优先使用接口；只有必须执行脚本、交互或浏览器渲染时，才使用无头浏览器。
为什么固定等待 10 秒仍然抓取失败？
固定时间无法保证接口完成或元素出现。应改为等待正文容器、数据数量、关键接口响应或加载状态消失，并设置超时上限。
浏览器中正常，无头模式为什么失败？
常见原因包括浏览器版本、视口、字体、时区、启动参数、登录状态和出口网络不同。需要对比截图、控制台日志、失败请求和关键接口响应。
出现 403 或 429 应该怎么排查？
先降低并发与请求频率，检查响应头、账号权限、访问政策和官方 API。对于明确的验证码或访问控制，不应尝试绕过。
如何避免滚动加载页面出现重复数据？
每轮滚动后立即提取数据，记录列表数量和分页游标，并使用业务 ID 或规范化后的组合字段建立唯一键。
生产环境必须记录哪些信息？
至少记录任务 ID、目标与最终 URL、状态码、错误分类、耗时、关键接口结果和重试次数；失败任务还应保存脱敏后的截图、DOM 与控制台日志。
总结
排查 JavaScript 渲染页面抓取失败时，应按网络、浏览器执行、接口、认证、页面状态、元素定位和数据处理逐层定位。使用业务条件等待，保存截图、DOM、控制台与网络证据，对权限失败、限流、结构变化和瞬时故障分类处理。修复后通过稳定选择器、有限重试、并发控制、唯一键、资源释放和监控机制降低复发概率。