Corsair HtmlToImage 插件实战指南一行接入 HTML/URL 截图 API【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair导读corsair-dev/htmltoimage是 Corsair 生态中的 HTML 转图片插件封装了 html2img 的截图服务让开发者通过统一的 Corsair 客户端即可完成「HTML 片段或公开 URL → PNG/PDF 图片」的转换、结果获取与账户额度查询。本文以 packages/htmltoimage/README.md 为骨架结合插件源码与官方文档完整讲解其安装、配置、3 个类型化 API 操作、本地数据同步模型以及底层的请求封装与校验逻辑读完即可在自己的多租户应用中直接落地截图能力。插件概览3 个操作 2 个同步实体HtmlToImage 插件围绕一条核心业务闭环设计提交渲染请求 → 生成图片 → 取回结果。README 中给出了三个操作及其风险级别操作Operation ID风险说明account.checkUsagehtmltoimage.api.account.checkUsageread查询账户用量与剩余积分html.convertToImagehtmltoimage.api.html.convertToImagewrite将 HTML 或公开 URL 转换为图片image.getImagehtmltoimage.api.image.getImageread获取已生成的图片除 API 操作外插件还会把服务端数据同步到本地数据库提供 2 个可搜索实体accounts账户信息与renders渲染记录支持.search()/.list()快速查询避免每次都要打远程 API。从源码结构看这 3 个操作被组织为嵌套的端点树注册在 packages/htmltoimage/index.tsconst htmlToImageEndpointsNested { account: { checkUsage: HtmlToImage.checkUsage }, html: { convertToImage: HtmlToImage.convertToImage }, image: { getImage: HtmlToImage.getImage }, } as const;对应生成的类型化调用路径即tenant.htmltoimage.api.account.checkUsage、tenant.htmltoimage.api.html.convertToImage、tenant.htmltoimage.api.image.getImage。安装与项目配置安装依赖插件本身依赖 Corsair 核心运行时与 Zod 校验库见 packages/htmltoimage/package.json 中peerDependencies为corsair 0.1.0、zod ^4.1.13。按包管理器任选其一安装npm install corsair corsair-dev/htmltoimageyarn add corsair corsair-dev/htmltoimagepnpm add corsair corsair-dev/htmltoimagebun add corsair corsair-dev/htmltoimage注册插件在 Corsair 实例初始化时通过plugins数组将htmltoimage()注册进去并配置本地数据库与 Hub 密钥import Database from better-sqlite3; import { createCorsair } from corsair; import { htmltoimage } from corsair-dev/htmltoimage; export const corsair createCorsair({ plugins: [ htmltoimage(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });database本地 SQLite 数据库实例用于同步accounts、renders实体实现离线可查询。kekCorsair 的密钥加密密钥Key Encryption Key用于加密租户凭据参见 docs/quick-start.mdx。hubCorsair Hub 的项目 API Key 与签名密钥负责承载连接页与结果投递参见 docs/management/connect.mdx。多租户是默认行为——所有调用通过corsair.withTenant(id)限定租户范围账户间数据天然隔离详见 docs/concepts/multi-tenancy.mdx。连接租户首次使用前需要为用户租户生成一个连接链接Hub 会托管连接页面并在完成后把结果投递给你的应用const { connectUrl } await corsair.manage.connect.createLink({ plugin: htmltoimage, tenantId: acme, }); // 将用户浏览器重定向到 connectUrl连接成功后租户即可在withTenant作用域下调用插件 API。认证机制API Key 与 keyBuilderREADME 明确Auth: API keyCorsair 会在租户首次使用时提示其提供凭据。插件默认也是唯一的认证类型是api_key在 packages/htmltoimage/index.ts 中硬编码为const defaultAuthType: AuthTypes api_key as const;认证配置为{ api_key: {} }。源码中keyBuilder给出了 API Key 的完整解析优先级packages/htmltoimage/index.ts若在插件选项中显式传入key如htmltoimage({ key: htim_xxx })端点调用直接使用该 Key否则从当前租户上下文的keys.get_api_key()中读取已存储的租户 Key两者都取不到时抛出AuthMissingError(htmltoimage, api_key)提示用户补充凭据。测试 packages/htmltoimage/endpoints.test.ts 中的keyBuilder用例验证了这两种路径传key时正常解析、无 Key 时抛错。这对应了 README 所述「首次使用弹窗收集凭据」的机制——租户凭据由 Corsair 加密存储调用端点时自动取出注入请求。API 操作详解输入输出与校验规则以下 3 个操作的参数形状与返回类型均由插件 Zod schema 定义见 packages/htmltoimage/endpoints/types.ts调用即获得完整 TypeScript 类型提示与运行时校验。account.checkUsage查询账户与剩余积分风险级别read输入空对象。const tenant corsair.withTenant(acme); const usage await tenant.htmltoimage.api.account.checkUsage({});底层实现为GET https://app.html2img.com/api/me见 packages/htmltoimage/endpoints/check-usage.ts返回类型HtmlToImageAccountpackages/htmltoimage/schema/database.ts字段类型必填说明emailstring是账户邮箱planstring否套餐标识plan_namestring否套餐名称activeboolean是账户是否启用free_planboolean是是否免费套餐credits_remainingnumber是剩余积分Zod 约束为非负整数credits_reset_atstring否积分重置时间html.convertToImage核心渲染操作风险级别write输入支持两种渲染源——HTML 字符串或公开 URL二者必须且只能提供一个字段类型必填校验约束说明htmlstring否非空字符串要渲染的 HTML 片段urlstring否必须是http:/https:公开地址要截图的公开网页cssstring否—附加 CSSwidthnumber否整数1–5000输出宽度pxheightnumber否整数1–5000输出高度pxfullpageboolean否—是否整页截图dpinumber否整数1–4输出 DPIformatpng \| pdf否枚举输出格式scale_to_fitboolean否—是否缩放以适应画布ms_delaynumber否整数1–5000渲染前等待毫秒数webhook_urlstring否合法 URL异步完成回调地址wait_for_selectorstring否—等待页面中该选择器出现再截图selectorstring否长度 ≤ 255仅对url模式有效Zod 的superRefine还做了三重交叉校验packages/htmltoimage/endpoints/types.ts这是文档表格之外的关键行为务必注意html与url必须二选一——同时提供或同时缺失都会报错Provide exactly one of html or urlselector只在提供url时合法否则报selector is only valid with urlselector对pdf格式无效会被忽略并给出提示。输出HtmlToImageRender见 packages/htmltoimage/schema/database.ts字段类型必填说明successtrue是恒为true字面量类型idstring是渲染任务 IDurlstring否结果图片 CDN 地址credits_remainingnumber否渲染后剩余积分expires_atstring否图片过期时间statusprocessing否异步任务时为processingmessagestring否附加信息调用示例const tenant corsair.withTenant(acme); const result await tenant.htmltoimage.api.html.convertToImage({ html: h1Hello Corsair/h1, format: png, width: 1200, fullpage: true, });底层路由packages/htmltoimage/endpoints/convert-to-image.ts会按渲染源分流提供url时POST /api/screenshot仅提供html时POST /api/html并把selector仅在 URL 模式下随请求体发送。image.getImage取回已生成图片风险级别read输入只有url必填并且 Zod 校验该地址必须是https://i.html2img.com的 CDN 域名见 packages/htmltoimage/endpoints/types.ts 的isHtml2imgCdnUrl辅助函数const tenant corsair.withTenant(acme); const { url } await tenant.htmltoimage.api.image.getImage({ url: https://i.html2img.com/image-1786092598870-921691.png, });输出为{ url: string }——同样的 CDN 地址。实现上该操作不发起远程 HTTP 请求仅做域名白名单校验后直接回传packages/htmltoimage/endpoints/get-image.ts可作为生成结果 URL 的安全入口。本地数据同步search 过滤器与操作符插件将远端数据同步到本地 SQLite实体挂载在corsair.htmltoimage.db.entity下支持.search({ data, limit?, offset? })与.list()。分页参数limit、offset对所有查询通用详见 docs/concepts/database.mdx。accounts 实体路径htmltoimage.db.accounts.searchconst rows await corsair.htmltoimage.db.accounts.search({ data: { /* filters below */ }, limit: 100, offset: 0, });可搜索过滤器来自 docs/plugins/htmltoimage/database.mdx字段类型操作符entity_idstringequals, contains, startsWith, endsWith, inemailstringequals, contains, startsWith, endsWith, inplanstringequals, contains, startsWith, endsWith, inplan_namestringequals, contains, startsWith, endsWith, inactivebooleanequalsfree_planbooleanequalscredits_remainingnumberequals, gt, gte, lt, lte, incredits_reset_atstringequals, contains, startsWith, endsWith, in典型场景筛选「剩余积分不足 100 的免费账户」并做用量告警const lowCreditAccounts await corsair.htmltoimage.db.accounts.search({ data: { credits_remaining: { lt: 100 }, free_plan: true }, });renders 实体路径htmltoimage.db.renders.searchconst rows await corsair.htmltoimage.db.renders.search({ data: { /* filters below */ }, limit: 100, offset: 0, });可搜索过滤器字段类型操作符entity_idstringequals, contains, startsWith, endsWith, inidstringequals, contains, startsWith, endsWith, inurlstringequals, contains, startsWith, endsWith, incredits_remainingnumberequals, gt, gte, lt, lte, inexpires_atstringequals, contains, startsWith, endsWith, inmessagestringequals, contains, startsWith, endsWith, in典型场景按时间或过期状态检索某租户的历史渲染记录const recentRenders await corsair.htmltoimage.db.renders.search({ data: { entity_id: acme, id: { startsWith: 8a9d } }, limit: 50, });源码纵深请求封装与错误处理所有远程请求统一经由 packages/htmltoimage/client.ts 的makeHtmlToImageRequest发出基础地址固定为https://app.html2img.com鉴权头为X-API-Key请求时注入当前租户解析出的 API Key采用corsair/http的request基础设施与 Corsair 核心 HTTP 层一致Content-Type: application/json; charsetutf-8任何非ApiError/HtmlToImageAPIError的异常会被包装为HtmlToImageAPIError统一错误面。插件还内置了错误分类器error-handlers.ts测试 packages/htmltoimage/endpoints.test.ts 通过构造不同 HTTP 状态码如 401/429验证错误归类帮助上层应用对「凭据失效」「限流/积分不足」等场景做出差异化响应。关于 Corsair 通用错误处理模型可参考 docs/concepts/error-handling.mdx。此外三个操作在完成后都会通过logEventFromContext记录事件如htmltoimage.convert_to_image并附带id、format、width等上下文便于审计与追踪这也与 README 中「无 Webhooks」的定位互补——插件不主动推送事件但本地日志与同步数据已覆盖常用观测需求。小结corsair-dev/htmltoimage用极少的接入成本把 HtmlToImage 的截图能力完整纳入 Corsair 的类型系统与多租户模型3 个类型化操作覆盖「查额度 → 渲染 → 取图」全链路输入输出由 Zod 在运行时双重保障2 个本地同步实体让accounts、renders可离线、可过滤、可分页查询API Key 认证按「插件选项 Key → 租户存储 Key」的优先级解析未配置时引导用户补齐凭据底层请求封装统一处理基地址、鉴权头与错误包装测试覆盖插件形状、Key 解析与错误分类。配置时注意三点即可快速上手html/url二选一、selector仅限 URL 模式且对 PDF 无效、getImage只接受i.html2img.com域名的地址。若要进一步将该插件的操作暴露给 Agent 作为 MCP 工具可参考 docs/mcp-adapters/mcp-adapters.mdx。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考