技能介绍

先解决什么问题

把网页变成 PDF，看起来只是一句 page.pdf() 的事，实际工程里却处处是坑：长页面被截断、表头在翻页后消失、分栏内容被硬生生劈开、登录后的页面一抓就是空白，或者输出的 PDF 里字体与线上渲染不一致。这个技能关注的是「从真实页面拿到可用于归档、分发、打印的成品 PDF」，而不是简单地截图存档。

它如何工作

真实浏览器渲染：由 Puppeteer 启动无头浏览器，页面先完成 JavaScript 执行与资源加载，再走 Chromium 自带的 PDF 生成能力。因此 page.pdf() 输出的是矢量文本而非位图，打印缩放后依然清晰。
自定义页眉与页脚：通过参数注入页眉、页脚模板，可以放上文档标题、章节名、页码、生成时间等信息，避免事后手工给 PDF 补页码。
可控的分页行为：支持通过 CSS 分页规则与打印媒体设置控制断页位置，例如让章节标题不与正文分离、让表格不被切断。
认证页面也能渲染：支持以 Cookie 注入的方式进入需要登录的页面，先恢复会话状态，再对目标页面执行渲染，适合内部报表、后台详情页这类不对外开放的资源。

适用边界与注意点

PDF 走的是 Chromium 的 Page.printToPDF 能力，不是 CSS Paged Media 的完整实现，少数打印样式（如 break-inside 的部分行为）需要在实际页面中验证后再上线。
Cookie 注入依赖会话仍然有效，Cookie 过期、CSRF 令牌失效都会导致渲染出未登录页面，必要时在渲染前重新获取凭据。
依赖远程接口动态加载的页面，建议显式等待关键内容出现后再触发打印，否则 PDF 里可能只留下骨架屏。
被渲染站点的 robots.txt、服务条款与访问频率限制仍需自行评估，批量导出前先确认是否有授权。
该能力源自 Puppeteer 上游文档，同时存在基于 Puppeteer 的 MCP server 可用于浏览器自动化与调试场景。