awdr74100/figwright · 上手攻略

  • 仓库：awdr74100/figwright
  • 链接：https://github.com/awdr74100/figwright
  • 分类：AI Coding · 设计协同
  • 作者：Tom
  • 更新：2026-09-30

一、是什么

Figwright 是一个免费、双向的 Figma MCP（Model Context Protocol）服务器，让 AI 编程代理（Claude Code、Cursor、Codex 等 MCP 客户端）可以直接读写 Figma 设计文件——而不只是"查看"设计图。

核心原理：Figwright 在你的机器上本地运行一个 MCP 服务器，通过 WebSocket 与 Figma 桌面端的插件通信。整个链路跑在本地，不上传任何设计数据。

关键特点： - 免费（Figma 官方 Dev Mode MCP 需要付费 Dev Mode 席位；Figwright 只需免费桌面版） - 双向：不是只读的——115 个工具覆盖读写 Figma 画布 - Provider-first 代码生成：自动识别你的技术栈（React/Vue/纯 CSS 等）和现有组件，生成复用你已有 tokens 和 icons 的代码 - 多代理支持：多个 AI 代理可以同时工作，每个代理操作各自独立的 Figma 文件

二、解决什么问题

传统 Figma + AI 编程流程的痛点：

  1. 只读限制：官方 Figma MCP（或 Figma 官方 Dev Mode MCP）大多是读图，AI 只能"参考"设计，无法反向写回
  2. 付费门槛：Figma 官方 MCP 需要 Dev Mode 付费席位（月费 12~15 美元起）
  3. 代码脱节：即使能读 Figma，生成的代码也是通用 HTML/CSS，与实际项目组件/tokens 脱节
  4. 代理冲突：多个 AI 代理操作同一个 Figma 文件时，容易互相覆盖彼此的改动

Figwright 通过本地 WebSocket relay + 115 个 MCP 工具，让 AI 代理真正成为 Figma 的"协作者"而非旁观者。

三、快速安装

环境要求

  • Node.js：20.19+ 或 22.12+（⚠️ 注意：Node 18/21 和 22.0~22.11 不支持）
  • Figma 桌面端：免费版足够（必须使用桌面端，因为插件需要导入）
  • MCP 客户端：Claude Code、Cursor、Codex 或其他支持 MCP 的客户端

步骤 1：配置 MCP 客户端

在项目的 .mcp.json 文件中添加（以 Claude Code 为例）：

{
  "mcpServers": {
    "figwright": {
      "command": "npx",
      "args": ["-y", "@figwright/mcp@latest"]
    }
  }
}

⚠️ 如果遇到 command not found 错误，说明客户端的 PATH 里找不到 npx。需要用绝对路径： json { "mcpServers": { "figwright": { "command": "/Users/you/.local/share/fnm/node-versions/v24.x.x/installation/bin/npx", "args": ["-y", "@figwright/mcp@latest"] } } } 在终端运行 which npx 获取本机路径。

步骤 2：安装 Figma 插件

官方暂未上架 Figma Community，需手动导入：

  1. 进入 GitHub Releases 页面 下载最新插件 zip 并解压
  2. Figma 桌面端：Menu → Plugins → Development → Import plugin from manifest… → 选择解压出的 manifest.json

步骤 3：验证连接

  1. 在 Figma 中打开：Plugins → Development → Figwright，插件面板应显示 Connected
  2. 在 AI 客户端中运行： ping 若返回成功响应，说明链路打通。

步骤 4：（可选）安装 Skills 以增强 AI 代理工作流

npx skills add awdr74100/figwright/skills

Skills 包含两个工作流： | Skill | 用途 | |---|---| | figma-codegen | 把 Figma 选区转为框架感知代码，复用现有组件和 tokens | | figma-build | 根据代码或描述在 Figma 中构建设计，复用文件已有组件和样式 |

⚠️ Skills 需要 @figwright/mcp 服务器已连接，独立安装 Skills 不产生任何工具。

四、核心用法

读取设计上下文（Read）

当选中 Figma 中某个 frame 后，告诉代理：

Code this Figma selection as a React component.

代理会自动调用 get_design_context 获取结构化数据，结合 component_map / token_map / icon_map 将 Figma 数据对接到你的代码库。

核心读取工具：

工具 作用
get_design_context 获取忠实、去重的设计上下文（布局、字体、变量、组件）
get_screenshot 获取视觉参考截图
get_component_map 将 Figma 组件映射到代码库对应组件
get_token_map 将 Figma 变量/Token 映射到代码库
get_icon_map 将 Figma 图标映射到代码库已有图标
design_diff 对比设计变更与代码基准，只更新受影响的部分

