HTML 渲染为图片

要解决什么问题

把本地 .html 做成可分享、可嵌入文档或汇报材料的静态图片时，自己搭无头浏览器往往成本高；本技能走固定远端 html2image 接口，用一条脚本完成「读文件 → 请求渲染 → 写盘」。

工作方式

1. 从磁盘以 UTF-8 读取 HTML 内容。
2. 需要核对字段或错误码时，可查技能内 references/html-to-image-api.md。
3. 通过 scripts/render-html-to-image.ts 调用 POST https://html2image.hanfangyuan.cn/api/html2image，解码返回的 image_base64 并写入 --output 路径。
4. 确认目标路径上已生成图片文件。

常用参数：--input / --output 必选；可选 --element-id（不带 #）、--image-type（png / jpeg）、--device-scale-factor、--viewport-width / --viewport-height、--render-wait-ms、--element-padding（配合元素截图时的边距）。

边界与注意点

• 运行依赖本机可用的 npx（脚本经 npx -y tsx 执行 TypeScript）。
• HTML 里的图片必须是公网 URL，本地路径不会被远端加载。
• 输出扩展名应与 --image-type 一致。
• 卡片或页面尺寸大于默认视口时，务必调大 --viewport-width / --viewport-height，否则易被裁切；设计尺寸已知时，视口应不小于目标元素。
• 异步字体、外链图未就绪时可加 --render-wait-ms。
• 接口 400 多为 element_id 不存在；422 多为参数越界或不合法。