刚把一版设计稿交付给开发对方连发了五个问题“这个按钮的 hover 色值是多少”“两栏间距是 24 还是 32”“图标是用 SVG 还是切图”“小屏下的断点怎么处理”“组件在 Figma 里的名字叫什么我这边命名对不上。”说实话这些问题在设计稿里全都能找到答案但它们散落在 Figma 的各个图层、样式面板和 Auto Layout 属性里靠人肉翻找再复制粘贴一个下午就没了。这也是为什么我今年开始重度使用Figma MCP来做设计交付——它能让 AI 直接读取 Figma 设计文件的内容自动整理出开发需要的颜色、字体、间距、组件结构甚至生成可参考的代码片段。这篇文章就把我这几个月踩过的路、验证过的配置方式、能直接抄的提示词模板还有那些普通教程里不会写的“隐藏技巧”完整梳理一遍。我默认你是用过 Figma、听说过 MCP但还没真正把它跑通的设计师或者前端开发。如果你连 MCP 是什么都还不太清楚也不用担心第一章节我会用最直白的方式解释清楚然后再带你一步步把自动生成开发文档的流程搭起来。1. 先把概念讲清楚Figma MCP 到底是什么以及它为什么能用来写开发文档1.1 MCP 是什么一句话解释MCP 的全称是 Model Context Protocol翻译过来就是“模型上下文协议”。你可以把它理解成 AI 应用的一个万能转接头——以前 AI 只能看你复制粘贴给它的文字有了 MCP 之后AI 可以通过一套标准协议去调用外部工具和数据源实时拿到它需要的信息。打个比方如果 AI 是一个新来的实习生以前你给他需求得把资料打印好放在桌上他才能开始干活而有了 MCP他等于拿到了公司所有内部系统的只读账号需要什么资料自己查查完直接出活。Figma MCP 就是这个“内部系统账号”里专门对接 Figma 的那一个它把 Figma 设计文件中的图层结构、样式变量、组件属性、画板尺寸等信息通过标准化的方式暴露给 AI 读取。现在市面上主流的 AI 客户端像 Claude Desktop、Cursor、Codex、Cherry Studio 等都已经支持配置 MCP Server。你只需要把 Figma MCP 作为服务挂上去AI 就具备了“看懂设计稿”的能力。1.2 在“设计交付开发文档”场景下解决了什么传统的设计交付流程本质上是一个“信息搬运”的过程设计师把 Figma 里的尺寸、颜色、圆角、字体一个个抄到文档里或者截图标注后扔给开发。这个过程有三个很明显的问题第一是慢。一套 20 个组件的设计系统光整理色板和字体规范就能花掉一两个小时更别说还要逐个组件填状态、写尺寸说明。第二是容易出错。人工搬运必然有漏项尤其是那些“看起来差不多其实差很多”的灰色、圆角值手一抖就写错了。第三是信息损耗。设计师脑子里清楚“这个颜色用变量 primaryToken”但写文档时可能只写了一个十六进制色值开发拿到的信息和设计稿之间的关联就断了。Figma MCP 解决的是“让机器直接读机器文件”的问题。AI 通过 MCP 读取的是 Figma 的文件结构本身——哪些是组件、用的是什么样式变量、Auto Layout 里 padding 是多少、constraints 怎么设置——这些结构化信息直接进入 AI 的上下文再被整理成开发文档。整个过程不需要设计师手动截图、填表、抄数值准确率也比人肉搬运高得多。1.3 适合谁、不适合谁先说说适合谁。如果你是以下三类人Figma MCP 非常值得试需要高频给前端、客户端、小程序团队交付设计稿的 UI 设计师尤其是设计系统维护者。有一定代码理解能力、希望用 AI 提效但不想一头扎进前端工程化的设计师。前端开发经常需要从设计稿里手动抠参数、希望自动拿规范的人。再说不适合谁。如果你完全零代码基础连 JSON 配置、终端命令都不太想碰那第一次配置 MCP 可能还是会有点门槛建议找团队里的开发帮你搭一次环境之后日常使用其实并不需要碰代码。另外一个不适合的场景是超大设计文件——如果一份 Figma 文件里塞了几百个画板、上千个 Frame直接让 AI 全量读取既慢又容易超 token这种情况需要拆文件或者指定节点去读后面我会讲怎么处理。2. 配置 Figma MCP 之前先搞清楚这 3 个前置条件2.1 准备 Figma 个人访问令牌的正确姿势Figma MCP 要读取你的设计文件需要一个访问令牌Token。获取入口在 Figma 网页版的右上角头像菜单里点击头像 - Settings - Security - Personal access tokens - Generate new token。生成的时候会让你选权限范围务必注意只需要勾选File content: read-only就足够了MCP 读取设计稿只需要只读权限不要为了省事直接勾 All权限越小越安全。生成之后你会拿到一串以figd_开头的字符串这就是你的 Token。关于 Token 有几点要特别注意Token 只显示一次关掉页面之后就再也看不到了一定要先复制保存好丢失了只能重新生成。不要把 Token 截图发到群里、不要提交到 Git 仓库、更不要写死在分享出去的配置里。它就相当于你 Figma 账号的钥匙丢了等于别人能读你的设计文件。如果怀疑 Token 泄露去同一个页面点 Revoke 作废然后重新生成一个。我在实际配置中习惯把 Token 放在 MCP Server 的环境变量里而不是直接写进命令参数这样配置文件和代码库分离相对安全一些。2.2 安装 Figma MCP Server并让 AI 客户端指向它目前常用的 Figma MCP Server 主要有两个来源Figma 官方出的figma-developer-mcp以及社区维护的一些版本。我比较推荐直接用官方的更新及时、接口稳定也是我用下来最省心的。官方安装文档里提供了几种运行方式npx、uvx、Docker。对于大多数普通用户我建议直接用 npx因为它只需要 Node.js 环境不用另外装 Python 或者 Docker。以 Claude Desktop 为例配置文件通常在这个位置macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.json在这个 JSON 文件里添加如下内容{ mcpServers: { figma: { command: npx, args: [-y, figma-developer-mcp, --stdio], env: { FIGMA_API_KEY: figd_你的token } } } }配置好之后重启 Claude Desktop在对话里输入“看看我的 Figma 文件”AI 如果能调起 MCP 工具就说明连接成功了。Cursor 的配置方式类似只是配置入口在 Cursor 的 MCP 设置面板里可以直接通过图形界面添加然后填入同样的命令和环境变量。Codex 的情况稍微有点不一样它支持通过命令行添加 MCP比如codex mcp add figma -- npx -y figma-developer-mcp --stdio添加之后还需要把FIGMA_API_KEY设置到环境变量里再重启 Codex 会话才能被识别到。2.3 Token 权限范围与文件 ID 获取方式经常有人问我“为什么我已经配好了 MCP 但 AI 还是读不到文件”十有八九是文件 ID 或者分享权限出了问题。先看怎么拿文件 ID。打开任何一个 Figma 设计文件看浏览器地址栏https://www.figma.com/design/AbC123xYz/项目名称?node-id123-456其中design/后面、/项目名称前面的那一串字符也就是上面示例里的AbC123xYz就是 file key也就是我们说的文件 ID。如果你的 URL 里有?node-id123-456那123-456就是具体节点 ID可以用它精确定位到某一个画板或 Frame。再注意一个很多人忽视的问题即使你的 Token 权限正确如果 Figma 文件本身的分享权限没有开放给该账号API 也读不到。Figma 文件至少要对你的账号开放 Viewer 以上权限建议直接用你登录 Figma 的账号打开文件后确认右上角能看到文件内容而不是“需要访问权限”的提示页。3. 核心实操用 Figma MCP 自动生成开发文档的完整流程3.1 第一步让 MCP 读取设计稿结构配置完成之后最激动人心的时刻就是把设计稿交给 AI。这里我给你的建议是不要一上来就丢一个超复杂的指令先让 AI 读一遍文件结构确认它能看懂。我用 Claude Desktop 时的第一句指令很简单请读取这个 Figma 文件file key 是 AbC123xYz先帮我把里面的页面和画板结构列出来不要展开细节。AI 会调用 MCP 里的工具去拉取文件信息然后返回类似这样的内容页面列表首页、详情页、个人中心每个页面下的画板名称和数量是否使用了组件库、样式变量等这一步非常关键原因有三第一确认 MCP 工具确实测通了第二让你快速了解文件全貌决定后续是整文件处理还是按节点处理第三给 AI 一个“建立地图”的过程后续让它深挖某个具体画板时它不会迷路。如果你只要某一个页面的内容可以在指令里带上前置的 node-id让 AI 只读取指定节点效率会高很多结果也更干净。3.2 第二步提取样式变量与组件规范结构读完之后就可以进入正题了。让 AI 深入读取设计稿中的样式信息包括颜色、字体、间距、圆角、阴影等。我用的指令大概是这样的继续分析这个文件里所有画板提取以下信息 1. 所有颜色填充的色值如果有命名样式优先使用样式名作为颜色标签 2. 所有文本节点的字体、字号、行高、字重 3. Frame 的 padding、gap、cornerRadius 值整理出常用的间距和圆角规范 4. 组件实例的列表标注组件名称和使用的变体属性。我自己实测的案例一个包含 14 个组件的后台管理页面设计稿AI 用了大约 2 分钟就整理出了 27 个颜色、4 套字体排版、12 个圆角数值还自动标注了哪些颜色使用了设计变量、哪些是硬编码色值。这个信息量如果让我手工在 Figma 里逐个图层去查起码要一下午而且大概率会漏掉几个深色模式下的辅助色。这里有一个细节可以帮 AI 做得更好如果你们团队在 Figma 里已经建立了样式变量Variables尽量在指令里提醒 AI“优先使用样式变量名”这样输出的文档里颜色和字体都会带上变量名开发拿到手可以直接对应到代码里的 Token而不是看到一串十六进制再自己去映射。3.3 第三步自动组装开发文档信息提取完成之后才是真正的“文档生成”。这时候你需要给 AI 一个明确的文档结构要求否则它可能会输出成一段散文式的总结开发根本没法用。我的建议是给 AI 一个清晰的任务描述比如基于你刚才读取到的设计稿内容生成一份 Web 前端开发文档要求如下 1. 设计规范部分色板、字体、间距、圆角、阴影、边框用表格输出 2. 页面与组件清单部分列出所有页面、画板下的组件标注组件类型和用途 3. 组件详情部分每个组件至少包含结构层级、尺寸、状态默认/hover/禁用等、样式 Token、可复用的代码建议 4. 响应式说明部分标注关键画板使用的约束条件和自适应策略 5. 交付注意事项列出开发实现时可能需要和设计再次确认的问题。AI 生成之后你可以直接复制到飞书文档、语雀、Notion 或者 GitLab Wiki 里当作正式交付物发给开发。如果开发用的是 Jira 之类的项目管理工具也可以直接把 Markdown 粘进去基本不需要再做排版。我在实际操作中一份中等规模页面的开发文档从读取设计稿到生成终稿整个流程大约 10 到 15 分钟。对比之前手动截图、标注、填表动辄四五个小时这个效率差距是非常直观的。3.4 给 AI 的提示词模板可以直接抄写提示词这件事我踩过不少坑。最开始我给 AI 的指令太笼统比如“帮我生成开发文档”结果它输出的是一堆正确的废话“这个页面采用了现代化的设计风格使用了圆角卡片布局……”开发看了想打人。后来我总结出一套相对稳定的模板你直接复制改一下就能用请扮演一位资深前端开发者基于下面的 Figma 文件生成一份可直接落地的开发文档。 文件信息 - file key: AbC123xYz - 只需要关注 node-id: 1-234 这个画板 要求 - 按设计系统维度整理颜色、字体、间距、圆角、阴影、边框 - 每个组件列出名称、状态、尺寸、结构层级用缩进表示、样式 Token、可复用的代码建议 - 导出资源部分标注建议格式png/svg/webp - 色板和字体规范用表格输出 - 最后单独列一个“开发前需要确认的问题清单”把设计稿中你觉得语义不明确、可能歧义的地方写清楚。这个模板的核心在于给了 AI 一个明确的角色、明确的文件范围、明确的输出格式并且强制它产出一个“问题清单”。这个“问题清单”特别有用它会把设计稿里那些开发容易产生歧义的地方提前暴露出来相当于让 AI 替你把设计走查了一轮。4. 隐藏技巧普通教程不会写的 Figma MCP 用法4.1 直接生成 React/Vue 代码骨架附带设计标注生成开发文档只是最基础的操作。Figma MCP 真正让我觉得“值回票价”的用法是它能辅助生成组件代码骨架。提示词可以这样写读取这个组件的节点信息输出一个 React Tailwind 的组件代码骨架 - 保持设计稿中的层级结构 - 颜色、圆角、间距使用设计 Token 变量名 - 标出哪些地方需要根据交互状态做条件渲染 - 不要写业务逻辑只要结构和样式骨架。实测下来因为 AI 能看到设计稿里真实的节点层级、Auto Layout 约束和样式值生成的代码骨架还原度比我以前“截图丢给 AI”高很多。以前 AI 看图经常会自己发挥多出一个阴影、少了一个圆角现在它读到的是结构化的设计数据基本能做到“有什么输出什么”。不过我要提醒一句代码骨架只是骨架距离可直接上线的代码还有距离尤其涉及交互逻辑、数据绑定、状态管理的时候仍然需要开发手工介入。但作为初稿它已经能帮开发省掉一大半“照着设计稿敲标签”的时间了。4.2 版本对比自动识别设计变更这个用法可能很多人没想到Figma 文件有版本历史的MCP 可以通过 API 读取不同版本的内容让 AI 来做新旧版本对比自动生成“本次设计变更说明”。指令大概是这样的读取这个文件最近两个版本的页面结构帮我做对比分析 - 列出新增的组件、删除的组件、被修改的组件 - 对每个修改简要说明变化点比如颜色、间距、文案、结构层级 - 输出一份 Markdown 格式的变更说明文档适合直接贴在工单/群公告里。实际用下来这个功能在迭代速度快的团队里非常香。以前每次设计稿有更新开发都会在群里问“这次改了啥”“哪几个页面要重新适配”设计师得一张张截图对比。现在让 AI 读一遍新旧版本几分钟内就能整理出变更清单而且因为基于节点名称和属性做 diff基本不会漏项。需要注意的是如果文件特别大版本对比会消耗比较多的 token建议只指定关键页面或关键组件做对比不必全文件跑。4.3 让 MCP 检查设计稿与代码规范的一致性很多团队有自己的设计 Token 规范比如主色是brand-primary、成功色是success、字体层级是text/heading-1之类。问题是设计稿里并不总是严格使用这些规范偶尔会出现某个地方直接填了一个规范里没有的色值。这种问题以前只能靠设计评审时人工发现或者开发提 bug 时才发现。现在可以让 AI 充当“规范审查员”第一步把团队的规范写在提示词里比如“我们的色板 Token 只有这些primary #1677ffsecondary #f5f5f5danger #ff4d4f……字体规范是……”第二步让 AI 读取设计稿中的实际颜色和字体样式第三步让 AI 输出“不符合规范的清单”列出设计稿中使用了但规范里不存在的色值、字体组合以及出现的具体位置。我试过一次AI 在一个 30 多页的组件库里找出了 7 处未纳入 Token 的硬编码色值还标注了这些色值分别在哪个画板的哪个组件出现。设计师拿着这份清单去规范化比自己单独过一遍文件高效太多了。4.4 文档自动化工作流设计稿更新 → 文档自动同步如果你想更进一步可以把 Figma MCP 结合脚本来实现“设计稿更新后开发文档自动同步”的工作流。目前的实现思路大概是这样用支持 MCP 调用的编程环境或者通过命令行直接调用 MCP Server定时或监听 Figma 文件的版本变化发生更新时自动读取文件内容调用 AI 生成开发文档把生成的文档推送到团队的文档站点飞书、语雀、Notion、Confluence或者直接提交到 Git 仓库的 docs 目录。这个流程的自动化程度取决于你的实际场景。我目前在团队里跑通的是半自动化版本Figma 文件有新版本后由设计师在 AI 客户端里一键触发文档生成然后复制到公司文档站点。完全自动化的版本需要额外写一些胶水代码更适合有开发资源的团队去搭建。做这个工作流有一个前提设计稿必须足够规整。如果图层命名混乱、页面结构随意那 AI 生成的文档质量也会随之下降。换句话说MCP 不会解决脏乱差设计稿的问题它只会把规整设计稿的交付效率放大。5. 常见问题与排查技巧实录5.1 Token 获取不到 / 401 报错如果你在配置完 MCP 之后AI 调工具时报 401 Unauthorized大概率是 Token 的问题。排查顺序如下确认 Token 是否以figd_开头并且完整粘贴到了环境变量里没有多余空格确认生成 Token 时勾选了File content: read-only权限确认 Figma 文件对该账号开放了访问权限确认你的 AI 客户端在读取环境变量时确实加载了FIGMA_API_KEY。有些客户端改了配置后必须完全退出重启才生效不能只刷新窗口。如果以上都正常仍然 401最简单的办法就是重新生成一个新 Token换掉旧的试一试。这个问题我遇到过两次基本都是 Token 权限勾选少了或者复制时漏了后半段。5.2 读取不到文件内容 / 文件 ID 错误AI 能连上 MCP但回复“找不到文件”或者“文件内容为空”这种一般不是 MCP 的问题而是文件 ID 或 node-id 传错了。注意几个细节file key 是design/和/项目名之间的那一段别把项目名当成了 keynode-id 里的格式可能是123-456中间是短横线不是下划线如果你指定了 node-id但这个 node 不是一个画板或者 FrameAPI 可能会返回空结构。这时候不传 node-id让 AI 先读文件整体结构。另外一个冷门但很常见的坑如果你的设计文件是存在 Team Library 里的组件库项目而不是普通设计文件file key 的获取方式是一样的但读取速度可能会更慢因为组件库通常图层非常多。建议把组件库文件按需要拆几个文件来管理或者指定 node 读取。5.3 MCP Server 连不上 / 客户端识别不到这种情况通常是 MCP Server 本身没有启动成功。先在终端里单独验证一下npx -y figma-developer-mcp --stdio如果命令能正常运行不报错说明 MCP Server 本身没问题问题出在客户端配置上。如果命令直接报错大概率是 Node.js 环境没装好或者网络拉取 npm 包失败。客户端识别不到工具的场景大部分是配置文件 JSON 格式出错比如多余逗号、引号不匹配、环境变量路径写错。检查完 JSON 之后重启客户端注意是要完全退出进程不是关闭窗口。Cursor 和 Claude Desktop 在配置变更后都需要彻底重启才会重新加载 MCP Server。如果你用的是 Codex可以通过codex mcp list查看当前已经加载的 MCP Server 列表确认 figma 是否在列表里。如果不在检查添加命令时的参数特别是环境变量有没有同步设置。5.4 AI 生成了看似合理但实际错误的文档怎么防这是我最想强调的一点MCP 提效不等于无人值守AI 生成的内容一定要人工抽查。尤其是颜色、圆角、字号这类精确数值AI 在整理长文档时偶尔会出现错位。我的防错经验有三条第一限制 AI 的读取范围。如果只需要某个页面的文档就用 node-id 圈定范围不要让 AI 读整个文件。读取范围越大混淆的概率越高。第二在提示词里要求 AI 优先使用设计变量名而不是直接给十六进制色值。变量名本身是语义化的AI 不太容易搞混而且开发拿到的信息更接近代码里的 Token 引用。第三生成文档后抽查几个关键值。我习惯重点核对主色、常用文字色、最大的圆角值和默认间距这几个高频参数。如果这几项都对其他小概率错误影响一般不大。有一次 AI 把两个非常接近的灰色值搞混了一个是#f5f5f5一个是#f0f0f0。如果我没抽查出来开发照着做出来的页面在暗色背景下会出现不太明显的色差这种问题在 QA 阶段很难被发现但在用户面前会很显眼。后来我每次生成完文档都会把色板表格和 Figma 里的样式面板快速对照一遍两分钟的事能避免很多返工。5.5 常见问题速查表为了方便你以后快速排查我把上面提到的问题做成了一个速查表现象可能原因处理方式401 UnauthorizedToken 无效或权限不足重新生成 Token确认勾选 File content: read-only找不到文件 / 内容为空file key 或 node-id 错误核对文件 URLfile key 是 design/ 后的字符串MCP Server 启动失败Node 环境问题 / npm 包拉取失败终端单独运行命令验证重装 Node.js客户端识别不到工具配置文件格式错误 / 未完全重启检查 JSON完全退出客户端后重启文档数值错乱读取范围过大 / token 超限限定 node-id分段生成人工抽查关键值读取速度慢文件过大 / 图层过多拆分文件只读取目标画板最后再分享一点我自己实际使用中的体会Figma MCP 不是一个能让设计师一夜之间变成全栈开发的神器它真正解决的是“设计稿信息到开发文档”之间那段低效重复的搬运过程。以前每次交付设计文档就像一封手写信要逐字逐句地写清楚现在更像是在开一个自动化的接口让 AI 直接从数据源里提取要点。坦率地说配置 MCP 的第一个下午可能有点折腾尤其是环境变量、JSON 格式、权限设置这些细碎的东西。但一旦跑通后面每一次设计交付都能省下大块时间。如果你想开始尝试我的建议是从一个小页面、一个组件库子集开始不要一上来就拿着巨型文件去跑。先让 AI 读一个画板生成一份十来行的文档确认输出质量和格式都符合预期再逐步扩展到更多页面。最后一个小技巧给 AI 下指令时尽量把输出格式要求写清楚比如“用表格输出色板”、“列出问题清单”、“标注哪些是硬编码色值”这些明确的约束能让生成结果的质量立刻上一个台阶。别问我怎么知道的都是被一堆“正确的废话”教育出来的。