企业官网建设流程全解析

1. 为什么要在 Cursor 里接 Figma：设计稿到代码的断点在哪

如果你平时用 Cursor 写前端，大概率遇到过这种场景：产品丢过来一个 Figma 链接，你打开一看，间距、圆角、阴影、字体层级全在画板上，但落到代码里还是得靠肉眼量、手动抄。抄错一个padding就要来回对三遍，改到后面自己都烦。

Figma 配置 MCP 服务这件事，本质就是把这个「肉眼量」的环节交给模型。MCP 全称 Model Context Protocol，你可以把它理解成 Cursor 和外部工具之间的一条标准数据通道。Cursor 本身不会读 Figma 文件，但通过一个跑在本地的 MCP 服务，它就能拿到当前选中画板的节点信息、样式、层级结构，然后按你的项目规范生成代码。

这套流程适合谁？我总结下来是三类人：一是经常接设计稿的前端，二是做设计系统、组件库的同学，三是想用 AI 批量把画板转成页面骨架的人。不适合谁？如果你的项目根本没有设计稿，或者设计稿是随手画的草图，那接进来意义不大，模型拿到的信息本身就是乱的。

这里要区分两个东西，很多人第一次配会搞混。Figma 官方在 Cursor 的 Plugins 里提供了一个在线 MCP，走的是 Figma 云端接口，适合 Web 端设计稿；而cursor-talk-to-figma-mcp是本地插件方案，需要在 Figma 桌面端手动导入manifest.json，通过本地 WebSocket 通信。两者不是替代关系，是互补关系。本地这套的好处是能直接操作当前打开的文档，响应更快，也能配合 Skills 和 Rules 做更细的控制。

我试过把两种方式混着用，结果 Cursor 里同时出现两个 Figma 相关的 MCP，模型会犹豫该调哪个。所以建议先明确：你要的是本地实时读取，还是云端链接解析。本文聚焦本地这套，也就是manifest.json+ Bun + Cursor 的完整链路。

整个链路里有三个关键角色。Figma 桌面端负责加载插件、暴露当前文档；Bun 负责跑cursor-talk-to-figma-mcp这个服务，它启动后会开一个 WebSocket 端口并生成一个 channel 随机码；Cursor 通过 MCP 配置连到这个本地服务，拿到工具能力后就能读取设计数据。三者缺一不可，而且顺序不能乱——先起服务，再连 Cursor，最后在 Figma 里确认插件弹窗还开着。

理解了这条链路，后面配置时遇到报错你就能自己定位是哪一环断了。比如 Cursor 里报连接失败，可能是 Bun 服务没起；Figma 里读不到数据，可能是插件弹窗被关了导致随机码失效。下面按顺序把每一步拆开。

2. 前置准备：Bun 运行时与 cursor-talk-to-figma-mcp 环境搭建

在写manifest.json之前，得先把运行环境弄好。这套方案依赖 Bun，不是 Node。Bun 是一个现代化的 JavaScript/TypeScript 运行时，你可以把它当成 Node 的更快替代品，它把运行时、包管理器、打包器都集成在一起了。cursor-talk-to-figma-mcp的setup和socket脚本都是按 Bun 写的，用 Node 跑会出各种模块解析问题。

安装 Bun 分平台。macOS 和 Linux 通用的一键脚本是：

curl -fsSL https://bun.sh/install | bash

macOS 如果你习惯 Homebrew，也可以走官方仓库：

brew tap oven-sh/bun brew install bun

Windows 用户注意，官方推荐在 WSL 里跑上面那条 curl 脚本，直接在 PowerShell 里执行 bash 脚本会失败。装完验证一下：

bun --version

能打印出版本号，比如1.1.x，就说明运行时没问题。这里有个坑我踩过：如果你机器上装了 nvm，并且切过多个 Node 版本，用npm install -g bun装出来的 Bun 有时会因为 PATH 指向旧 Node 的 bin 目录而不生效。表现是bun --version报 command not found，或者版本号对不上。解决办法是优先用 curl 脚本装，装完source ~/.bashrc或重开终端，让 PATH 刷新。

环境好了之后克隆项目：

git clone git@github.com:grab/cursor-talk-to-figma-mcp.git cd cursor-talk-to-figma-mcp

如果你没配 SSH key，用 HTTPS 也行，但原作者提到 HTTP 克隆有时拉不下来，我实测用 SSH 更稳。克隆完进目录，执行初始化：

bun setup

这一步会自动装依赖，并且帮你生成.cursor/mcp.json的初始内容。注意，它生成的是给 Cursor 用的 MCP 配置模板，不是 Figma 的manifest.json，两者别搞混。manifest.json在项目的src/cursor_mcp_plugin目录下，是给 Figma 导入插件用的。

初始化完成后启动 WebSocket 服务：

bun socket

终端会打印出端口号和 channel 随机码，类似3055和o3jmymg2。这两个值先记下来，后面 Cursor 配置和 Figma 验证都要用。这个服务一旦启动就不能关，关了 Cursor 那边立刻断连。建议单独开一个终端窗口挂着，别和 Cursor 共用一个。

