Pyppeteer启动卡住或报错主因是Chromium下载失败，应手动指定executablePath并加ignoreHTTPSErrors、timeout等参数；截图前需waitForSelector或waitForFunction确保页面加载完成；PDF中文乱码需预装字体并注入CSS指定字体；page.pdf()和screenshot()必须await且参数严格符合规范。
Pyppeteer 启动时卡住或报 Browser closed unexpectedly
Pyppeteer 默认会下载 Chromium，但国内网络常导致下载失败或不完整，进而引发启动崩溃。它不会主动提示“下载失败”，而是静默卡在 launch() 或抛出模糊错误。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 手动指定已安装的 Chrome/Chromium 路径，跳过自动下载：
browser = await launch(executablePath='/usr/bin/chromium-browser')（Linux）或'C:\Program Files\Google\Chrome\Application\chrome.exe'（Windows） - 添加超时和忽略证书错误参数更稳妥：
await launch(ignoreHTTPSErrors=True, timeout=30000, headless=True) - 首次运行前先执行
pyppeteer-install命令（需在终端中运行），确保二进制文件完整；若失败，改用--skip-download并自行配置executablePath
截图时页面未完全加载就执行 screenshot()
直接调用 page.screenshot() 而不等待内容就绪，会导致截到白屏或缺元素。Pyppeteer 不像 Selenium 那样有隐式等待，必须显式控制时机。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 优先用
await page.waitForSelector('main')等关键选择器出现，比waitFor(2000)更可靠 - 对 SPA 页面，可监听网络空闲：
await page.waitForFunction("window.performance.getEntriesByType('navigation')[0]?.loadEventEnd > 0") - 截图前加
await page.evaluate('window.scrollTo(0, 0)')，避免因滚动位置导致顶部被裁 - 设置
fullPage=True参数才能截长图；否则只截当前视口，且默认无滚动行为
生成 PDF 时中文乱码或字体缺失
Pyppeteer 底层用的是 Chromium 的 PDF 导出能力，而默认 Chromium for Linux 不带中文字体，Windows/macOS 通常自带但路径可能未被识别，结果 PDF 中文显示为方块或空白。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- Linux 下需预装字体（如 Noto Sans CJK）并确认 Chromium 能读取：
sudo apt-get install fonts-noto-cjk，再启动时加args=['--font-render-hinting=none'] - PDF 生成前注入 CSS 强制指定字体：
await page.addStyleTag(content='body { font-family: "Noto Sans CJK SC", sans-serif; }') - 不要依赖
printToPDF的displayHeaderFooter，它对中文页眉页脚支持差；如需页眉，用 HTML +@media print模拟更可控 -
printToPDF不支持背景图、部分 CSS3 属性（如filter），导出前建议用page.emulateMedia('screen')预览效果
page.pdf() 返回空字节或文件损坏
常见于未 await 完整调用、或传入了非法选项（如 format='A5' 写成 'a5'）、或 PDF 输出路径所在目录不存在。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 必须
awaitpage.pdf()，它返回bytes，不是文件路径：pdf_bytes = await page.pdf(format='A4', printBackground=True) - 检查选项值是否符合 Chromium 文档：格式只能是
'Letter'/'A4'等大写字符串，margin必须是 dict，如{'top': '20px'} - 写入文件时确保目录存在：
os.makedirs(os.path.dirname(output_path), exist_ok=True) - 调试时先用
page.content()输出 HTML 到本地，用 Chrome 手动“另存为 PDF”对比，快速定位是渲染问题还是导出参数问题
page.pdf() 和 page.screenshot() 都是异步方法，但它们的完成不代表页面 DOM 已稳定——尤其动态渲染内容。别省掉 waitForSelector 或 waitForFunction 这一步。 
