@karinjs/plugin-shotium

karin 的 shotium 截图渲染插件。

shotium 是一个被裁剪过的 chromium：只留下 Blink 布局、Skia CPU 光栅化、字体与图片解码，以及 chromium 的网络栈， V8、content 框架、GPU 进程、DevTools 协议全部拿掉了。 它以 Node-API 的形式跑在 node 进程里，没有浏览器进程，也没有 CDP 往返。

对 karin 来说，这意味着渲染模板图这件事不再需要装一个 100+ MB 的浏览器。 代价是页面里的 JavaScript 不会执行——模板必须是服务端渲染好的静态 HTML。

安装

pnpm add @karinjs/plugin-shotium -w

装好重启 karin 即可，插件会自己把渲染器注册进 karin 的渲染器列表。

它做了什么

karin 的渲染器就是一个函数：收下 Options，还回 base64。 这个插件把 karin/puppeteer 那一套参数翻译成 shotium 的参数，再把结果翻译回去。

| karin | shotium | 说明 | | --- | --- | --- | | file | file | 本地路径按配置转成 file:// 或桥接 http 地址 | | data | — | 交给 karin 的 renderTpl 先跑 art-template | | selector | selector | 引擎内部用 Document::querySelector 解析，不注入脚本 | | fullPage | fullPage | 与 selector 互斥，fullPage 优先 | | setViewport.width/height | viewport | | | setViewport.deviceScaleFactor | scale | | | type / quality | type / quality | png 不带 quality | | omitBackground | omitBackground | jpeg 没有 alpha，会被忽略 | | clip | clip | clip.scale 无对应项 | | pageGotoParams.waitUntil | pageGotoParams.waitUntil | networkidle0/2 统一归到 networkidle | | pageGotoParams.timeout | pageGotoParams.timeout | 0(不超时) 回退到引擎默认值 | | headers | headers | 只对同源子资源生效，见下 | | multiPage | tile.height | 走引擎的分片接口 screenshotTiles() | | waitForSelector 等 | — | 引擎没有 JS 运行时，忽略并提示一次 |

分片渲染

multiPage 在 puppeteer 那边是「改视窗高度重截几次」，这里交给引擎的 screenshotTiles()：文档只加载、布局、光栅化一次，引擎在光栅化的过程中按行切开、 逐片编码，同一时刻只存在一片的位图。每一片都来自同一次布局，不会出现分片之间样式对不上的情况。

multiPage: true 用配置里的 autoMultiPageHeight，传数字就是这个数字， 单位是 css 像素，上限 32000（引擎从一个滚动位置能画出的最大行数），超过会被夹到上限。 最后一片是余数，所以片数是 ceil(高度 / 单片高度)。

分片不再限定输出格式：png / jpeg / webp 都能分片，quality 照常生效。

分片模式下没有「整张图」可以往 path 上写，所以 path 按片编号存：路径里写了 {n} 就替换成 1 起的序号，没写就把序号插在扩展名前面（a.png → a-1.png、a-2.png）。

本地文件怎么交给引擎

localAccess 有三档：

• file（默认路径）：file:// 直接打开，同时打开引擎的 allowFileAccess， 模板里 file:// 形式的图片、字体照常能读到。
• http：借用 karin 自己的 express 服务，把本地文件挂在一个带随机 token 的路径下转成 http:// 再截图。 插件不另开端口。 http 文档下 chromium 会拒绝加载 file:// 子资源，所以这条路径上 HTML/CSS 里的 file:// 引用会被一并改写成桥接地址。
• auto（默认）：平时走 file，只有调用方传了 headers 时才切到 http—— 引擎只对同源子资源发送自定义头，file:// 文档没有同源可言，headers 会被整个丢掉。

桥接路径里带一段进程级随机 token，并且只放行渲染会用到的后缀， 避免 karin 监听在 0.0.0.0 时把工作目录直接暴露出去。

配置

首次运行会在 @karinjs/@karinjs-plugin-shotium/config/config.json 生成默认配置，也可以在 WebUI 里改。