写入 Figma（Write）

告诉代理：

Build a pricing section in Figma from this spec.

代理调用写工具直接在画布上创建和编辑元素。

核心写入工具：

工具 作用
create_frame / edit_frame 创建和编辑 Frame
create_text / edit_text 创建和编辑文本
create_shape / edit_shape 创建和编辑图形
set_auto_layout 设置自动布局
create_component / edit_component 创建/编辑组件（含 boolean/text/instance-swap 属性）
set_variables 操作 Figma 变量
apply_batch 批量应用多个编辑，一次性落盘
create_motion 创建 Motion 动画（关键帧、预设、时间线）

典型命令速查

# 查看所有可用工具（MCP 客户端连接时会列出完整目录）
# 推荐先确认工具列表是最新的权威目录
ping

# 获取设计上下文（选区）
get_design_context

# 获取截图
get_screenshot

# 批量写入（一次性应用多个编辑）
apply_batch

五、典型适用场景

  1. Design-to-Code 自动化：设计师在 Figma 调好 UI，AI 代理直接生成对应 React/Vue 组件代码，复用项目已有 tokens 和图标
  2. Code-to-Design 自动化：产品经理/设计师给出 PRD 描述，AI 代理在 Figma 中快速生成设计稿
  3. 多代理并行 UI 开发：多个 AI 代理各自操作独立的 Figma 文件，并行开发不同页面/模块
  4. 设计系统维护：设计 token 变更后，AI 代理自动对比 design_diff 并只更新受影响的代码文件
  5. AI 设计审查：AI 代理读取 Figma 设计，验证实现代码是否忠实于原始设计意图

六、坑与注意

⚠️ 坑点清单

  1. Node.js 版本严格限制：仅支持 Node 20.19+ 和 22.12+；Node 18/21 和 22.0~22.11 均不兼容。如果你的项目用其他 Node 版本运行，Figwright server 本身需要独立环境（npx 方式不受项目 Node 版本影响，但环境要装对）

  2. 必须使用 Figma 桌面端：不支持 Figma Web 版，因为插件需要本地导入和 WebSocket 通信。Figma 免费桌面版即可，无需付费 Dev Mode

  3. 插件不在 Figma Community：每次更新需手动从 GitHub Releases 下载新 zip 并重新导入，比官方市场插件多一步

  4. npx 不在 PATH 时连接失败：AI 客户端通常在隔离环境运行，如果找不到 npx 会报 command not found。必须使用绝对路径或配置 env.PATH

  5. 多代理写同一文件会冲突：虽然支持多代理，但"一个代理对应一个 Figma 文件"。同一文件被两个代理同时写会互相覆盖——切换标签页不会自动隔离代理

  6. 写权限依赖 Figma 文件权限：Figma 只读权限下，AI 代理只能读不能写

  7. 设计变更追踪需手动保存基准：design_diff 需要先保存一个代码基准才能对比，没有自动建立基准的机制

  8. Skills 需要手动 npx skills add：Skills 不是装好 Figwright 就自动加载的，需要单独安装且仅在 MCP 连接状态下生效

七、与同类对比

Figwright Figma 官方 Dev Mode MCP Figma REST API + 代理
费用 免费 需 Dev Mode 付费席位 免费
读写方向 双向（读+写） 主要读取（设计审查） 需自己封装，读写都复杂
工具数量 115 个 较少 需要自己实现
代码生成质量 Provider-aware，复用项目组件/tokens 通用代码生成 无
多代理支持 ✅ 原生支持 ❌ ❌
本地运行 ✅ 完全本地 ❌ ❌（需云端中转）
无需 Figma 桌面端 ❌ 必须桌面端 ✅ 官方支持 ✅
技能生态 Skills 体系（可 fork/安装） 无 无

结论：如果你是 AI Coding 深度用户（Claude Code / Cursor），需要 AI 代理真正写回 Figma 而不是只读设计，Figwright 是目前免费生态里最完整的方案。Figma 官方 MCP 更适合纯"设计到代码"的单向场景，以及不需要 AI 写回的情况。

八、一句话推荐结论

在 Figma 免费版上实现 AI 代理双向读写设计——Figwright 是目前门槛最低、能力最完整的开源方案，尤其适合 Design-to-Code 自动化流程和 Design System 维护场景。