用途
Figma Core Workflow B —— 资源导出，用于通过 Figma REST API 从 Figma 文件中导出图片、图标和资源。它可以将指定节点渲染为 PNG、SVG、JPG 或 PDF，适合构建图标、插画和组件预览的自动化资源流水线。
前置条件
- 已完成 figma-install-auth 设置
- 准备待导出框架或组件的节点 ID（来自 figma-hello-world）
- 已设置 FIGMA_PAT 与 FIGMA_FILE_KEY 环境变量
主要能力
步骤 1：将节点渲染为图像
通过 GET /v1/images/:file_key?ids=X,Y&format=png&scale=2 请求渲染节点。支持的格式为 png、svg、jpg、pdf；scale 范围为 0.01 到 4（SVG 始终以 1x 导出）；单张图像最大为 32 百万像素，超出会自动缩小。返回结果中 data.images 是一个 nodeId 到 URL 或 null 的映射，null 表示节点渲染失败（不可见、透明度为 0% 或节点 ID 无效），URL 在 30 天后过期。
步骤 2：下载导出的图像
调用导出函数获取图像 URL 后，逐个下载并写入本地文件系统，文件名基于节点 ID（将 : 替换为 -）。下载结果会记录每个节点的路径与成功状态。
步骤 3：从框架中导出全部图标
先请求框架节点及其子节点，收集类型为 COMPONENT 或 INSTANCE 的子节点 ID，然后以 SVG 格式批量导出。每批最多 100 个 ID。
步骤 4：带组件元数据的命名导出
利用组件元数据生成更友好的文件名：从框架子节点构建 nodeId -> name 映射，将名称转为小写、非字母数字字符替换为连字符并去除首尾连字符，然后按名称导出 SVG 文件。
输出
- 按指定格式与倍率从 Figma 节点渲染的图像
- 下载到本地文件系统的资源文件
- 以命名 SVG 文件形式导出的图标库
- 面向大型组件集的批处理能力
错误处理
- images 映射中为 null：节点不可见或透明度为 0%，需在 Figma 中使节点可见
- 400 Bad Request：节点 ID 格式无效，使用 pageId:nodeId 格式（如 0:1）
- 429 Rate Limited：图像端点属于 Tier 1，需批量请求并遵守 Retry-After
- 图像 URL 过期：URL 30 天后过期，需重新导出，不要长期缓存 URL
- SVG 使用 scale > 1：SVG 忽略 scale 参数，始终以 1x 导出
示例：通过 curl 快速导出
# 以 2x 将单个节点导出为 PNG
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
"https://api.figma.com/v1/images/${FIGMA_FILE_KEY}?ids=0:1&format=png&scale=2" \
| jq -r '.images["0:1"]'
# 返回渲染图像的临时 URL
资源
- Figma Images 端点
- 导出设置
- figma-export-assets（社区工具）
下一步
常见错误请参见 figma-common-errors。