到这一步，Bun 环境、项目依赖、本地服务三样都齐了。接下来才是写manifest.json和导入 Figma。

3. 可复制配置：manifest.json 模板与 Cursor MCP 接入片段

这一节是全文最核心的部分，配置写错一个字就连不上。先看 Figma 侧的manifest.json。这个文件在cursor-talk-to-figma-mcp/src/cursor_mcp_plugin/manifest.json，正常情况下克隆下来就已经存在，你不需要从零写。但如果你要改插件名、改 ID，或者想理解每个字段的作用，可以对照下面这份模板：

{ "name": "Cursor MCP Plugin", "id": "cursor-mcp-plugin-local", "api": "1.0.0", "main": "code.js", "ui": "ui.html", "editorType": ["figma"], "networkAccess": { "allowedDomains": ["*"], "reasoning": "Local WebSocket communication with cursor-talk-to-figma-mcp" } }

几个字段说明一下。name是插件在 Figma 里显示的名字，随便改不影响功能。id是插件唯一标识，本地开发用任意字符串即可，不要和已发布的插件冲突。main和ui分别指向插件的逻辑文件和界面文件，这两个文件名必须和目录里实际文件一致，改错会导入失败。editorType限定只在 Figma 里可用。networkAccess是较新版本 Figma 插件必须声明的字段，因为本地 MCP 要走 WebSocket，所以allowedDomains给*，reasoning写清楚用途，否则 Figma 会拦截网络请求。

导入方式：打开 Figma 桌面端，顶部菜单Plugins→Development→Import plugin from manifest...，然后在文件选择框里导航到src/cursor_mcp_plugin目录，选中manifest.json。导入成功后 Figma 会弹出一个插件窗口，窗口里会显示当前连接的 channel 随机码。

这里有个必须强调的点：这个弹窗不能关。随机码是动态生成的，关掉再开就变了，Cursor 那边拿的是旧码，直接连接超时。我见过有人嫌弹窗挡视线随手关了，然后排查半天以为是配置问题。

再看 Cursor 侧的 MCP 配置。bun setup会生成.cursor/mcp.json，内容大致如下，你可以直接复制：

{ "mcpServers": { "cursor-talk-to-figma": { "command": "bun", "args": ["run", "socket"], "cwd": "/你的绝对路径/cursor-talk-to-figma-mcp" } } }

三个关键点。command必须是bun，不是node。args是["run", "socket"]，对应项目里的启动脚本。cwd要填你本地项目的绝对路径，Windows 下路径分隔符用双反斜杠或正斜杠，别直接粘单反斜杠。如果你不想让 Cursor 自己拉起服务，而是手动bun socket已经跑着，那这段配置也可以改成连接已存在的服务，但最简单的方式还是让 Cursor 托管。

配置写完后，在 Cursor 里点Tools & MCP，再点New MCP Server，把上面这段 JSON 粘进去，或者直接编辑.cursor/mcp.json后重启 Cursor。Cursor 会尝试启动这个 MCP 服务，状态变成绿色或显示已连接就对了。

如果你同时要用 Figma 官方在线 MCP，可以在 Plugins 里单独配置，它和本地这套不冲突，但建议一次只启用一个，避免模型调用时选错工具。官方那套走的是链接解析，本地这套走的是当前文档实时读取，用途不同。

配置阶段最容易出问题的是路径和运行时。路径写错，Cursor 启动服务时直接报找不到目录；运行时写成 node，会报模块解析失败。这两类错误在下一节验证时都会具体讲。

4. 验证请求：从 Cursor 读取 Figma 文档信息确认连通

配置写完不代表通了，得实际发一次请求验证。验证的目标很简单：让 Cursor 通过 MCP 读到当前 Figma 文档的信息，如果返回了你画板里的内容，说明整条链路是通的。

操作顺序很重要。先确认bun socket服务在跑，终端里能看到端口和 channel。然后确认 Figma 桌面端里那个插件弹窗还开着，弹窗上显示的 channel 和终端里的一致。最后回到 Cursor，在对话里输入类似这样的指令：

获取当前 Figma 文档信息

如果一切正常，Cursor 会调用 MCP 工具，返回类似Connected to server in channel: o3jmymg2的提示，后面跟着你当前 Figma 文档的节点信息、画板名称、图层结构等。看到这些内容，就证明 Cursor 已经能读到设计数据了。

这里有个细节：channel 随机码一定要对上。终端里是o3jmymg2，Figma 弹窗里也必须是o3jmymg2，Cursor 返回里出现的也应该是同一个。三者不一致，说明某一环拿的是旧码，最常见的原因是 Figma 弹窗被关过又重新打开，或者bun socket重启过但 Cursor 没重新连。

验证通过后，你可以进一步测试读取具体画板。比如在 Figma 里选中一个画板，然后在 Cursor 里说「读取当前选中的画板样式」，模型会返回该画板的尺寸、填充、圆角、字体等信息。这一步能过，说明数据通道不仅通了，还能定位到具体节点。

