Playwright 网页截图模糊排查与超高清渲染 (Playwright High-DPI Screenshot)

1. 核心目标 (Goal)

在使用 Playwright（Python / Node.js）将 HTML 网页或数据报表渲染并导出为长图（如海报、价格看板、分析报告）时，解决导出图片在手机端缩放、高分屏或社交软件中查看时出现的文字发虚、锯齿发蒙、分辨率低（Low Resolution）的问题，生成视网膜级别（Retina Display, 2x / 3x）的超清位图。

2. 根因分析 (Root Cause Analysis)

2.1 默认设备像素比缺失 (Device Scale Factor Omission)

Playwright 创建浏览器上下文（Browser Context）时，默认的设备像素比 device_scale_factor 为 1.0（标准 96 DPI）。
在现代高分辨率屏幕（如 Mac Retina 为 2x、高端手机为 3x）下，1.0 导出的位图放大会直接暴露像素插值模糊，字体抗锯齿呈现低清马赛克。

2.2 视口宽度与容器宽度不匹配导致无效黑边 (Viewport-Container Mismatch)

• 典型误区：在 browser.new_context(viewport={"width": 1800, "height": 1200}) 中设置了 1800px 视口，但 HTML 内部容器限制了 max-width: 1240px; margin: 0 auto;。
• 后果：左右两侧产生了大量无意义的空白色块或黑边，整张长图在移动端缩略图展示时会被动缩放到极小比例，用户需手动捏合放大，视觉体验粗糙。

3. 完整解决方案与实施步骤 (Implementation Steps)

步骤 1：设置 device_scale_factor 为 2.0 或 3.0

在调用 browser.new_context() 时显式声明 device_scale_factor：

context = await browser.new_context(
    ignore_https_errors=True,
    viewport={"width": 1200, "height": 800},
    device_scale_factor=2.0,  # 关键：开启 2x 视网膜渲染，导出为 2400px 物理像素宽度
)

步骤 2：CSS 级抗锯齿与字体平滑优化

在待渲染的 HTML 的 <style> 中注入抗锯齿声明与等宽数字对齐：

* {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: optimizeLegibility;
}

/* 价格与数字列强制采用等宽数字，避免抖动 */
.price-value {
  font-variant-numeric: tabular-nums;
  font-feature-settings: "tnum";
}

步骤 3：消除无意义边距并约束视口 (Zero-Waste Layout)

确保 HTML 顶层容器宽度与 Playwright 视口宽度精准契合，例如视口设为 1200px，页面主容器设为 max-width: 1180px; margin: 0 auto; padding: 0 24px;，保证生成的图片充满画面且留白呼吸感适度。

步骤 4：二维码等内嵌资源超采样生成 (Supersampling)

使用 qrcode 库生成 Data URI 时，将 box_size 适当调大（如 box_size=12），生成的原始图像分辨率在 400px 以上，再通过 CSS 缩小至 140px 显示，实现高精超采样，手机扫码秒级识别。

4. 验证方式 (Validation Method)

使用 Pillow (PIL.Image) 检查导出文件的像素分辨率与色彩空间：

from PIL import Image

im = Image.open("prices.png")
print("Dimensions:", im.size)  # 预期: (2400, H)，物理像素为 CSS 宽度的 2 倍

5. 适用边界与避坑提醒 (Pitfalls & Boundaries)

1. 内存与截图耗时：长页面（高度 > 8000px）若开启 scale=3.0，显存与内存消耗会剧增，建议绝大多数线上长图看板锁定 scale=2.0。
2. 网络等待策略：页面包含外部字体或动态图片时，必须使用 await page.goto(url, wait_until="networkidle") 或 wait_until="load"，防止字体未加载完成即被截图导致回退为系统默认宋体/黑体。

6. Linux 无头服务器端部署与浏览器启动排查 (Headless Linux Server Setup)

6.1 症状与静默吞错排查

当插件或服务报错 未能启动 Chromium 实例进行海报截图 或 BrowserType.launch: Executable doesn't exist 时，通常是因为业务代码捕获了异常并尝试了 chrome / msedge / chromium 通道，最后吞掉异常统一抛出外层错误，掩盖了底层根因。

直接进入运行环境测试真实报错：

/path/to/.venv/bin/python -c "import asyncio; from playwright.async_api import async_playwright; asyncio.run(async_playwright().start().chromium.launch(headless=True))"

6.2 根因分析

1. 浏览器二进制缺失 (Missing Executables)：~/.cache/ms-playwright/ 目录为空，Playwright 未下载对应的 Chromium / Chrome Headless Shell。
2. 系统动态链接库缺失 (Missing Shared Libraries)：Ubuntu Server 等精简环境缺少 libcups2t64、libdrm2、libdrm-amdgpu1、libdrm-intel1 等图形支持库。
3. 中文字体缺失 (Missing Chinese Fonts)：若未安装 fonts-wqy-zenhei 等中文字体包，截图内的中文字符会回退为乱码方块（Tofu, □□□）。

6.3 完整安装与部署步骤

以目标服务运行用户（如 ubuntu）操作：

1. 安装系统底层依赖与中文字体库（需 sudo）：

   sudo DEBIAN_FRONTEND=noninteractive /path/to/.venv/bin/python -m playwright install-deps chromium

2. 配置国内镜像源下载 Chromium 浏览器内核：

   PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/ /path/to/.venv/bin/python -m playwright install chromium

3. 端到端渲染验证：

   import asyncio
   from playwright.async_api import async_playwright
   
   async def main():
    async with async_playwright() as pw:
        b = await pw.chromium.launch(
            headless=True,
            args=['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--disable-gpu']
        )
        ctx = await b.new_context(viewport={'width': 1020, 'height': 800}, device_scale_factor=2)
        page = await ctx.new_page()
        await page.set_content('<html><body><h1>海报渲染测试</h1></body></html>')
        await page.screenshot(path='/tmp/test_poster.png', full_page=True)
        await b.close()
        print('Screenshot successful!')
   
   asyncio.run(main())

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/Python