Claude Code + Figma MCP：设计稿自动转HTML完整指南

干前端第七年我终于把“手动切图”这个动作从日常流程里彻底删掉了。以前拿到设计稿先要在 Figma 里量间距、取色值、导出切片再手动还原成 HTML一个落地页怎么也得磨上大半天。现在我的做法是Claude Code 负责写代码Figma MCP 负责把设计稿里的图层和样式信息直接喂给 Claude Code最终一键产出结构干净的 HTML 页面。这套组合适合每天跟设计稿打交道的前端工程师也适合一个人干所有活的独立开发者。这篇文章就把整套工作流的搭建、实操和踩坑记录完整写下来照着做基本就能跑通。1. 这套工作流到底解决了什么问题1.1 传统“切图-标注-还原”流程的痛点先说说为什么非要折腾这条链路。手动还原设计稿的痛点做前端的人都懂量间距、取色值、导切片、看图层的隐藏状态这些动作又碎又重复。一个中等复杂度的落地页光设计还原就能吃掉 4 到 6 个小时其中真正“写代码”的时间可能只占一半另一半全耗在跟设计稿“对齐”上。更烦的是设计改版。设计师改一个按钮颜色、调两处间距你就要重新取色、重新量尺寸、重新核对圆角。如果页面里有十几个模块改一版就意味着把之前的重复劳动再走一遍。还有一个隐藏成本是“信息损耗”——设计稿里的自动布局、约束关系、组件状态靠肉眼和手动测量很难完整传递到代码里还原出来的页面经常出现“看着差不多细看差很多”的情况。我试过的常规解法是各种“设计稿转代码”工具和平台它们对简单卡片、静态布局确实有效但一碰到复杂的组件状态、自定义字体、特殊交互生成结果基本没法直接用最后还得回炉重写。问题出在它们通常是一锤子买卖把设计稿当图片识别而不是把它当结构化的数据来读。而 Claude Code 加 Figma MCP 这条路线最大的不同就是它真的“读”到了设计稿内部的图层树、样式参数和约束信息而不是靠猜。1.2 Claude Code 和 Figma MCP 各自扮演什么角色先拆解一下这两个东西。Claude Code 是 Anthropic 官方的命令行编程代理装好之后直接在终端里敲claude就能进入交互界面。它能读文件、改文件、执行命令也能调用外部工具本质上是把大模型的能力接进了本地开发环境。你给它一个任务它会像同事一样一步步拆解、执行、检查而不是只给你一段代码让你自己去贴。Figma MCP 则是连接 Figma 的“桥梁”。MCP 的全称是 Model Context Protocol简单理解就是一个让 AI 工具对接外部数据的通用协议相当于给 Claude 装了一个标准的“数据接口”。Figma 官方的figma-developer-mcp服务器通过 Figma API 读取设计稿里的图层树、节点属性、样式定义和图片资源然后把这些信息暴露成一个个工具供 Claude Code 调用。打一个比方Claude Code 是厨师Figma MCP 是传菜员传菜员把设计稿这盘“菜”的完整配方端到厨师面前厨师只需要照着配方做不用自己跑去后厨翻食材。这条链路成立的关键在于Figma 文件本质上是一份结构化数据每个图层、每个文本节点、每个样式属性都有明确的参数。MCP 服务器把这些参数原样取出来交给 Claude CodeAI 拿到的不是“一张图片”而是“这个按钮宽 120 像素、圆角 8 像素、背景色 #2563EB、文字加粗”这样的精确信息。这也是它比传统切图工具还原度更高的根本原因。2. 环境准备从零装好 Claude Code 和 Figma MCP2.1 安装 Claude Code 的两种方式我实测下来最省事的安装方式是 npm 全局安装。先确认本机有 Node.js 环境版本建议在 18 以上装完后在终端执行node -v npm install -g anthropic-ai/claude-code claude --version安装完成后在项目目录里直接运行claude就会启动交互式会话。首次使用需要登录你的 Claude 账号终端里会弹出授权链接用浏览器打开确认一下就行。如果你对 npm 全局包有顾虑也可以用原生安装脚本但我个人觉得 npm 方式最好维护升级时执行npm update -g anthropic-ai/claude-code就搞定。有一点提醒Claude Code 是在本地跑的它读写的是你当前目录下的文件所以最好在项目根目录里启动它。这样它生成的 HTML、CSS、图片资源都会落在项目目录里后续管理也方便。我一般会为每个设计稿单独建一个文件夹里面放index.html、styles、assets这几个子目录让 Claude Code 在这个范围内活动。2.2 获取 Figma API Key要让 MCP 服务器能读你的设计稿需要一个 Figma 的个人访问令牌。打开 Figma 的账号设置进入 Security 页面找到 Personal access tokens点 Generate new token给它起个名字然后在权限范围里勾选file_content:readonly。这里注意只需要这一个只读权限就够了别勾写权限安全第一。生成之后把 token 复制下来保存好——这个值只会显示一次关掉页面就再也看不到了。提示如果你是帮团队维护设计稿最好用独立的服务账号建 token避免个人账号离职后整个链路失效。自己单干的话用自己的账号就行。2.3 把 Figma MCP 接入 Claude Code拿到 token 之后在终端执行claude mcp add figma -- npx figma-developer-mcp --figma-api-key你的KEY claude mcp listclaude mcp add就是把 MCP 服务器注册给 Claude Codefigma是给这个服务起的名字后面跟的是启动命令。默认情况下这个配置是项目级的只对当前项目生效如果想让所有项目都能用可以加--scope user参数。执行完claude mcp list能看到 figma 状态是 connected就说明注册成功了。然后重新启动claude第一句话可以问它“你现在可以调用哪些 figma 工具分别有什么用”正常情况下它会列出 get_file、get_node、get_image 这类工具并说明各自用途。到这一步环境就准备好了。提示claude mcp add之后的配置存在项目目录下的.mcp.json或全局配置里。如果之后提示找不到服务器先执行claude mcp list看状态再执行claude mcp get figma查看详细配置。3. 实操从设计稿到 HTML 的完整流程3.1 第一步把设计稿的文件 Key 交给 ClaudeFigma 文件的 URL 长这样https://www.figma.com/design/AbCdEfGhIjKlMnOpQrStUv/项目名称?node-id0-1URL 里design/后面那串AbCdEfGhIjKlMnOpQrStUv就是文件 Key。把设计稿在 Figma 里打开复制这个 URL然后在 Claude Code 会话里说读取这个 Figma 设计稿文件 Key 是 AbCdEfGhIjKlMnOpQrStUv 先列出里面所有页面Page和画板Frame的名称与节点 ID。Claude Code 会调用 get_file 工具拿到文件元数据再把页面结构整理给你。对于文件特别大的情况我建议直接从 URL 里的node-id入手只让它读目标画板避免一次拉太多信息。比如 URL 里 node-id 是 0-1就可以说“只读取 node-id 为 0-1 的这个画板”这样 Claude 的上下文窗口不会被无关图层塞满回答也更专注。这一步是整个流程的入口也是最容易被忽略的一步。很多人上来就说“生成这个设计稿的 HTML”但 Claude 根本不知道你指的是哪个文件、哪一屏内容必须先明确文件 Key 和节点范围。3.2 第二步提取设计规范生成 CSS 变量画板信息拿到手之后下一步不是急着写结构而是先让 Claude 把设计稿里的“设计规范”提取出来。我会这样问读取这个画板里所有文本节点和样式定义 把颜色、字号、字重、行高、间距、圆角、阴影整理成一套 CSS 变量 按设计稿里实际使用的值来不要自己发挥。Claude 会调用 get_node 拿到各个节点的详细属性然后汇总输出一段类似下面的内容:root { --color-primary: #2563EB; --color-bg: #F8FAFC; --color-text: #0F172A; --color-muted: #64748B; --font-size-h1: 32px; --font-size-body: 16px; --spacing-lg: 24px; --spacing-md: 16px; --radius-lg: 12px; --radius-sm: 6px; --shadow-card: 0 4px 12px rgba(0, 0, 0, 0.08); }这一步的价值在于把“设计规范”和“页面结构”解耦。后面无论页面怎么改只要颜色、字号这类全局变量不动整体风格就不会跑偏。而且这套 CSS 变量是直接从设计稿取值生成的比我肉眼取色准得多尤其是一些接近黑白的灰色肉眼根本分不清 #F8FAFC 和 #F9FAFB 的区别但 AI 读取的数值不会有偏差。我习惯让 Claude 把 CSS 变量单独存到styles/tokens.css文件里和页面样式分开放后续维护时一眼就能找到所有可配置项。3.3 第三步图片和图标资源自动导出页面里的图片、图标这类资源也是让 Claude 通过 MCP 工具导出的。我一般这样要求把画板里所有图片节点导出到 assets/ 目录 图标用 SVG 格式照片用 PNG 格式导出的尺寸跟设计稿一致。figma-developer-mcp 提供的 get_image 工具支持按节点 ID、格式、尺寸导出图片。Claude 会遍历图层树找出所有图片节点逐个调用导出接口。这里有一个重要的取舍图标类资源尽量导出 SVG体积小而且缩放不糊位图类资源按设计稿标注的 1 倍或 2 倍尺寸导出避免后面做响应式时图片发虚。提示如果设计稿里的资源特别多一次全部导出很容易触发超时或上下文过长。我会按模块分批处理比如“先导出 Hero 区域的图片和图标再导出下一个模块”。分批处理虽然多聊几句但整体更稳。3.4 第四步生成完整 HTML 页面并迭代设计规范和资源都齐了接下来就是让 Claude Code 生成页面本体。我会给一个尽量具体的提示把结构、语义、响应式、可访问性都写进去根据设计稿生成一个完整的 index.html 要求 1. 使用语义化标签header、main、section、footer 2. 引用 styles/tokens.css 里的变量 3. 页面宽度最大 1200px 居中栅格用 CSS Grid 4. 移动端适配768px 以下改为单列 5. 图片使用 assets/ 目录下导出的文件 6. 为一个模块补充合适的交互比如表单校验或菜单展开Claude Code 会根据前面读取的图层结构把设计稿的布局还原成 HTML 结构。以一张特性卡片模块为例它生成的结构大致是这样section classfeatures h2 classfeatures__title核心能力/h2 div classfeatures__grid article classfeature-card img srcassets/icon-speed.svg alt高速图标 classfeature-card__icon / h3 classfeature-card__title毫秒级响应/h3 p classfeature-card__desc基于边缘节点分发首屏加载速度提升 80%。/p /article /div /section生成之后我会直接在浏览器里打开预览然后对着设计稿检查把发现的问题反馈给 Claude Code。比如“标题字号比设计稿大了 4 像素”“卡片间距应该是 24 像素”“这个区域缺一个背景分隔线”它会在原基础上做局部修改而不是整页重来。整个迭代过程一般会走三四轮第一轮看整体布局第二轮抠间距和字体第三轮检查响应式和交互细节。实测下来一个包含五六个模块的落地页从设计稿到基本可用的 HTML大概在半小时以内就能完成而且修改成本远低于手写。4. 常见问题与排查技巧实录4.1 MCP 认证失败401 和 403跑这套流程最常见的错误是 Figma 接口返回 401 或 403。401 基本是 token 没生效403 多半是权限范围不够。我的排查顺序是先检查claude mcp get figma看启动命令里 token 是否完整再去 Figma 后台确认 token 没被删、权限是否包含file_content:readonly。这里有个容易踩的坑Figma 的 token 有时效设置如果你当初设置过一次性的 token过期之后整套流程就会静默失败。我后来习惯把 token 存到本地环境变量里启动命令改成从环境变量读取claude mcp add figma -- npx figma-developer-mcp --figma-api-key$FIGMA_API_KEY这样 token 不写死在配置文件里换机器、换 token 都只改一处。4.2 图层太多导致上下文被撑爆设计稿一复杂图层数量轻松上千。如果直接让 Claude 读取整个文件它可能在处理到一半时上下文窗口就不够了表现为回答变慢、漏掉模块、或者开始“编造”设计稿里不存在的内容。遇到这种情况处理思路是缩小作用域优先用node-id指定画板只读当前要还原的区域让 Claude 按模块分批处理生成一个模块后再进入下一个把已经导出的 CSS 变量单独存文件后续会话通过读取文件来复用而不是每次重新提取这也是我前面反复强调分批处理的原因。AI 工具不是越快越好而是要把它的工作范围控制在一个它能稳定处理的量级。4.3 字体、间距还原不准如果你发现生成的页面跟设计稿有偏差先别急着怪 AI多数情况是输入信息不够全。比如设计稿里用了某个特殊字体本机没装浏览器就会回退成默认字体看起来跟设计稿差很多。我的做法是让 Claude 先检查所有文本节点的字体名称如果是系统常见字体Inter、PingFang SC、微软雅黑直接用系统字体栈如果是品牌定制字体就让 Claude 在 HTML 里引入对应的 web font或者让设计师提供字体文件放进assets/fonts/目录。间距偏差则多半是设计稿用了自动布局Auto Layout某个容器里有 padding 和 gap仅靠肉眼看不容易识别。这种时候我会让 Claude 用 get_node 重新读取那个容器节点的布局属性把 padding、gap、margin 的数值逐个打出来核对。4.4 图片导出超时或文件过大设计稿里如果有高清大图一次导出多个节点容易超时。我的应对策略是需要 2 倍图的资源单独导出普通装饰图用 1 倍图图标一律用 SVG。如果导出的 PNG 文件过大会让 Claude 在处理时调用压缩工具或者直接用在线图片压缩服务压一遍再放进assets/。4.5 问题排查速查表现象常见原因解决办法MCP 工具返回 401token 无效或过期重新生成 token检查启动命令工具返回 403权限范围不足确认勾选 file_content:readonlyClaude 说找不到图资源没导出或路径写错用 get_image 导出后核对 assets 目录页面字体跟设计稿不符设计稿用了定制字体引入 web font 或替换为系统字体栈间距、圆角肉眼看着不对自动布局参数没被读取让 Claude 重读容器节点布局属性比对 padding 和 gap生成到一半上下文不够图层太多、范围太大用 node-id 锁定画板按模块分批生成图片导出超时大图一次导太多分批导出装饰图降为 1 倍图标用 SVG5. 几点实操体会跑通这套流程之后我最大的感受是它不是把设计师和前端之间的协作变成零而是把最枯燥的“搬运”工作交给了 AI让人把精力留给真正需要判断的事——比如模块的交互方式、不同屏幕下的布局策略、可访问性这些设计稿不会直接告诉你的东西。我个人的建议是别一上来就让它还原一个 30 个模块的复杂官网先拿一个三五张卡片的落地页练手。跑通一遍流程你就知道它擅长什么、在哪个环节容易翻车后面再放大项目就有底了。还有一个小技巧把常用需求写进项目里的 CLAUDE.md比如“生成代码时优先使用语义化标签”“图片必须加上 alt 属性”“CSS 变量统一放在 tokens.css”Claude Code 每次启动都会自动读取省得每次重复交代。最后想说的是这套链路对静态页面和中等复杂度的组件页面效果最好那种涉及复杂状态管理、交互动效高度定制的页面还是得靠人来主导AI 负责把骨架和视觉基础先搭好——对我来说这已经能省下每天最宝贵的两小时了。