| 字段 | 默认值 | 说明 | | --- | --- | --- | | mode | inprocess | inprocess 进程内 / daemon 常驻守护进程 | | localAccess | auto | 见上 | | type | png | 调用方没指定时的截图格式 | | quality | 90 | jpeg / webp 的压缩质量 | | viewport | 800x600 | 默认视窗 | | scale | 1 | 默认设备像素比 | | timeout | 30000 | 默认导航超时 | | autoMultiPageHeight | 4000 | multiPage: true 时每片的高度，css 像素，上限 32000 | | cacheDir | '' | HTTP 磁盘缓存目录，留空用引擎默认，填 off 关闭 | | cacheMaxBytes | 256MB | 缓存上限 | | userAgent | '' | 留空使用引擎内置 | | idleTimeoutMs | 300000 | 守护进程空闲退出时间 | | logStats | true | 日志里带上引擎耗时统计 |

改完配置会热重建引擎，不需要重启 karin。

性能与实测

性能结论以 Shotium 主仓库的六平台基准报告为准。 README 不再混用不同机器、版本和页面的绝对耗时，也不跨平台排名。

标准基准

下面摘录 Shotium 0.3.3 的 linux-x64 合格结果。三者在同一原生 runner、同一静态页面、 PNG、1280×720、scale 1、waitUntil: load 条件下测试；表内为 p50，越低越好。

| 场景 | Shotium | Puppeteer Shell | Puppeteer Chrome | | --- | ---: | ---: | ---: | | 冷启动 | 53 ms | 282 ms（5.32×） | 471 ms（8.89×） | | 启动稳定后的首张 | 21.028 ms | 104.061 ms（4.95×） | 114.146 ms（5.43×） | | 预热截图 | 24.905 ms | 131.601 ms（5.28×） | 157.438 ms（6.32×） | | 启动—截图—关闭循环 | 53.989 ms | 289.344 ms（5.36×） | 565.139 ms（10.47×） |

数据来源：Shotium 0.3.3 基准报告。 该次六平台聚合结果标记为“不完整”，所以上表只引用其中状态为“通过”、允许排名的 linux-x64 同平台数据，不推测缺失结果。

KKK 帮助卡片兼容性实测

2026-08-30 使用 karin-plugin-kkk 2.42.2、@karinjs/plugin-shotium 0.1.0 和 Shotium 0.3.3，在 Windows x64 对实际 SSR 帮助卡片进行了明暗主题冒烟测试：

| 主题 | 尺寸 | PNG 大小 | 插件总耗时 | 引擎耗时 | | --- | ---: | ---: | ---: | ---: | | 亮色 | 1440×2673 | 5.58 MB | 800 ms | 781.2 ms | | 暗色 | 1440×2673 | 6.01 MB | 746 ms | 732.5 ms |

两张卡片的布局、中文、背景和主题均正确。此处只有各一次样本，而且隔离测试没有启动 KKK 的 3780 字体服务，20 个 HarmonyOS 字体请求回退到系统字体，因此它只用于兼容性证明， 不参与上面的性能排名。

这类大卡片会同时承担数 MB CSS 解析和大尺寸 PNG 编码成本；Shotium 主要节省的是冷启动、 常驻内存与浏览器进程/CDP 往返开销。页面越小、调用越频繁，固定开销差异越明显。

需要更快的话，按收益排序：

1. 输出换成 jpeg 或 webp；代价是 jpeg 没有 alpha 通道，omitBackground 会失效。
2. 模板侧把 CSS purge 掉，别把整份 tailwind 内联进每张图。
3. 图别做那么大——同一份内容宽度减半，像素少四分之三。

已知限制

• 页面里的 JavaScript 不会执行。 模板必须是 SSR 好的静态 HTML。 用 Vue/React 组件路径当模板的 file_type（vue3、vueString、react）会直接报错。
• data: 开头的地址不能当作主文档（子资源里的 data URI 正常）。 插件会把 file_type: 'htmlString' 的字符串先落盘再截。
• 没有 waitForSelector / waitForFunction / waitForRequest / waitForResponse。
• 抗锯齿是确定性的灰阶抗锯齿，和 puppeteer 的输出会有极细微的差别。

License

MIT