1. 从 Figma 到 PSD 的真实工作流长什么样Figma 导入 PSD 这件事听起来像是一个格式转换的小需求但真正做过的人都知道它背后牵扯的是图层命名、字体替换、切图导出、脚本调用一整条链路。我最近帮一个做电商中台的设计团队梳理这套流程他们的场景很典型设计稿在 Figma 里协作完成但下游的运营团队、外包供应商、甚至部分老旧的素材管理系统只认 PSD。于是每次交付都要手动导出、手动整理图层、手动补字体一个页面折腾两小时。核心检索词先摆出来Figma 导入 PSD 是什么本质是把 Figma 的矢量图层树、文本样式、图片填充、组件实例转换成 Photoshop 能识别的图层结构。它能做什么让设计稿在 PSD 生态里继续被编辑、被切图、被二次加工。适合谁适合需要向传统设计流程交付源文件的设计师、需要批量处理设计稿的前端、以及想把这条链路自动化的技术同学。这条链路里最容易被低估的是「一致性校验」。很多人导出完 PSD 打开一看图层是平的、字体被替换成默认的、阴影变成了位图然后就开始手动修。修一个文件还行修二十个文件就是灾难。所以这篇笔记的重点不是教你点哪个按钮而是给你一套可复制的配置、一份校验清单以及如何用统一的 API 通道把脚本调用串起来让「导出—校验—修正」变成可重复执行的流程。我先说结论Figma 原生并不直接导出 PSD官方导出格式是 PNG、JPG、SVG、PDF。要拿到 PSD通常走两条路。第一条是借助中间格式转换比如先导出 Sketch 文件再转 PSD或者通过 Adobe XD 做中转。第二条是用插件或脚本把 Figma 的节点树通过 API 拉出来再用图像库合成 PSD。第一条路适合手动操作、单文件交付第二条路适合批量、自动化、需要校验的场景。下面我会把两条路都讲清楚重点放在第二条因为那才是「链路」的意义。中间会用到 TaoToken 的统一 Key 来调用模型能力做图层命名规范化、字体映射建议、以及导出后的结构比对。注意TaoToken 在这里的角色是提供统一的 API 通道让你不用在多个平台之间来回切换 Key而不是替代 Figma 或 Photoshop 本身。先说一个我踩过的坑早期我试图直接用 Figma 的 REST API 拉节点然后自己拼 PSD结果发现文本图层的行高、字距、混合模式这些属性在 API 里拿到的值和渲染出来的效果有偏差。后来改成「API 拉结构 截图做视觉参考 脚本合成」的组合才稳定下来。这个思路贯穿全文。2. TaoToken 统一 Key 的前置准备与 API 通道配置在讲具体配置之前先解释为什么这条链路需要一个统一的 Key。你做 Figma 导入 PSD 的自动化脚本里通常要做几件事调用 Figma API 拿节点数据、调用模型接口做图层命名清洗或字体映射、可能还要调用图像处理服务。如果每个服务都用不同的 Key、不同的 Base URL脚本里就会散落一堆环境变量换个人接手就懵。TaoToken 的做法是给你一个统一的入口Base URL 固定Key 统一管理模型 ID 按需切换。前置准备分三步。第一步拿到 Key。访问 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建一个新的 Key复制保存。注意这个 Key 只在创建时完整显示一次丢了就重新建。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api所有请求都走这个地址不要自己拼别的路径。第三步选模型 ID。做图层命名规范化和字体映射建议用通用的对话模型就够如果要做图像理解辅助判断图层类型选支持视觉的模型。模型列表可以在模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite查看。配置方式我推荐用环境变量加配置文件双保险。环境变量放 Key配置文件放 Base URL 和模型 ID这样脚本可以跨项目复用。下面是一个.env的示例# .env TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL_ID你的模型ID然后在脚本里读取。如果你用的是 Node.js可以这样初始化客户端// taotoken-client.js import OpenAI from openai; import dotenv from dotenv; dotenv.config(); export const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); export const MODEL_ID process.env.TAOTOKEN_MODEL_ID;这里有个细节OpenAI SDK 的baseURL要写到/api这一层SDK 会自动拼接/v1/chat/completions这类路径。如果你手动用 fetch 请求完整地址是https://taotoken.net/api/v1/chat/completions。我试过用错层级导致 404排查了半天所以这里写清楚。如果你更习惯用 Python配置逻辑一样# taotoken_client.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL), ) MODEL_ID os.getenv(TAOTOKEN_MODEL_ID)对于需要长期跑批量任务的场景比如每天晚上定时把当天更新的 Figma 文件导出成 PSD 并校验建议用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite来管理调用配额和并发。它的好处是你不用自己维护重试和限流逻辑脚本里专注业务就行。配置完成后先做一次最小验证确认 Key 和通道是通的。这一步不要跳过否则后面脚本报错你分不清是配置问题还是业务逻辑问题。3. 可复制的 Figma 导出配置与 PSD 合成脚本这一节是全文的核心给你一套可以直接抄的配置和脚本。整体思路分四步从 Figma 拉节点树、用模型做图层命名和字体映射、用脚本合成 PSD、导出切图。每一步都有可复制的片段。第一步Figma 侧的导出配置。在 Figma 里选中要导出的 Frame右侧面板的 Export 区域添加导出设置。格式选 PNG倍数选 2x 用于视觉参考同时把「Include layer names」相关的插件配置打开。如果你用插件导出推荐在插件设置里勾选「Preserve layer hierarchy」和「Export text as editable」。这两个选项决定了后面 PSD 里图层是不是平的、文字能不能改。第二步拉取节点树。用 Figma REST API 的/v1/files/:key/nodes接口传入 node-id。请求头里放 Figma 的 token这个 token 和 TaoToken 的 Key 是两回事别混。拿到 JSON 后你会看到每个节点的type、name、characters、style等字段。下面是一个精简后的节点结构示例{ nodes: { 1:23: { document: { id: 1:23, name: Button/Primary, type: COMPONENT, children: [ { id: 1:24, name: Label, type: TEXT, characters: 提交订单, style: { fontFamily: PingFang SC, fontWeight: 500, fontSize: 16 } } ] } } } }第三步用 TaoToken 做命名规范化和字体映射。Figma 里的图层命名经常是「Frame 123」「Rectangle 45」这种直接进 PSD 没法用。写一个函数把节点名批量发给模型让它按你的规范重命名。规范可以自定义比如「模块_元素_状态」。同时让模型给出字体映射建议因为 PSD 环境里不一定有 PingFang SC需要映射到系统里有的字体。// normalize-layers.js import { client, MODEL_ID } from ./taotoken-client.js; export async function normalizeLayerNames(nodes) { const prompt 你是一个设计稿图层命名助手。请把下面的图层名按「模块_元素_状态」的规范重命名 并给出字体映射建议如果原字体在当前系统不可用推荐一个替代字体。 输入${JSON.stringify(nodes)} 输出 JSON 数组每项包含 originalName、newName、fontFamily、fallbackFont。; const res await client.chat.completions.create({ model: MODEL_ID, messages: [{ role: user, content: prompt }], temperature: 0.2, }); return JSON.parse(res.choices[0].message.content); }第四步合成 PSD。Node.js 里可以用ag-psd这个库它支持写入图层、文本、组、蒙版。下面是一个最小可运行的合成示例// build-psd.js import { writePsdBuffer } from ag-psd; import fs from fs; const psd { width: 750, height: 1334, children: [ { name: Header, children: [ { name: Title, text: { text: 订单确认 } }, ], }, { name: Content, children: [ { name: Button_Primary_Default, text: { text: 提交订单 } }, ], }, ], }; const buffer writePsdBuffer(psd); fs.writeFileSync(output.psd, buffer);把第三步的输出喂给第四步就能生成带规范图层名的 PSD。切图导出单独处理用 Figma 的/v1/images/:key接口指定 format 为 pngscale 为 2批量拿 URL 后下载。这里给一个完整的配置对照表方便你检查参数配置项推荐值说明Figma 导出格式PNG 2x用于视觉参考和切图图层层级Preserve hierarchy避免图层被拍平文本导出Editable text保证 PSD 里文字可改TaoToken Base URLhttps://taotoken.net/api统一入口模型温度0.2命名任务要稳定PSD 库ag-psd支持文本和组如果你用 Cline MCP 或 Claude Code 来做这套脚本的开发记得把三件套写全Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 填你选的模型。缺一个都会报连接错误。CC Switch 里切换配置时也是这三项别只改 Key 忘了 Base URL。4. 验证请求与成功结果图层结构一致性怎么确认脚本跑完不算完必须验证导入后的 PSD 图层结构和源文件一致。这一步很多人省掉结果交付后被下游打回来。验证分三个层面结构、文本、视觉。结构验证比对节点数量和层级。写一个函数把 Figma 节点树和 PSD 图层树都转成扁平化的路径列表然后做 diff。路径用「父/子/孙」的形式表示。下面是一个比对脚本的片段// verify-structure.js function flatten(node, prefix ) { const path prefix ? ${prefix}/${node.name} : node.name; const result [path]; if (node.children) { for (const child of node.children) { result.push(...flatten(child, path)); } } return result; } export function diffStructure(figmaTree, psdTree) { const a new Set(flatten(figmaTree)); const b new Set(flatten(psdTree)); const missing [...a].filter((p) !b.has(p)); const extra [...b].filter((p) !a.has(p)); return { missing, extra }; }如果missing和extra都为空说明结构一致。如果有差异优先看是不是组名被改了或者某些装饰性图层被合并了。文本验证比对每个文本图层的characters和字体属性。Figma 里拿到的characters要和 PSD 里的text.text一致。字体方面如果做了映射比对映射后的字体名。这里可以用 TaoToken 再跑一次校验把两边的文本列表发给模型让它找出语义不一致的地方比如「提交订单」变成了「提交」。视觉验证把 Figma 导出的 PNG 和 PSD 导出的 PNG 做像素级比对。用pixelmatch这个库输出差异图。如果差异像素占比低于 1%基本可以认为视觉一致。高于这个值就要看是阴影、圆角还是字体渲染的差异。成功的结果长这样控制台输出Structure OK、Text OK、Visual diff 0.3%然后生成一份校验报告。报告里列出所有被重命名的图层、被替换的字体、以及切图的下载链接。这份报告可以直接发给下游减少沟通成本。我实测下来一个包含 200 个图层的页面从拉取到校验完成大约 40 秒其中模型调用占 15 秒左右。如果批量处理 20 个页面用 Coding Plan 的并发能力可以压到 5 分钟以内。这个效率比手动导出快一个数量级。验证通过后把 PSD 和切图打包连同校验报告一起交付。如果下游反馈某个图层有问题你可以根据报告里的原始名快速定位到 Figma 里的节点改完重新跑一遍脚本就行。这就是「链路」的价值可重复、可追溯、可修正。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节把我在实操中遇到的报错集中列出来每个都给排查路径。你遇到问题时按顺序对照。401 Unauthorized。这个最常见原因有三个Key 没填、Key 填错、Key 过期。先检查.env里的TAOTOKEN_API_KEY是不是完整复制了有没有多余空格。然后确认请求头里的Authorization格式是Bearer sk-xxx。如果 Key 是对的还报 401去 API Keys 页面确认这个 Key 是否被禁用或删除。注意Figma 的 token 和 TaoToken 的 Key 是两个东西别把 Figma token 填到 TaoToken 的请求里。local proxy failed。这个报错通常出现在你本地网络环境有代理设置但脚本没有正确读取。排查方法是检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY这类设置如果有确认它们指向的地址是可达的。如果你不需要代理把这些变量清空再跑。另外某些 Node.js 版本对代理环境变量的处理不一致可以在脚本里显式设置process.env.NO_PROXY *来排除干扰。这个报错和 TaoToken 本身无关是本地环境问题。reading choices 相关报错完整信息通常是Cannot read properties of undefined (reading choices)。这说明 API 返回的结构里没有choices字段原因可能是请求失败但没抛错或者返回的是错误对象。排查方法是在调用后先打印完整响应const res await client.chat.completions.create({...}); console.log(JSON.stringify(res, null, 2));如果看到error字段按错误信息处理。常见的是模型 ID 写错或者请求体格式不对。还有一种情况是流式响应没处理完就取choices加个await或检查stream参数。OAuth 相关报错。如果你用 Claude Code 或类似工具接入报 OAuth 错误通常是因为认证方式选错了。这些工具默认可能走 OAuth 流程但 TaoToken 用的是 API Key 认证。你需要在配置里明确选择 API Key 模式把 Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填对应模型。三件套缺一不可。如果工具里同时有 OAuth 和 API Key 两个选项选 API Key。还有一个容易忽略的报错PSD 合成后打开是空白。这通常是ag-psd的坐标系问题子图层的left、top没设置默认都在 (0,0) 重叠了。给每个图层显式设置位置就行。另外文本图层如果没设置fontPhotoshop 打开会提示字体缺失虽然能显示但不可编辑。在合成时把font字段补上。排查顺序建议先确认 Key 和 Base URL再确认模型 ID然后看请求体最后看本地环境。大部分问题在前两步就能解决。如果还不行把完整请求和响应贴到接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里对照参数说明通常能找到原因。6. 把这条链路用起来从单次导出到日常流程到这里配置、脚本、验证、排错都齐了。最后说说怎么把它变成日常流程而不是一次性折腾。第一把脚本封装成命令行工具。用commander或yargs包一层支持传入 Figma 文件 key、node-id、输出目录。这样你不需要每次改代码直接node export.js --file xxx --node 1:23 --out ./dist就行。第二把校验报告接入你的交付流程。如果团队用飞书或钉钉可以写个 webhook校验通过自动发消息附上报告链接。校验不通过就 相关负责人。这样下游不用问「导好了吗」你也不用重复回答。第三定期更新字体映射表。不同项目用的字体不一样映射关系会变。把映射表单独存一个 JSON 文件每次跑脚本前用 TaoToken 检查一遍有没有新字体需要补充。这个动作可以做成定时任务每周跑一次。第四对于长期跑批量任务的团队用 Coding Plan 管理配额和并发避免高峰期调用失败。它的重试机制比你自己写的稳省下来的时间可以放在设计规范上。第五保留每次导出的原始节点 JSON 和校验报告。万一下游说某个版本有问题你可以回溯到具体是哪次导出、哪个图层、什么参数。这个习惯在多人协作里特别值钱。我自己的做法是把整套东西放在一个 Git 仓库里配置用.env.example做模板脚本分模块校验报告按日期归档。新同事入职clone 下来填个 Key 就能跑。这样「Figma 导入 PSD」就不再是一个人的手艺而是团队的基础设施。如果你还没开始建议先从单个页面跑通确认结构、文本、视觉三层校验都过再扩展到批量。跑通之后你会发现原来最耗时的不是导出本身而是导出后的对齐和返工。把校验做在前面返工就少了。