先说明白一件事标题里的“figma”本身有两种理解。一种是指那个能活动的手办模型品牌另一种是指 UI 设计协作工具 Figma。本文聊的是后者。不过我想把拆手办的那种兴奋感保留下来——如果你最近对着设计稿写页面写到逐渐提不起兴趣那这套“设计稿读取 JSON 结构化 AI 编程助手生成代码”的工作流值得你花两小时重新点燃一下自己。这篇文章会围绕四个关键点展开第一Figma 的本地化体验到底怎么解决包括汉化、客户端和字体第二Figma MCP 这两年为什么突然重要第三从 Figma API 读取节点到生成前端代码的完整流程第四一批高频问题的排查思路。读完你至少能照着手动跑通“读取设计稿节点 → 转为结构化 JSON → 交给 AI 生成 UI 代码”这条链路并且知道出问题时先查哪里。1. 这篇文章真正要解决的问题先说痛点。大多数前端或全栈开发者都经历过这类场景设计师交付一个 Figma 链接你打开设计稿对照着量间距、取颜色、复制字号然后手工写成 CSS。一个页面还好遇到一个模块二三十个设计稿文件时大部分时间都消耗在“把视觉信息翻译成代码结构”上。这种重复劳动做多了就很容易进入冷淡期。Figma 这两年最大的变化不是多了一堆设计功能而是它开始被 AI 编程助手当作“读设计稿的接口层”来调用。过去设计稿对 AI 来说是图片AI 只能“看个大概”现在通过 Figma API 或 Figma MCPAI 拿到的是一份包含图层结构、布局属性、颜色、文字、间距的 JSON 数据。这两者的差别相当于让一个人“看照片做菜”和“按配方做菜”。所以这篇文章真正要解决的问题是如何把 Figma 设计稿从“图片”变成“结构化数据”再结合 AI 生成可用代码同时把汉化、字体、API 额度这些坑提前踩平。适合前端工程师、全栈开发者、设计系统维护者以及所有想在 AI 编程工具链里加入“设计稿输入”这环的人。2. Figma 的定位从设计交付工具到设计开发接口2.1 为什么说 Figma 已经不只是画图工具早期的设计协作工具核心任务是把设计稿“交付”给开发形式通常是标注尺寸、导出切图、生成样式代码。这个流程里设计稿和代码之间是断裂的设计师改一个圆角前端就要重新看一遍设计稿再手动改代码。Figma 的底层模型不一样。它的文件本质上是一棵节点树页面里有画板画板里有图层每个图层都有类型、位置、尺寸、样式。这种结构天然适合被程序读取。也就是说Figma 文件本身就像一份“可视化的 JSON”设计工具只是把这份 JSON 渲染出来给你看。这带来一个结果只要接入 Figma API外部程序就可以按节点 ID 精确读取某个按钮、某段文字、某个图标的全部样式信息。过去需要人眼做的“尺寸测量”现在变成了简单的字段读取。2.2 本地化现状汉化、客户端与字体对中文用户来说Figma 的门槛有两层一层是界面语言一层是中文字体环境。Figma 官方一直以英文界面为主虽然部分账户可以在设置里切换语言但很多旧版本客户端仍然默认英文。于是“figma 汉化”“figma 中文语言包”“figma 客户端汉化”这些需求常年存在。社区里有不少语言包和汉化插件但使用第三方汉化工具时需要谨慎因为它会修改客户端资源版本更新后可能出现失效、界面文字缺失、甚至无法启动的问题。字体的坑更常见。Figma 桌面端依赖系统字体库。你刚下载安装的中文字体如果没有重启 Figma很可能在字体列表里找不到如果文件里的字体在系统中不存在Figma 会弹窗提示缺字甚至在某些情况下自动替换成另一套字形。这不是 Figma 的 bug而是字体管理方式导致的问题理解了机制就很好排查。3. 环境准备客户端、中文字体与界面语言3.1 客户端获取建议优先从 Figma 官网下载桌面客户端而不是使用第三方打包版本。桌面客户端有两个优势一是本地字体识别更直接二是快捷键和系统集成更完整。Web 版也不是不能用但遇到字体缺失、大文件卡顿、插件权限问题时桌面端往往更省心。如果你已经装了客户端也请留意版本。Figma 的自动更新比较激进旧版本可能在 API 调用和 Dev Mode 功能上不完整。遇到 MCP 连接失败时先检查客户端版本再检查 Figma 登录状态。3.2 中文字体安装与识别以最常见的场景为例设计稿用了“思源黑体”或“HarmonyOS Sans”这类字体你本地没有安装页面文字就会变成默认字体样式看起来完全不对。安装字体后请按这个顺序排查在系统字体目录中确认字体已安装。Windows 可以双击 .ttf/.otf 文件然后点击“安装”macOS 可以双击后在“字体册”里确认。完全退出 Figma 进程再重新打开。选中设计稿中的文字图层打开右侧 Text 面板在字体下拉框中输入完整字体名确认系统能识别到该字体。如果字体名包含 ExtraLight、Medium 等字重后缀检查是否只安装了常规字重。很多“字体在 Figma 中不生效”的问题其实不是 Figma 的问题而是字体只装了单一字重或者安装后没有重启客户端。3.3 中文界面与汉化方案关于汉化我的建议分两个层次。如果你只需要看懂菜单先检查账户设置里是否提供语言切换选项。有的账号已经能切换为简体中文这是最安全的方式不修改客户端文件跟随账号状态生效。如果你的客户端版本没有这个选项再考虑社区汉化包。但要注意两点一是从可信渠道获取避免下载到被植入额外逻辑的修改版安装包二是清楚汉化包有失效风险。Figma 客户端更新后汉化文件很可能被覆盖或不再匹配。团队协作场景里我更推荐让成员使用英文界面配合官方文档理解术语而不是依赖汉化包。这并不难因为 Figma 的高频操作就集中在 Move、Frame、Text、Design 这几个面板里。4. Figma MCP设计稿与 AI 编程助手的“翻译层”4.1 MCP 是什么MCP 的全称是 Model Context Protocol可以简单理解成“AI 模型读取外部工具数据的统一接口协议”。以前你要让 AI 读取设计稿得自己写脚本调用 API然后把输出粘贴给 AI。有了 MCP 之后AI 编程助手可以直接按需调用插件读取当前设计稿里的选中节点、图层结构、样式信息甚至批量获取标注。MCP 的价值不是“多了一个插件”而是把工具调用方式标准化了。无论你用的是 Claude、Codex、Trea还是其他支持 MCP 的客户端配置结构都是一套声明 server 名称、启动命令、环境变量。一旦你为一个项目配好 Figma MCP团队其他人也能复用同一份配置。从材料看“figma mcp”“trea figma mcp”“codex figma”这些词集中出现在搜索趋势里说明大量开发者已经开始把 Figma MCP 接入自己的 AI 编程工具链。它本质上解决的是“AI 看不到设计稿”的问题模型如果不读 JSON就只能靠截图猜布局读了 JSON 之后颜色、间距、字号都是确定值生成代码的准确性会明显提升。4.2 Figma 官方 API 和 MCP server 的定位区别Figma 官方 APIREST API和 MCP server 不是替代关系。REST API 适合程序化批量读取比如写一个定时脚本把整个文件的节点信息拉下来保存为 JSONMCP server 更偏向交互式调用比如在 AI 编程助手里让模型实时读取当前设计稿选中节点再生成对应组件。实际项目中通常两种方式配合使用MCP 负责日常开发时的“随取随用”REST API 负责搭建设计到代码的自动化流水线。下面就从创建令牌开始把两条路都走一遍。5. 完整示例连接 Figma 读取节点信息5.1 第一步创建个人访问令牌在 Figma 网页版中进入账户设置找到 Security 或 Personal access tokens 模块创建一个新的访问令牌。创建时最好只勾选“File content: Read-only”这类最小读取权限不要给编辑权限。创建完成后把令牌保存到项目本地环境变量中不要写进代码仓库。# 文件路径.env FIGMA_API_KEY你的_figma_personal_access_token如果你使用命令行可以临时导出export FIGMA_API_KEY你的_figma_personal_access_token用下面这个接口可以验证令牌是否有效curl -H X-Figma-Token: $FIGMA_API_KEY \ https://api.figma.com/v1/me看到返回 JSON 中有你的邮箱或用户名说明令牌有效。5.2 第二步获取设计稿的文件信息打开任意一个 Figma 设计稿浏览器地址栏里的 URL 大致长这样https://www.figma.com/file/AbCdEf123/MyDesign?node-id1-2其中AbCdEf123就是文件 key。node-id1-2是当前选中的节点 ID注意在 API 调用里要写成1:2冒号替代短横线。先请求整个文件的基本信息curl -H X-Figma-Token: $FIGMA_API_KEY \ https://api.figma.com/v1/files/AbCdEf123/names \ | jq .上面这个请求只返回文件名称和缩略图不会拉取完整节点数据适合先确认文件可访问。完整文件 JSON 的接口是这个路径curl -H X-Figma-Token: $FIGMA_API_KEY \ https://api.figma.com/v1/files/AbCdEf123 \ -o design-file.json不过完整文件 JSON 通常很大动辄几千 KB不建议每次开发都整包拉取。更高效的做法是只读取某个节点curl -G https://api.figma.com/v1/files/AbCdEf123/nodes \ -H X-Figma-Token: $FIGMA_API_KEY \ --data-urlencode ids1:2 \ -o node-data.json拿到node-data.json后先用jq看看结构jq .nodes[1:2].document node-data.json | head -100只要能看到type、name、children这类字段说明设计稿节点已经成功转换成结构化数据。5.3 第三步通过 MCP 接入 AI 编程助手如果你希望在 AI 编程助手里直接读取设计稿推荐配置 Figma 的 MCP server。下面是一个典型的 MCP 配置结构// 文件路径mcp.json { mcpServers: { figma: { command: npx, args: [-y, figma-developer-mcp], env: { FIGMA_API_KEY: 你的_figma_personal_access_token } } } }请注意具体 MCP server 的包名要以你使用的工具官方文档为准不同客户端的配置字段也可能略有差异但核心结构都是声明command、args和env。配置完成后重启 AI 编程助手在对话中要求“读取当前设计稿选中节点”模型就会通过 MCP 工具去 Figma 实时拉取数据。这里最容易踩的坑有两个一是没有在浏览器/桌面端打开对应设计稿MCP 不知道“当前选中的节点”是什么二是钥匙没有读文件权限API 返回 403。建议先在 Figma 中选中一个页面或组件再发起 AI 指令。6. 图标转 JSON一个高频场景的脚本示例6.1 为什么需要图标转 JSON“figma 如何将图标转换成 json”经常出现在搜索热度里是因为很多前端项目不直接使用设计稿里的 PNG 切图而是希望拿到一套可程序化引用的图标数据。例如生成一个icons.json记录每个图标的名称和 SVG 字符串前端动态渲染图标时直接读取 JSON。你可以在 Figma 中右键单个图标图层选择复制 SVG也可以使用 API 导出。下面给出手动复制 SVG 后的 Node.js 转换脚本。6.2 Node.js 脚本SVG 目录转 JSON// 文件路径scripts/export-icons-to-json.js const fs require(fs); const path require(path); const iconsDir path.join(__dirname, ../assets/icons); const outputFile path.join(__dirname, ../assets/icons.json); const icons {}; fs.readdirSync(iconsDir) .filter((file) file.toLowerCase().endsWith(.svg)) .forEach((file) { const name path.basename(file, .svg).replace(/\s/g, -); const raw fs.readFileSync(path.join(iconsDir, file), utf8); // 简单压缩换行和多余空白便于 JSON 存储 const svg raw.replace(/\n\s*/g, ).replace(/\s/g, ).trim(); icons[name] svg; }); fs.writeFileSync(outputFile, JSON.stringify(icons, null, 2)); console.log(已生成 ${Object.keys(icons).length} 个图标到 ${outputFile});运行方式node scripts/export-icons-to-json.js运行后assets/icons.json内容大致如下{ home: svg ....../svg, user: svg ....../svg, close: svg ....../svg }如果需要进一步压缩体积可以先用 SVGO 对 SVG 做优化再交给上面脚本生成 JSON。这样生成的文件既能用于前端图标组件也可以作为后续 AI 生成代码时的图标素材库。7. 从 JSON 到组件代码一次典型工作流现在我们已经拿到设计稿节点的 JSON接下来要让 AI 编程助手基于它生成代码。为了便于展示我在下面给出一段精简后的节点 JSON真实 API 返回的字段会更多这里去掉无关字段// 文件路径button-node.json演示用已精简 { id: 1:2, name: Button/Primary, type: FRAME, absoluteBoundingBox: { width: 120, height: 40 }, fills: [ { type: SOLID, color: { r: 0.2, g: 0.4, b: 0.9 } } ], children: [ { id: 1:3, name: Label, type: TEXT, characters: 登录, style: { fontSize: 14, fontWeight: 500, textAlignHorizontal: CENTER } } ] }你可以把这段 JSON 直接粘贴到支持长上下文的 AI 编程助手里并给出提示词“用 React 实现这个设计稿节点忽略多余字段保持颜色、尺寸、字号一致。”模型就会生成类似下面的代码// 文件路径src/components/PrimaryButton.tsx export function PrimaryButton() { return ( button style{{ width: 120, height: 40, background: #3366e6, border: none, borderRadius: 4, color: #fff, fontSize: 14, fontWeight: 500, cursor: pointer, }} 登录 /button ); }注意JSON 中的颜色值r: 0.2是 0 到 1 的浮点数转换成 CSS 时通常要乘 255 并取整产生轻微浮点误差是正常的。AI 生成的代码是否准确关键要看输入 JSON 的质量。如果设计稿里填写的是颜色变量而不是具体色值最终输出往往也会更稳定。8. 常见问题与排查思路问题现象可能原因排查方式解决方案Figma 客户端中文界面不完整汉化包版本与客户端版本不匹配查看汉化包说明和客户端版本号升级/更换汉化包或等待官方语言设置新安装的字体在 Figma 里找不到字体仅安装单一字重或安装后未重启在系统字体管理器中确认字体安装完整字重并完全退出重启 FigmaFigma API 返回 403令牌权限不足检查令牌创建时的权限范围重新创建只读令牌确认有文件读取权限Figma API 返回 429 或提示额度不足短时间请求过多超过调用限额查看响应头中的 Retry-After 字段增加缓存、按节点读取避免频繁拉取整个文件MCP 连接失败未打开设计稿或模型工具列表未刷新检查终端报错和 MCP server 日志在 Figma 中打开设计稿并选中节点重启客户端图标导出结果为空选中的是父级画板而非图标图层在图层列表中确认选中对象双击进入图标图层后再复制或导出节点 JSON 中颜色字段缺失图层使用了样式变量而非直接填充检查 Figma 中的样式绑定情况在设计侧将必用色定义为变量统一读取访问 api.figma.com 超时网络策略或代理配置导致无法访问检查网络连通性和公司防火墙策略联系 IT 放行或改用客户端内置功能9. 最佳实践与工程建议9.1 设计侧规范要让 Figma API 和 AI 生成代码的链路真正稳定设计稿的规范程度往往比工具本身更重要。图层命名最好使用英文 PascalCase例如Button/Primary、Card/Header/Title避免大量中文空格和特殊符号。颜色的使用尽量收敛到变量或 Design Tokens不要在图层里直接埋入几十种手工取色值。这样读取节点 JSON 时字段语义会清晰得多。9.2 API Token 安全Figma 个人访问令牌等同于账户的某个权限子集。无论是否只读都应该按密文对待。建议使用.env本地文件或团队密钥管理服务保存不要硬编码到代码仓库更不要粘贴到分享出去的截图里。如果发现令牌泄漏第一时间到 Figma 账户设置里吊销重建。9.3 调用额度与缓存Figma API 对调用频率有限制具体的数值会随平台策略调整以官方文档为准。实践中应该避免在循环里反复请求同一个文件的节点数据而是把一次性拉取的 JSON 缓存到本地比如.figma-cache/目录并设置合理的过期时间。MCP 工具调用频繁时尤其要注意因为一次对话可能引发多次隐藏调用额度消耗会比预想快。9.4 团队协作流程推进这套工作流不建议一上来就要求所有人使用 MCP因为学习成本并不低。更稳妥的方式是先做成一条自动化流水线设计稿更新后CI 任务自动调用 Figma API 拉取指定节点 JSON并同步到前端仓库的设计数据目录。前端在本地拿到 JSON再手动或借助 AI 工具生成代码。这样即使有人不会配 MCP也不影响整条链路运转。9.5 代码生成后的验证AI 基于设计稿 JSON 生成的代码只能当做“初稿”不能直接当作最终交付。你需要对照设计稿检查间距是否来自itemSpacing字段颜色是否需要换算文字是否超出容器。最实用的方式是先让 AI 输出一份“组件结构清单”列出它从 JSON 中理解到的关键样式再进入代码生成这样能减少两轮返工。10. 怎么开始第一次实操如果你之前没有接触过 Figma API建议不要按官方文档从头读到尾而是找一个只有两三个页面的简单设计稿按下面的步骤快速跑通在 Figma 账户里创建只读令牌拿一个真实文件的 key 和节点 ID调用nodes接口保存 JSON把 JSON 精简后交给 AI 编程助手让它生成一个按钮或卡片组件对照设计稿检查颜色、间距、文字是否一致跑通之后再引入 MCP把日常开发里的“选中设计稿 → 生成组件”的交互链路建立起来。这套流程第一次跑通后你大概率会发现设计稿不再是静态图片而是可以直接被程序消费的数据源。它对日常开发最大的帮助不是完全取代人工校对而是把“看稿、量尺寸、翻译成代码”这个枯燥阶段大幅压缩让精力回到真正需要判断的组件交互和业务逻辑上。如果你在配置汉化、字体或 API 时卡住可以按本文的排查表逐项对照。Figma 相关工具链变化很快MCP server 配置和 API 限制会持续调整以实际使用时的官方文档为准。建议收藏本文下次从设计稿到代码时直接按流程走一遍。