自建网页截图与OG图片生成API：基于Playwright的无头浏览器实战

在做内容分享类业务时很多团队都会遇到这样的需求把某个网页变成一张清晰截图或者为文章动态生成一张适合发到微信、Twitter、Facebook 的分享卡片图。市面上的网页截图 API 和 OG Image API 并不少但按调用量付费、返回格式固定、定制能力有限数据敏感一点的项目还不敢直接调用外部服务。这个项目Another Webpage Screenshot and OG Image Generation API的定位就是“自建一套”自己控制无头浏览器自己定义卡片样式自己决定鉴权和缓存策略。本文会从原理讲起完整搭建一个基于 Playwright Express 的截图与 OG 图片生成服务并覆盖 Docker 部署、并发控制、常见报错排查和工程化建议。如果你已经在使用 Puppeteer、Playwright 这类无头浏览器可以直接跳到第 4 节看完整实现如果是第一次接触建议从头按顺序阅读。1. 为什么需要自建网页截图与 OG 图片生成 API1.1 网页截图 API 能做什么网页截图 API 的核心能力很简单传入一个 URL服务端通过无头浏览器加载页面等待资源渲染完成后截取整页或视口区域再以图片二进制形式返回给调用方。它在业务中常见的用途包括生成网页预览缩略图比如分享链接时展示目标网站的视觉快照。定时巡检页面样式记录线上页面是否出现布局错乱。生成周报、日报中的可视化图表图片将内部报表页面转成图片后贴到文档。为移动端 H5 制作分享长图把活动页、邀请页截成一张便于传播的图片。作为 Web 自动化测试的辅助能力将失败用例的关键页面截图留存证据。这些场景有一个共同特点页面是在浏览器里渲染的动态内容不是简单抓一下 HTML 就能得到。服务端获取图片必须依赖一个“真实浏览器内核”也就是无头浏览器。无头浏览器没有界面窗口但拥有完整的渲染、脚本执行和网络请求能力因此可以拿到和用户看到一模一样的页面。1.2 OG Image 到底是什么OG Image 中的 OG 是 Open Graph 协议的缩写。它最早由 Facebook 提出后来被 Twitter、微信、LinkedIn 等平台广泛支持。它的作用是在网页 URL 被分享到社交平台时告诉平台“你应该用哪张图、哪个标题、哪段描述来展示这个链接”。我们平时在群里看到带大图的链接卡片本质就是平台后台请求了网页的 HTML读取meta propertyog:image等标签后渲染出来的结果。一个标准的 Open Graph 标签集合如下meta propertyog:title content从零搭建网页截图与 OG 图片生成 API / meta propertyog:description content基于 Playwright 的无头浏览器截图服务实战 / meta propertyog:image contenthttps://example.com/og/cover.png / meta propertyog:type contentarticle / meta propertyog:url contenthttps://example.com/post/1001 / meta nametwitter:card contentsummary_large_image /其中og:image是分享卡片的核心素材推荐尺寸是 1200×630 像素宽高比约为 1.91:1。很多内容平台在生成分享卡片时会压缩图片所以图片内文字不能太靠边缘重要信息应当集中在中部区域。动态 OG Image 是指根据每篇文章的标题、描述、作者、分类等元数据实时渲染出一张 1200×630 的图片。相比手工设计一张通用封面图动态生成能做到“每篇文章一张专属封面”而且不需要设计师介入整个流程可以完全自动化。1.3 自建 API 的优势与技术选型对比自建而不是采购第三方 SaaS主要考虑三点一是成本无头浏览器服务按调用量计费时量大之后费用并不低二是定制第三方服务往往只能提供有限模板无法满足企业内部的视觉规范三是数据安全内网报表、未发布内容如果经过外部截图服务会带来泄露风险。在技术选型上目前主流方案大致有三类方案原理优点缺点Playwright / Puppeteer 无头浏览器启动 Chromium加载页面后截图支持复杂布局、完整 CSS 渲染内存占用高启动有一定开销SVG 转 PNG先用代码画出 SVG再用 sharp/resvg 转换轻量快速适合纯版式卡片对复杂排版支持有限Canvas 服务端绘制node-canvas 等库直接绘制位图可控性强无浏览器依赖文字换行、字体适配需要自己处理对于“网页截图 简单 OG 卡片”这种组合需求无头浏览器是最均衡的方案。同一个浏览器实例既能加载任意网页截图又能渲染自己写的 HTML 模板来生成 OG 图代码路径统一维护成本低。本项目采用 Playwright原因是它的现代 API 设计、自动等待机制和跨浏览器支持都更友好。2. 环境准备与项目结构设计2.1 运行环境与依赖说明搭建这个项目需要以下基础环境操作系统macOS、Linux 或 Windows 均可生产环境推荐 Debian/Ubuntu 系 Linux。Node.js建议使用 16 及以上版本。版本需要根据你的项目实际情况调整文章示例重点演示配置思路。包管理器npm 或 yarn本文使用 npm。浏览器内核Playwright 需要单独下载 Chromium不会自动复用系统浏览器。核心依赖只有两个npm install express playwrightExpress 用来提供 REST APIPlaywright 用来驱动 Chromium。项目本身不依赖数据库缓存可以先用文件系统生产环境可以替换为 Redis 或对象存储。2.2 项目目录结构为了让代码职责清晰我们按模块拆分项目screenshot-og-api/ ├── package.json ├── .env.example ├── Dockerfile ├── docker-compose.yml ├── src/ │ ├── server.js │ ├── browser.js │ ├── limiter.js │ ├── auth.js │ ├── screenshot.js │ ├── og-image.js │ └── templates.jsserver.jsHTTP 服务入口定义路由、鉴权、并发控制。browser.js管理全局浏览器实例避免每个请求都重新启动 Chromium。limiter.js简单的并发限制器防止无头浏览器占用过多内存。auth.js接口鉴权中间件。screenshot.js网页截图核心逻辑和处理函数。og-image.jsOG 图片生成核心逻辑和处理函数。templates.jsOG 图片的 HTML/CSS 模板。2.3 初始化 Node 项目创建目录并初始化mkdir screenshot-og-api cd screenshot-og-api npm init -ypackage.json中我们需要声明启动脚本和安装脚本。依赖版本以你安装时的最新稳定版为准下面给出示例{ name: screenshot-og-api, version: 1.0.0, description: Webpage Screenshot and OG Image Generation API, main: src/server.js, scripts: { start: node src/server.js, install:browser: playwright install chromium }, dependencies: { express: ^4.18.2, playwright: ^1.42.0 } }安装依赖并下载 Chromiumnpm install npx playwright install chromium这里要提醒一点如果服务器网络环境对下载安装包有限制npx playwright install chromium可能会失败。此时可以先执行npx playwright install-deps chromium安装系统依赖再单独下载浏览器核心或者配置 Playwright 的镜像源。3. 核心原理拆解3.1 无头浏览器的截图流程无头浏览器截图看起来只是“打开页面拍张照”但实际流程中每一步都值得关注启动浏览器实例chromium.launch()。这一步开销最大因此生产环境应当复用一个全局实例而不是每个请求都重新启动。创建上下文browser.newContext()。BrowserContext 相当于一个独立的浏览器会话cookie、缓存、localStorage 相互隔离适合作为每个请求的最小隔离单位。打开新页面context.newPage()。跳转 URLpage.goto(url, { waitUntil: networkidle })。networkidle表示页面在 500ms 内没有任何网络请求后认为加载完成。这个策略比load更可靠可以等到大部分异步接口返回。截图page.screenshot()。释放资源context.close()。页面和上下文必须释放否则长时间运行后内存会持续上涨。这段流程中waitUntil的选择决定了截图成功率。对于接口较慢、包含轮询请求的页面networkidle可能一直等不到空闲此时可以退化为load再加固定延时。更精细的做法是监听页面上的关键元素出现后再截图。3.2 OG 图片的尺寸与渲染模板社交平台对 OG 图的尺寸有强约束。1200×630 是事实标准Twitter 的summary_large_image也推荐这个尺寸。为什么不是 800×800 这种正方形因为信息流卡片在多数平台上都是横向排版宽图能占据更大的视觉区域同时不会被裁剪得太多。用无头浏览器生成 OG 图的核心思路是把卡片设计成一张 1200×630 的 HTML 页面然后让 Chromium 按精确视口尺寸打开并截图。这种做法的好处是可以用 CSS 完成所有排版渐变、圆角、文字截断都很容易实现。相比用 SVG 手写坐标CSS 的调试成本和可维护性都更好。需要注意的细节是给 Chromium 的视口必须精确设置成 1200×630否则截图比例不对。另外字体渲染受操作系统影响生产环境必须预装中文字体这个在 6.2 节会展开说明。3.3 REST API 接口设计本项目的 API 设计遵循 RESTful 风格只暴露两个核心接口方法路径功能请求体关键参数POST/api/screenshot截取指定网页url, width, height, fullPage, format, timeoutPOST/api/og-image生成自定义 OG 卡片title, description, siteName, theme, accentGET/health健康检查无接口都用 POST因为请求体是结构化 JSON比 query string 更适合传递截图参数。返回的不是 JSON而是图片二进制Content-Type设为image/png或image/jpeg。这样调用方直接把响应体当作图片文件保存即可前端也可以用img src接口地址直接预览。考虑到权限两个业务接口统一挂在/api前缀下由鉴权中间件统一保护。实际部署时还可以把写操作改为异步任务调用方提交任务后立即拿到任务 ID服务端生成完成后通过 Webhook 通知。这个优化适合生成图片耗时长的场景但会让代码复杂度明显上升文章先把同步方案做完整。4. 完整实战实现截图与 OG 图接口4.1 浏览器实例管理与并发控制浏览器实例是整个服务的核心资源。一个全局 Chromium 实例可以服务多个请求每个请求通过 BrowserContext 获得独立会话。下面是browser.js的实现// 文件路径src/browser.js const { chromium } require(playwright); let browserPromise null; function getBrowser() { if (!browserPromise) { browserPromise chromium.launch({ headless: true, args: [ --no-sandbox, --disable-setuid-sandbox, --disable-dev-shm-usage ] }); } return browserPromise; } async function closeBrowser() { if (browserPromise) { const browser await browserPromise; await browser.close(); browserPromise null; } } module.exports { getBrowser, closeBrowser };--no-sandbox在容器环境通常是必须的否则 Chromium 会因沙箱权限不足拒绝启动。生产环境如果对安全要求较高可以通过单独的用户命名空间或更细粒度的 seccomp 配置来替代直接关闭沙箱。无头浏览器属于“吃内存大户”并发太高会导致 OOM。我们需要一个简单的并发限制器。这里实现一个基于 Promise 的信号量// 文件路径src/limiter.js class ConcurrencyLimiter { constructor(max 5) { this.max max; this.running 0; this.queue []; } async run(task) { if (this.running this.max) { await new Promise((resolve) this.queue.push(resolve)); } this.running; try { return await task(); } finally { this.running--; const next this.queue.shift(); if (next) next(); } } } module.exports { ConcurrencyLimiter };这个限制器允许我们同时在页面加载阶段最多运行 5 个任务剩下的请求排队等待。并发数可以通过环境变量调整内存较小的机器建议控制在 3 以内内存充足的机器可以适度提高到 8 到 10。4.2 实现网页截图接口截图模块需要处理 URL 合法性校验、页面加载、滚动触发懒加载、最终截图几个环节。完整代码如下// 文件路径src/screenshot.js const { getBrowser } require(./browser); function validateUrl(rawUrl) { if (typeof rawUrl ! string || rawUrl.length 0) { return null; } let parsed; try { parsed new URL(rawUrl); } catch (_) { return null; } if (parsed.protocol ! http: parsed.protocol ! https:) { return null; } return parsed.href; } async function autoScroll(page) { await page.evaluate(async () { await new Promise((resolve) { let totalHeight 0; const distance 800; const timer setInterval(() { const scrollHeight document.body.scrollHeight; window.scrollBy(0, distance); totalHeight distance; if (totalHeight scrollHeight) { clearInterval(timer); resolve(); } }, 100); }); }); await page.waitForTimeout(500); } async function captureScreenshot({ url, width 1920, height 1080, fullPage false, format png, timeout 30000 }) { const browser await getBrowser(); const context await browser.newContext({ viewport: { width, height }, deviceScaleFactor: 2 }); const page await context.newPage(); try { await page.goto(url, { waitUntil: networkidle, timeout }); if (fullPage) { await autoScroll(page); } const buffer await page.screenshot({ type: format, fullPage: !!fullPage }); return buffer; } finally { await context.close(); } } async function screenshotHandler(req, res) { const body req.body || {}; const { url, width, height, fullPage, format, timeout } body; const targetUrl validateUrl(url); if (!targetUrl) { return res.status(400).json({ error: url 参数不能为空且必须是以 http:// 或 https:// 开头的合法地址 }); } const imageFormat format jpeg ? jpeg : png; try { const imageBuffer await captureScreenshot({ url: targetUrl, width: Number(width) || 1920, height: Number(height) || 1080, fullPage: fullPage true, format: imageFormat, timeout: Number(timeout) || 30000 }); res.setHeader(Content-Type, imageFormat jpeg ? image/jpeg : image/png); res.setHeader(Cache-Control, public, max-age86400); res.send(imageBuffer); } catch (err) { console.error([screenshot] capture failed:, err); res.status(502).json({ error: 截图失败 err.message }); } } module.exports { captureScreenshot, screenshotHandler };这里有两个容易忽略的参数。deviceScaleFactor: 2表示用 2 倍像素密度渲染这样截出的图片在高分屏上依然清晰否则网页截图很容易有“糊”的感觉。autoScroll是为了处理懒加载。很多页面的图片和列表要在滚动到视口附近才开始请求直接截图只能得到首屏内容滚动加载后再截图才能拿到完整页面。