如果返回的是空或者报错，先别急着改配置，按这个顺序排查：一看bun socket终端有没有报错日志；二看 Figma 弹窗是否还在、channel 是否一致；三看 Cursor 的 MCP 状态是不是已连接。大部分问题出在前两步。

验证成功后，建议马上加两个约束文件，不然模型容易乱来。一个是 Skills，用来告诉模型处理 Figma 时的行为规范：

--- name: Figma UI description: 配合 Figma 使用的技能，当用户使用 Figma 时触发 --- 1. 严格按照设计稿写代码 2. 根据项目结构增加页面，不能随意发挥 3. 严格按照设计稿尺寸实现，兼容不同屏幕 4. 遇到疑问先询问用户，确认后再执行

另一个是 Rules，防止模型反向修改设计稿：

--- name: Figma Rule description: 严格限制 Figma 使用范围 --- 1. 禁止通过 Cursor 修改 Figma 设计稿 2. 禁止在 Figma 连接失败或未连接时自行设计 UI

这两个文件放在项目的.cursor/rules或对应目录下，Cursor 会自动加载。加完之后，模型在读取设计稿时会遵守你的约束，不会出现「设计稿没连上就自己画一个」的情况。

5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth

配置过程中报错是常态，这一节把几个高频错误对照着讲，方便你快速定位。

401 Unauthorized。这个通常出现在你用了 Figma 官方在线 MCP 但没登录账号，或者 token 过期。本地这套cursor-talk-to-figma-mcp一般不会报 401，因为它走的是本地 WebSocket，不涉及云端鉴权。如果你在 Cursor 里看到 401，先确认当前调用的是哪个 MCP。如果是官方那套，去 Cursor 的 Plugins 里重新登录 Figma 账号即可。

local proxy failed。这个报错说明 Cursor 尝试启动 MCP 服务时失败了。常见原因有三个：一是cwd路径写错，Cursor 找不到项目目录；二是command写成了node而不是bun；三是 Bun 没装好或 PATH 不对。排查方法是在终端里手动进到项目目录执行bun run socket，如果手动能跑起来，说明是 Cursor 配置里的路径或命令有问题；如果手动也跑不起来，那是 Bun 环境的问题。

reading 'choices'。这个报错一般出现在模型调用返回结构异常时，本质是 MCP 返回的数据格式和 Cursor 预期的不一致。常见触发场景是bun socket服务中途挂了，Cursor 还在等响应，拿到空数据后解析失败。解决办法是重启bun socket，然后在 Cursor 里重新发起请求。如果反复出现，检查项目依赖是否装全，重新跑一次bun setup。

OAuth 相关报错。这个主要出现在官方在线 MCP 的授权流程里。本地这套不涉及 OAuth。如果你看到 OAuth 报错，说明你在用官方 MCP，需要去 Figma 账号设置里重新授权，或者在 Cursor 的 Plugins 面板里退出重登。

除了这些，还有两个非报错但很坑的现象。一是 Figma 弹窗被关，随机码刷新，Cursor 那边一直超时，表现是请求发出去没反应。二是bun socket服务被终止，比如你关了那个终端窗口，Cursor 立刻断连。这两个都不是配置错误，是运行状态问题，保持服务和弹窗常开就行。

另外提一下模型选择。Cursor 里如果选 Auto 模型，遇到 Figma 这种需要多步工具调用的任务，Auto 有时会判断「需求太大」而拒绝执行。建议手动选一个支持工具调用的模型，比如 Composer 2 Fast，实测响应比较快，也能正常走 MCP 调用链。

排查时养成看日志的习惯。bun socket终端会打印连接、断开、消息收发记录，Cursor 的 MCP 面板也会显示服务状态。两边对照着看，基本能定位到是哪一环断了。

6. 长期使用建议：把 Figma 接入纳入日常编码流

配置跑通只是开始，真正有价值的是把它变成日常习惯。我自己的做法是固定一套启动顺序：先开 Figma 桌面端并导入插件，再开终端跑bun socket，最后开 Cursor 确认 MCP 已连接。三步都绿了再开始干活，避免中途断连返工。

如果你经常做「设计稿转代码」，可以配合 Cursor 的 Plugins 里 Figma 官方提供的三个能力用。implement-design负责把画板落成代码，流程是解析链接、拿设计上下文、截图、处理资源、按设计实现；code-connect-components用 Code Connect 把 Figma 组件和真实代码组件对应起来，适合组件库维护；create-design-system-rules能为你的仓库生成设计系统规则，让生成结果更贴合技术栈。这三个能力可以在 Plugins 面板里按账号启用，和本地 MCP 配合使用。

对于需要长期跑 Agent 任务、频繁调用模型做设计稿解析的场景，可以考虑用 Coding Plan 这类按量方案，比单次调用更划算，适合把 Figma 接入纳入固定工作流的团队。日常只是偶尔转一两个页面的话，按需调用就够了。

最后留一个实用技巧：把常用的 Figma 操作指令存成 Cursor 的快捷提示，比如「读取当前画板并生成 React 组件」「对比设计稿和现有代码的样式差异」。这样每次不用重新组织语言，直接调用，效率会高很多。设计稿和代码之间的那道手工鸿沟，配好这套之后基本就填平了。