[Python] Satori实战指南：使用JSX将HTML/CSS高效转换为SVG

Satori 是一个优秀的开源库，专门用于将 HTML 和 CSS 转换为 SVG 格式。它支持 JSX 语法，使得开发者能够以简洁的方式处理图形生成。

以下是一个基本使用示例，展示如何通过 Satori 将 JSX 元素渲染为 SVG：

// api.jsx
import satori from "satori";

const svg = await satori(
  <div style={{ color: "black" }}>hello, world</div>,
  {
    width: 600,
    height: 400,
    fonts: [
      {
        name: "Roboto",
        data: robotoArrayBuffer,
        weight: 400,
        style: "normal",
      },
    ],
  }
);

执行上述代码后，Satori 会生成一个 600×400 的 SVG 图形，并返回对应的 SVG 字符串：

'<svg ...><path d="..." fill="black"></path></svg>';

Satori 在底层自动处理布局计算、字体加载和排版等细节，确保生成的 SVG 与浏览器中渲染的 HTML 和 CSS 效果一致。

目前 Satori 在 GitHub 上已获得超过 12.6k 的 star，是一个备受关注的前端开源项目。

在浏览器环境中使用 Satori

Satori 仅支持无状态的纯 JSX 元素。开发者可以使用部分 HTML 元素或自定义 React 组件，但不支持 React 的状态管理 API（如 useState、useEffect）和 dangerouslySetInnerHTML 等功能。

如果没有配置 JSX 转译器，可以直接传递类似 React 元素的对象结构：

await satori(
  {
    type: "div",
    props: {
      children: "hello, world",
      style: { color: "black" },
    },
  },
  options
);

由于 Satori 专注于静态渲染，它仅支持有限的 HTML 和 CSS 功能。例如，不支持 <input> 元素、cursor 属性，以及外部资源加载（如 <style>、<link> 或 <script>）。此外，基于 SVG 1.1 规范的布局引擎可能导致渲染结果与浏览器不完全一致。

图像支持示例：

await satori(
  <img src="https://picsum.photos/200/300" width={200} height={300} />,
  options
);

await satori(
  <img src="data:image/png;base64,..." width={200} height={300} />,
  options
);

在 Node.js 环境中使用

Satori 兼容 Node.js（版本 ≥ 16）和 Web Workers。它默认将 WASM 依赖打包为 base64 字符串并在运行时加载。

对于受限环境（如 Cloudflare Workers），可以使用独立版本。独立版本不包含 Yoga 的 WASM 文件，需要手动加载：

import satori, { init } from 'satori/standalone';

const res = await fetch('https://unpkg.com/satori/yoga.wasm');
const yogaWasm = await res.arrayBuffer();
await init(yogaWasm);

// 现在可以正常使用 satori
const svg = await satori(...);

也可以通过 Node.js 的 fs.readFile 从本地加载 yoga.wasm 文件。

默认情况下，Satori 将文本渲染为 <path> 元素，内嵌字体路径数据。可以通过设置 embedFont 为 false 改用 <text> 元素：

const svg = await satori(
  <div style={{ color: 'black' }}>hello, world</div>,
  {
    ...,
    embedFont: false,
  }
);

参考资料

• Satori GitHub 仓库
• OG Playground 演示