中科院张老师去年给我这边的一个渠道团队做过一个内部工具，需求很简单：每天定时把运营后台的数据报表，渲染成一张漂亮的长图，推到工作群。当时第一个想法是后端把数据拼成HTML，然后用无头浏览器截图，Python生态里绕不开这种方式。项目落地跑通之后，其实不止能用于报表，商品分享卡片、网页预览图、邮件模板预览、社交平台分享图，凡是遇到“能不能把这段网页内容变成一张图”的需求，这套东西都能直接接上。
这里我把整个手搓过程完整拆一遍，包括技术选型、关键原理、可直接抄的代码、以及线上跑起来之后遇到的各种问题。如果你的需求只是临时截个图，可以直接用Playwright那个几行代码的版本；如果你要把它做成一个稳定的截图服务，重点是后半段的资源管理、等待策略和接口设计，这些才是决定你能不能在线上长期存活的关键。
1. 先搞清楚一个核心问题：为什么HTML转图片必须用无头浏览器
1.1 这个需求背后真正要解决的是什么
把HTML变成图片，说白了就是完成一次“渲染”。HTML本身只是一堆结构化的文本，浏览器拿到它之后，要经历解析DOM、构建CSSOM、排版布局、绘制图层这一整套流程，最终才能在屏幕上输出像素。如果我们绕过浏览器，用代码去模拟这个过程，会马上撞上一个问题：现代的CSS布局里，Flex、Grid、动画、字体渲染、Canvas，每一样单独拿出来都能让人写到手抽筋，更别提把它们全都实现一遍。
所以实际可选的方案只剩两条路：要么找一个本身就支持自行渲染HTML的库，要么让一个真正的浏览器帮我们渲染，然后截图。前者听起来轻巧，但可用的项目非常少，而且渲染效果基本停留在WebKit很早期的水平；后者就是我们说的无头浏览器方案，把一个完完整整的Chromium内核拉起来，但不开窗口，后台完成加载、布局、绘制，最后输出截图。选择后者，等于是把“网页长什么样”这件事完全交给浏览器内核去判断，我们只关心结果截图，省掉了一整个浏览器引擎的开发量。
类比一下，这就像你自己家厨房做不了烤鸭，但你可以直接请一位全聚德的师傅来家里，用他全套的手艺帮你烤一只，你只需要表达“要皮脆肉嫩”这个需求。无头浏览器就是这个师傅，HTML就是宰好的鸭子，截图就是成品。
1.2 技术选型：Playwright、Selenium、pyppeteer到底选哪个
确定了无头浏览器这个大方向之后，Python生态里具体可以选哪几个，我把实测过的情况列一下。
第一个是Selenium。老牌选手，功能全，兼容各种浏览器驱动，社区资料最多。但它的问题在于历史包袱重：API设计是几年前的风格，对现代浏览器特性的抽象不够直接，等元素、等请求、操作浏览器上下文这些动作，写起来繁琐，出错时定位问题也比较费劲。如果是做简单爬虫或自动测试，它完全够用；但如果你要把“加载页面→等待渲染→截图”这个流程做成高并发的服务，就会觉得它处处使不上劲。
第二个是pyppeteer。它是Node.js里Puppeteer的Python复刻版，用起来跟Puppeteer很像。但有个很现实的问题——维护不太活跃，而且它依赖asyncio，没有同步API，对很多不熟悉async的Python开发者来说，入门门槛偏高。当初我调研时发现它安装时会自己下载Chromium，如果网络不好或机器环境受限，这一部就能卡死。还容易遇到版本和浏览器内核版本不匹配的问题。
第三个是Playwright。微软开源的项目，支持Python、Java、C#、Node.js，API设计非常现代，而且核心优势是它把“自动等待”做得很聪明：locator定位元素时，页面元素还没出现会等待，网络空闲会等待，请求和响应都有拦截能力。配合BrowserContext做多标签多隔离的并发管理，效率非常高。安装也简单，pip install playwright后执行playwright install chromium，自动下载对应版本的浏览器内核，版本绑定关系清晰，基本不会遇到“内核和驱动对不上”这种经典痛点。
综合下来，我的选择很明确：要做一个稳定、可维护、能上线的HTML截图服务，直接锁定Playwright。不是说其他方案不能用，但如果你不想在底层细节上消耗太多精力，Playwright是性价比最高的那条路。下面的代码也都基于Playwright。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心原理：无头浏览器渲染的完整链路里到底有哪些坑
2.1 无头浏览器是怎么工作起来的
先看一个最基础的版本，感受一下无头浏览器的使用模型：
python复制from playwright.sync_api import sync_playwright
html_content = """
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
body { font-family: sans-serif; padding: 40px; }
h1 { color: #333; }
.card { background: #f5f5f5; border-radius: 12px; padding: 24px; }
</style>
</head>
<body>
<div class="card">
<h1>Hello HTML</h1>
<p>This is a test card.</p>
</div>
</body>
</html>
"""
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page()
page.set_content(html_content, wait_until="load")
page.screenshot(path="output.png", full_page=True)
browser.close()
这段代码里其实隐含了好几个关键动作：启动浏览器进程、新建一个页面对象、把HTML字符串塞给页面、等页面加载完成、截图、退出。如果你只需要在本地偶尔截个图，这一个函数就能解决问题，10行不到。
但请注意，这只是一个“能用”的demo，离“能上生产”还差得远。要理解差在哪，得先说清楚headless启动浏览器之后发生了什么。Chromium内核在无头模式下，依然会正常解析HTML、请求CSS、执行JS、加载图片字体，唯一和有头模式的区别是它不会把渲染结果输出到屏幕，而是直接渲染到一个内部的后备存储里。截图本质上就是从这个后备存储里把像素数据取出来，编码成PNG或JPEG。
这意味着，无头浏览器并不仅仅是“能打开网页”，它等同于一个完整可编程的Chromium。这让它具备了很大优势：任何你平时在浏览器里能看到的页面，无头模式都能看到一样的渲染结果。也正是因为如此，它背后要做的事情非常多，多到经常出现让人觉得“为什么这么慢”“为什么截图是白的”的各种问题。
2.2 页面加载与等待策略：截图白屏的罪魁祸首之一
很多人第一次用无头浏览器截图，最容易碰到的现象就是：截图出来了，但是一片空白或者只有半截页面。根因几乎都是等待策略没做好。
页面加载不完全，图片还没请求完就截图了；广告位渲染到一半截图了；异步请求数据还没回来截图了；页面里新插入的DOM元素还在动画中截图了。解决办法其实也不是一句“多等几秒”就行，而是要理解页面加载的各个阶段。
Playwright里，wait_until支持几个状态：
load表示onload事件触发，即基础DOM和资源加载完毕。domcontentloaded表示DOM解析完成，更快但更早。networkidle表示网络连接数在500ms内不再变化，通常意味着所有请求都发完了。commit则表示导航正准备响应，非常早期。
实际场景里，如果是纯静态HTML，用domcontentloaded和load没多大区别。但如果页面里有图表库、异步接口，load往往不够，因为很多图表库是在DOM加载完才开始发数据请求的，等它画完图还需要额外时间。这时候用networkidle相对稳妥。
但networkidle也有坑，如果页面里有一个持续轮询的接口，比如每3秒刷新一次心跳数据，那网络永远不会“空闲”，networkidle就会一直等不到，最终卡死到超时。所以更可靠的做法是：先用wait_until="load"，然后page.wait_for_selector("某个关键元素")等待业务上真正代表渲染完成的元素出现，或者page.wait_for_timeout(500)再固定多等半秒，给动画和字体渲染留出时间。
实操时的经验值：我在做数据卡片时，页面里有一个ECharts图表，数据通过axios异步请求加载，图表渲染完成后会往容器里插入一个canvas。我的等待策略就是：
page.wait_for_selector("div.chart-container canvas", timeout=10000)，配合page.wait_for_timeout(300)让动画从第一帧进入静止状态再截图。这样既稳定，又不会因为接口慢而早早截图。
2.3 视口尺寸、deviceScaleFactor和最终图片清晰度的关系
截图清晰度是很多人忽视但非常重要的参数。同样一张网页，截出来的图有的发虚，有的锐利，区别就在于deviceScaleFactor。
简单解释一下：deviceScaleFactor在浏览器里模拟的是设备像素比，也就是DPR（Device Pixel Ratio）。手机屏幕DPR通常是2或3，所以同样是CSS里的100px宽，物理像素是200或300。在无头截图场景里，你如果想输出一张2倍图，给print媒体准备高清分享卡片，就要把deviceScaleFactor设为2。
看这个例子：
python复制browser = p.chromium.launch(headless=True)
context = browser.new_context(
viewport={"width": 1280, "height": 720},
device_scale_factor=2
)
page = context.new_page()
page.set_content(html_content)
page.screenshot(path="output@2x.png", full_page=True)
当你把device_scale_factor设成2之后，浏览器渲染的物理分辨率是CSS分辨率的2倍，输出的截图会更清晰，但同时渲染开销也会增加，CPU占用和耗时都会上浮。所以实践中要平衡：如果只是网页预览，1倍就够；如果是给公众号文章封面、分享海报这种要在手机上高清展示的图，必须用2倍甚至3倍。
还有一个容易踩的点是viewport和full_page的关系。viewport决定的是“一个屏幕上能看到多少内容”，而full_page截图会把整个文档的完整高度都截下来，两者不是一回事。如果只截首屏，直接screenshot不传full_page；如果截整页长图，必须传full_page=True。但要注意，full_page模式下，页面上如果有position: sticky或fixed的元素，会导致同一元素在长图的多个位置重复出现，这个需要在写页面样式时就想清楚。
3. 从零手搓一个能用的HTML截图服务
3.1 服务整体结构与目录规划
先聊聊项目结构。做服务化，你肯定不能每次都重新启动浏览器，那会慢到怀疑人生，所以设计上需要一个“服务常驻”的模型。我的结构大致如下：
code复制screenshot-service/
├── app.py # FastAPI入口
├── core/
│ ├── browser.py # 浏览器实例管理
│ ├── capture.py # 截图核心逻辑
│ └── templates.py # Jinja2模板渲染
├── templates/
│ ├── report_card.html # 报表卡片模板
│ └── share_img.html # 分享图模板
├── requirements.txt
└── static/
└── fonts/ # 中文字体
浏览器实例管理放在单独模块里，原因很简单：Chromium进程本身是有开销的，每个请求都启动一个浏览器，再关闭，HTTP接口平均响应时间会拉到每秒只能处理一到两个请求，完全没法用。更好的做法是启动一次浏览器，然后让请求复用它里的标签页。
3.2 浏览器实例管理的封装思路
下面这段代码是我线上在用的浏览器管理模块，做了基本的上下文复用：
python复制# core/browser.py
from playwright.sync_api import sync_playwright
class BrowserManager:
def __init__(self, headless=True, device_scale_factor=2):
self._playwright = None
self._browser = None
self.headless = headless
self.device_scale_factor = device_scale_factor
def start(self):
if self._playwright is None:
self._playwright = sync_playwright().start()
if self._browser is None:
self._browser = self._playwright.chromium.launch(
headless=self.headless,
args=["--no-sandbox", "--disable-dev-shm-usage"]
)
def get_context(self):
if self._browser is None:
self.start()
return self._browser.new_context(
viewport={"width": 1280, "height": 720},
device_scale_factor=self.device_scale_factor
)
def close(self):
if self._browser:
self._browser.close()
if self._playwright:
self._playwright.stop()
注意这里设置的两个Chromium启动参数，属于线上必选项。--no-sandbox是因为很多部署环境是Docker容器，默认的sandbox机制在这种容器里不兼容；--disable-dev-shm-usage则是解决容器里/dev/shm空间太小导致浏览器渲染失败的问题。如果你不在容器里跑，这两个参数也可以不加，但加上之后在容器化部署时会省很多麻烦。
BrowserContext在这里扮演的角色我很想强调一下：它类似于一个独立的浏览器会话，每个context之间Cookie、LocalStorage完全隔离。你可以为每个请求创建一个新的context，用完即弃，既干净又不影响其他并发请求。同一个浏览器进程里开多个context，开销比重复启动浏览器小得多，实测在单机8核配置下，稳定支撑每秒5-8个截图请求是没问题的。
3.3 核心截图逻辑：从HTML字符串到图片文件
有了浏览器管理，接下来就是截图核心模块。我需要考虑几种输入类型：直接传HTML字符串、传URL、传模板名称加数据。统一抽象成一种：先把所有输入归一化成完整的HTML文档，再交给截图函数处理。
python复制# core/capture.py
from urllib.parse import urlparse
def normalize_html(source: dict) -> str:
if source.get("html"):
return source["html"]
if source.get("template") and source.get("data"):
return render_template(source["template"], source["data"])
raise ValueError("source must contain html or template+data")
def capture_card(source: dict, output_path: str, manager: BrowserManager,
width=1280, wait_selector=None):
html = normalize_html(source)
context = manager.get_context()
try:
page = context.new_page()
# 加载内容
page.set_content(html, wait_until="load")
# 如果页面里有异步渲染，等待关键元素
if wait_selector:
page.wait_for_selector(wait_selector, timeout=10000)
# 再固定等一小段，让动画和字体稳定
page.wait_for_timeout(300)
page.screenshot(path=output_path, full_page=True)
finally:
context.close()
这段逻辑本身不复杂，核心思想就是先规整HTML，再加载、等待、截图。但真正要上生产，还有几个细节要做：
一是输入校验。如果接口允许传URL，必须做SSRF防护，限制不能访问内网IP、metadata地址等，不然别人可以拿你的服务去探测内网，这个问题很严重。我在代码里做了一层URL白名单域名的校验，非白名单域名直接拒绝。
二是超时控制。Playwright的默认超时是30秒，但线上服务如果对方页面一直不返回，会彻底拖垮你的线程池。所以我在每个等待调用里都显式传了timeout，并且整个截图流程包了一层总超时，超时就快速失败。
三是失败重试。有些第三方页面偶尔抖动，网络抖动导致加载失败，一次重试往往就成功了。我会在服务层做一层简单的重试逻辑，最多重试两次。
3.4 模板渲染与动态数据填充
单纯截HTML，功能还是太弱。实际项目中90%的需求是：给定一份JSON数据，把它渲染成一张好看的图片。靠手写拼接HTML字符串很痛苦，用Jinja2模板就舒服了。
假设我们要做一张销售数据卡片，模板大致长这样：
html复制<!-- templates/report_card.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<style>
body { margin: 0; padding: 40px; background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%); font-family: "PingFang SC", "Microsoft YaHei", sans-serif; }
.card { background: rgba(255, 255, 255, 0.95); border-radius: 20px; padding: 40px; max-width: 1000px; }
.title { font-size: 36px; color: #333; margin: 0 0 24px; }
.stat-row { display: flex; gap: 24px; margin-bottom: 24px; }
.stat-box { flex: 1; background: #f7f7fb; border-radius: 12px; padding: 20px; }
.stat-label { font-size: 16px; color: #888; }
.stat-value { font-size: 40px; font-weight: bold; color: #1a1a2e; margin-top: 8px; }
.footer { font-size: 14px; color: #aaa; text-align: center; margin-top: 32px; }
</style>
</head>
<body>
<div class="card">
<h1 class="title">{{ title }}</h1>
<div class="stat-row">
{% for item in stats %}
<div class="stat-box">
<div class="stat-label">{{ item.label }}</div>
<div class="stat-value">{{ item.value }}</div>
</div>
{% endfor %}
</div>
<div class="footer">生成时间：{{ generated_at }}</div>
</div>
</body>
</html>
渲染端代码也很简单：
python复制# core/templates.py
from jinja2 import Environment, FileSystemLoader
env = Environment(loader=FileSystemLoader("templates"))
def render_template(template_name: str, data: dict) -> str:
template = env.get_template(template_name)
return template.render(**data)
这样业务端调用接口时，只需要提交模板名称和JSON数据，后端负责渲染成HTML，再交给无头浏览器截图。这套逻辑把“页面设计”和“服务开发”解耦了：运营同学调整模板样式，开发同学完全不用动代码。
这里有一个重要提示：templates目录一定不能放在线上服务可写的路径下，防止模板注入和篡改。模板本身也不应该接受用户直接上传的内容，否则等于开放了一个RCE口子。合理的做法是模板预先定义好，接口只接收模板名称+业务数据，模板名称走白名单校验。
3.5 用FastAPI把截图能力封装成HTTP接口
核心逻辑就绪以后，封装HTTP接口是水到渠成的事。
python复制# app.py
from fastapi import FastAPI, HTTPException, Response
from pydantic import BaseModel, Field
import io, time, base64
from core.browser import BrowserManager
from core.capture import capture_card
app = FastAPI()
manager = BrowserManager()
manager.start()
class ScreenshotRequest(BaseModel):
source: dict = Field(..., description="source.html 或 source.template + source.data")
wait_selector: str = None
width: int = 1280
return_base64: bool = False
@app.post("/screenshot")
def screenshot(req: ScreenshotRequest):
start_ts = time.time()
output_path = f"/tmp/shot_{int(start_ts * 1000)}.png"
try:
capture_card(req.source, output_path, manager, req.width, req.wait_selector)
if req.return_base64:
with open(output_path, "rb") as f:
img_bytes = f.read()
b64_data = base64.b64encode(img_bytes).decode("utf-8")
return {"code": 0, "data": b64_data, "elapsed_ms": int((time.time() - start_ts) * 1000)}
return Response(content=open(output_path, "rb").read(), media_type="image/png")
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
finally:
if os.path.exists(output_path):
os.remove(output_path)
这里我留了一个return_base64参数，两种返回方式各有用处：如果调用方是另一个后端服务，直接拿文件流更高效；如果是前端页面调用且需要做图片预览，base64更方便。实际运行中大部分调用方还是选择了文件流，因为base64体积会多出30%左右，除非是为了避免跨域下载问题，否则没必要。
接口层还需要补充一个限流逻辑，防止有人拿你的截图上线程池轰炸。我用的是简单的内存限流：每IP每分钟最多调用30次，超过直接429。再往后可以用Redis做分布式限流，但单机服务内存限流已经够用。
4. 线上跑起来以后，那些必须面对的问题
4.1 并发场景下的浏览器资源管理
截图服务最大的性能瓶颈不是CPU计算，而是内存。每个Chromium进程默认开多个线程，每个标签页都需要加载资源、执行JS，内存占用轻松上GB级别。所以并发管理上，我采取的策略是“浏览器单实例+多上下文”。
我的服务启动时只启动一个Chromium进程，每个请求到来时新开一个BrowserContext和一个Page，用完关闭context。因为同一浏览器进程内的context之间共享内核资源，开新context的开销比新开浏览器进程小一个数量级。实测在8核16G的云主机上，同时并发20个截图请求，内存峰值控制在4GB以内，每个请求平均耗时2-4秒。如果换一个新的浏览器进程来处理每个请求，内存会直接爆炸。
但这样做有一个副作用：某个页面如果在浏览器内部执行了有问题的JS，比如死循环、无限弹窗或者内存泄漏，可能会影响整个浏览器进程的稳定性。所以我的服务里加了看门狗机制：如果浏览器进程在5分钟内出现异常崩溃，服务会自动重新启动一个浏览器实例。同时，每个context也设置了超时和资源回收逻辑，避免僵尸页面堆积。
4.2 中文字体缺失怎么办
部署在Linux服务器上，最经典的问题就是中文字体全部变成方块或乱码。根本原因是系统里没有安装中文字体，Chromium渲染时找不到合适的字体，只能回退到默认字体，而默认字体又不支持中文。
排查方法很简单：
bash复制fc-list :lang=zh
如果输出为空，说明系统里没有中文字体。解决办法是安装字体包，Debian/Ubuntu系可以用：
bash复制apt-get install -y fonts-noto-cjk
或者直接把Windows或macOS上常用的中文字体文件放到项目的static/fonts目录下，然后在HTML里用@font-face引用。我推荐第二种方式，因为对服务来说字体文件随项目走，部署到任何机器效果都一致，不受系统环境影响。
@font-face的写法大致如下：
css复制@font-face {
font-family: "CustomChinese";
src: url("/static/fonts/PingFang-SC-Medium.ttf") format("truetype");
font-weight: 500;
}
不过我实测下来，直接引用System Font Stack更省事：
css复制body { font-family: -apple-system, "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif; }
这样系统里有哪个就用哪个，没有Noto也没关系，只要安装了字体，渲染就能正常。还有一个容易被忽略的问题：字体加载时机。如果用web font，页面load事件可能已经触发了，但字体文件还没下载解析完成，截图出来的字体就是默认字体。这种情况可以加一个document.fonts.ready等待。Playwright里可以用page.evaluate("document.fonts.ready")或者直接等一个关键节点，我在代码里用page.evaluate("document.fonts.ready")确保字体加载完再截图，实测这个方案很稳。
4.3 页面懒加载资源的坑
现在网页普遍用懒加载，图片在滚动到可视区域之前不会请求。full_page截图时，如果页面高度远超视口高度，底部那些图片根本不会被触发加载，截图里就是空的。
解决方案是在截图前先强制滚动页面，把每个位置都“踩”一遍，触发懒加载。具体做法是用JavaScript在页面里循环滚动到不同的高度，每次停留几百毫秒，让浏览器有时间加载图片和渲染。
python复制page.evaluate("""
async () => {
const height = document.body.scrollHeight;
const step = 200;
for (let y = 0; y < height; y += step) {
window.scrollTo(0, y);
await new Promise(r => setTimeout(r, 50));
}
window.scrollTo(0, 0);
}
""")
等待时间不要太长，通常页面总高度几千像素，滚动一遍也就是一两秒。切记最后要把滚动位置恢复到顶部，不然截图出来是从页面中间开始的。我在实际项目里遇到过好多趟这坑的，最后总结为：凡是full_page截图，优先检查懒加载和滚动位置，否则截图出来永远差半截。
4.4 常见问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 截图为空白 | 页面加载尚未完成 | 使用wait_for_selector等待关键元素，或等待networkidle |
| 中文显示方块 | Linux系统缺少中文字体 | 安装fonts-noto-cjk，或项目字体目录引入ttf |
| 长图底部未加载 | 页面懒加载导致 | 截图前滚动页面触发加载 |
| 页面渲染一半 | 有动画或图表异步绘制 | 增加固定延时，等待canvas元素出现 |
| 浏览器进程崩溃 | 内存不足或沙箱不兼容 | 启动参数加--no-sandbox和--disable-dev-shm-usage |
| 接口响应超时 | 目标页面加载过慢 | 设置总超时机制，快速失败后重试一次 |
| fixed元素在长图中重复 | full_page截图原理导致 | 页面样式改为absolute定位，或截单屏 |
| 输出图片模糊 | DPR默认1 | 创建context时device_scale_factor=2 |
这张表基本覆盖了我实践中遇到的高频问题。遇到问题第一步先判断是页面加载问题、字体问题还是浏览器环境问题，用排除法定位。排查的时候，建议先把页面头图或关键位置单独截出来看看，再用page.content()确认HTML是否完整注入，再逐步缩小范围。
5. 再聊聊Service层面的落地细节
5.1 缓存策略：不是所有页面都需要重新渲染
很多业务场景里，同一份HTML模板配同一份数据，生成出来的图片是确定性的，重复截图只会浪费资源。我的做法是给模板+数据生成一个哈希值，作为缓存key，首次渲染后把截图存到对象存储或本地磁盘，后续请求直接返回缓存文件。
缓存逻辑大致如下：
python复制import hashlib, json, os
def cache_key(template, data):
payload = json.dumps({"template": template, "data": data}, ensure_ascii=False, sort_keys=True)
return hashlib.md5(payload.encode("utf-8")).hexdigest()
def get_cached_path(key):
path = f"/data/screenshot-cache/{key}.png"
return path if os.path.exists(path) else None
这里要注意，缓存要慎用在数据经常变化的场景。比如报表数据每小时更新一次，那缓存时间就要设置成59分钟，而不是无限期。我的做法是缓存文件名里带上时间分片，比如按小时分目录，这样过期时间到了以后，新请求自动落入新目录，不需要主动清理旧文件。
5.2 定时任务的接入方式
工具上线之后，最常用的场景是定时生成日报图片发到群里。我这边是直接写了一个Python脚本，用APScheduler调度，每天上午9点15分调用截图接口，拉取前一天的数据，生成图片，然后调用群机器人webhook发图。整个过程没有人工参与。
脚本里有一个很关键的小设计：生成图片之后，先检查图片大小是否合理。如果一张图片小于10KB，大概率是截了张空图，这个就不发送，而是发一条警告消息给值班同学。这个“异常检测”看着简单，但实际省了很多麻烦，避免了群里出现一批白图或者缺数据的图，影响观感。
5.3 服务监控与告警
线上服务如果不会报警，那等于没做监控。我接的是Prometheus + Grafana这套，暴露了几个基础指标：请求总数、截图成功数、失败数、平均耗时、浏览器进程存活状态。告警规则就两条：最近5分钟成功率低于98%，发告警；浏览器进程挂了，发告警。别看指标少，线上出了问题基本都能第一时间发现。
有一个细节是在服务启动的时候，我特意加了一个启动检查接口/healthz，它做两件事：检查浏览器进程状态，再真正执行一次最小截图为1x1像素的HTML，确保整条链路是通的。定时任务每次调用前也会先ping一下这个接口，链路挂了就不发图。
6. 写在最后的个人体会
这个服务从写完第一版到稳定运行，我花的时间主要不是在截图代码本身，而是在各种边缘情况上：字体、懒加载、并发、超时、缓存失效、安全校验。如果你想在自己的项目里也用这套方案，我给的建议是：先跑通最基础的核心函数，然后立刻面对所有“会出错”的细节，别想着一步到位。
有几句话确实是踩过坑之后才真正有感触的：
第一，无头浏览器不是银弹。它确实能解决HTML渲染成图片的问题，但代价是系统复杂度、内存开销、进程稳定性方面都需要你付出额外精力。如果只是截一个很简单的静态HTML，也许用轻量方案就够，不必上无头浏览器。
第二，等待策略永远是你最应该打磨的部分。截图结果的成败，有一半取决于“什么时候截”这个问题的答案。我的经验是对纯静态页面直接load，对数据动态加载页面用wait_for_selector，对图表类动画页面在这基础上再加延时。
第三，服务化之后，一切都要以“能用、可维护、可监控”为目标。截图这件事看起来简单，但真正服务化以后，你会遇到并发、缓存、安全、监控一整套工程问题。处理好了，这个服务会非常省心；处理不好，它可能会变成一天到晚被报警轰炸的定时炸弹。
最后分享一个不用写代码的小技巧：如果你只是临时想截一张网页截图，不一定要起服务。直接用Playwright的CLI就能完成：
bash复制playwright screenshot --full-page --device-scale-factor=2 https://example.com output.png
这个命令我经常用来做技术验证，先确认页面在无头浏览器里的表现，再决定是否把逻辑集成到服务里。用它快速判断问题源头，效率会高很多。