企业官网建设流程全解析

1. 为什么要把 Figma 画布接进 Codex/CC

先说清楚一件事：把 Figma 画布接入 Codex 或 Claude Code（下称 CC），本质上是让 AI 编程助手能"看见"你的设计稿，然后基于设计稿直接生成代码、修改组件、对齐样式。这件事在 2024 年下半年开始变得可行，核心原因是 MCP 协议（Model Context Protocol）的成熟——它给 AI 工具开了一个标准化的"外挂接口"，让 AI 能调用外部服务读取数据。

以前的工作流是什么样的？设计师在 Figma 里画完稿，前端工程师对着设计稿量间距、取色值、抄字号，一个页面切图加还原少说半天。有了 Figma MCP 之后，你可以直接对 Codex 说"把这个 Frame 转成 React 组件"，它会通过 MCP 读取 Figma 的节点树、样式属性、布局约束，然后生成对应的代码。这不是概念演示，是已经能跑通的流程。

但这里有个前提：你得把整条链路搭起来。链路大概是这样的——Figma 桌面端或网页端开启 Dev Mode MCP Server，本地跑一个 MCP 服务，Codex/CC 通过配置文件连接到这个服务，然后 AI 才能读取画布数据。任何一环出问题，你看到的都是local proxy failed或者401 unauthorized这类报错。

我写这篇东西的原因很简单：网上关于 Figma MCP 的教程大多是碎片化的，要么只讲 Figma 侧怎么开，要么只讲 CC 侧怎么配，中间那层"为什么连不上"没人讲透。我前后搭了三套环境（macOS、Windows、以及一台 Linux 开发机），踩了不少坑，这里把完整链路和排查思路整理出来。

适合谁看？如果你是全栈或前端工程师，想让 AI 帮你做设计稿还原；如果你是独立开发者，想用 Codex 快速把 Figma 原型变成可运行代码；或者你只是好奇 MCP 到底怎么落地——这篇都能给你一条能走通的路。

注意：本文涉及的 Figma MCP、Codex、CC 均为正常开发工具，所有操作在本地开发环境完成，不涉及任何网络代理配置。

2. Figma 侧的准备：Dev Mode MCP Server 到底怎么开

2.1 版本要求与入口位置

Figma 的 MCP 功能藏在 Dev Mode 里，不是所有版本都能看到。你需要满足两个条件：一是 Figma 桌面客户端（网页版部分功能受限），二是账号有 Dev Mode 权限（付费席位或团队版）。我实测下来，桌面端版本要在 124 以上，Dev Mode MCP Server 的开关才会出现在设置里。

打开路径是这样的：启动 Figma 桌面端，打开任意一个设计文件，右上角切换到 Dev Mode（快捷键Shift + D），然后在右侧面板顶部找到 MCP Server 的图标。如果找不到，去Preferences里搜 "MCP"，确认Enable Dev Mode MCP Server是打开状态。

这里有个容易忽略的点：MCP Server 是按文件开启的，不是全局的。也就是说你在 A 文件里开了，切到 B 文件可能又得重新开一次。我第一次配的时候以为是全局设置，结果在另一个文件里怎么都连不上，排查了半小时才发现是这个原因。

2.2 本地服务端口与连接方式

开启之后，Figma 会在本地起一个 HTTP 服务，默认监听127.0.0.1:3845。你可以用浏览器直接访问http://127.0.0.1:3845/sse看看有没有响应——如果返回一串 SSE 事件流，说明服务是活的。

这个端口是可以改的，在 MCP Server 的设置面板里有个Port输入框。我建议如果你本地 3845 被占用了（比如某些开发工具会占用这个段），改成 3846 或 3850 都行，但改完记得同步更新 Codex/CC 的配置，否则就是经典的"服务在跑但连不上"。

连接方式上，Figma MCP 走的是 SSE（Server-Sent Events）传输，不是标准的 stdio。这意味着你在配置 MCP 客户端时，transport类型要选sse，URL 填http://127.0.0.1:3845/sse。很多人配错就错在这里——用了 stdio 的配置模板，结果一直报连接失败。

2.3 Token 获取与权限范围

关于 "figma mcp token 在哪获取" 这个问题，实际情况是：本地 Dev Mode MCP Server 不需要额外 Token。它依赖的是 Figma 客户端本身的登录态，服务只在本地回环地址上监听，不对外暴露。

但如果你用的是 Figma 的 REST API 方式（比如自己写脚本调/v1/files接口），那就需要 Personal Access Token。获取路径是：Figma 网页版 → 右上角头像 → Settings → Security → Personal Access Tokens → Generate new token。权限范围至少要勾File content和Dev resources读权限。

这两种方式的区别很重要：Dev Mode MCP Server 是给 AI 工具实时读取画布用的，走本地 SSE；REST API 是给脚本批量拉数据用的，走 HTTPS + Token。别把两者搞混，否则你会一直在找"为什么 MCP 配置里要填 Token"——答案是不用填。

提示：如果你在团队环境里，确认管理员没有禁用 Dev Mode MCP 功能。有些企业版策略会默认关闭这个开关，表现就是设置里根本看不到 MCP 选项。

3. Codex 与 CC 的 MCP 配置：配置文件写对才是关键

3.1 Codex 的 MCP 配置结构

Codex 的 MCP 配置放在~/.codex/config.toml（macOS/Linux）或%USERPROFILE%\.codex\config.toml（Windows）。一个能用的 Figma MCP 配置长这样：

[mcp_servers.figma] transport = "sse" url = "http://127.0.0.1:3845/sse"

就这三行，没有 Token，没有额外参数。我第一次配的时候加了一堆command、args字段，结果 Codex 启动直接报配置解析错误——因为 SSE 类型的 server 不需要 command，那是 stdio 类型才有的字段。

配完之后重启 Codex，用/mcp命令（或对应的查看命令）确认 server 状态是connected。如果显示failed，先别急着改配置，去看 Figma 那边的服务是不是还开着——Figma 客户端一关，MCP Server 就停了，这是最常见的"昨天还好好的今天就连不上"的原因。

3.2 CC（Claude Code）的配置差异

CC 的 MCP 配置走的是claude_desktop_config.json或项目级的.mcp.json。结构上和 Codex 类似但字段名不同：

{ "mcpServers": { "figma": { "type": "sse", "url": "http://127.0.0.1:3845/sse" } } }

注意type字段，CC 用的是type而不是transport。这个差异坑过我一次——我把 Codex 的配置直接复制到 CC 里，结果 CC 完全不认，因为它期望的是type。两个工具的配置 schema 不通用，别偷懒复制。

CC 还有个特性：它支持项目级 MCP 配置。你可以在项目根目录放一个.mcp.json，这样团队成员拉下代码就自带 MCP 配置，不用每个人手动配。对于团队协作场景，这个比全局配置实用得多。

3.3 配置生效的验证方法

配完不算完，得验证。我的验证流程分三步：

第一步，确认 Figma 服务活着。浏览器访问http://127.0.0.1:3845/sse，能看到事件流就说明服务正常。

第二步，确认 AI 工具识别到了 server。Codex 里跑/mcp list，CC 里跑/mcp，看 figma 这个 server 在不在列表里，状态是不是 connected。

第三步，实际调用一次。对 Codex 说"读取当前 Figma 选中的 Frame，列出它的子节点"，如果它能返回节点名称和层级，说明整条链路通了。

这三步里任何一步失败，问题定位就很清晰了：第一步失败是 Figma 侧问题，第二步失败是配置问题，第三步失败是权限或数据问题。

4. 那些让人抓狂的报错：逐条拆解与修复

4.1 local proxy failed 系列报错

cc switch local proxy failed while handling codex endpoint /responses这个报错，字面意思是 CC 的本地代理在处理 Codex 的/responses端点时失败了。根因通常不是 Figma MCP 本身，而是 CC 和 Codex 之间的模型路由配置有问题。

我遇到这个报错时的场景是：CC 配置了多个模型 provider，其中一个 provider 的 endpoint 配错了，导致 CC 的本地代理转发请求时找不到目标。修复方法是检查 CC 的 provider 配置，确认每个 provider 的base_url和api_key都是有效的。

如果报错里带了upstream_status: http 400和reasoning_content in the thinking mode must be passed back，那是模型侧的问题——某些推理模型要求把 thinking 内容回传，但客户端没传。这个和 Figma MCP 无关，是模型调用层的事，需要检查你用的模型是否支持当前客户端的调用方式。

4.2 401 unauthorized 的排查路径

unexpected status 401 unauthorized出现在 MCP 场景下，通常意味着认证失败。但前面说了，本地 Figma MCP 不需要 Token，那 401 从哪来？

两种可能：一是你连的根本不是本地 MCP，而是某个需要认证的远程服务；二是你的 AI 工具本身没登录或登录态过期。我遇到过一次是 CC 的账号登录过期了，但它报的是 MCP 相关的 401，误导了我半天。后来重新登录 CC 就好了。

排查顺序建议：先确认 AI 工具本身登录正常（能正常对话），再确认 MCP URL 指向的是127.0.0.1而不是某个远程地址，最后检查 Figma 客户端是不是登录状态。

4.3 404 not found 与端口占用

unexpected status 404 not found: cc switch local proxy failed这个组合报错，八成是端口对不上。Figma MCP Server 实际监听的端口和你配置里写的端口不一致，请求打到了错误的端口上，自然 404。

怎么确认实际端口？在 Figma 的 MCP Server 设置面板里看Port字段的值，或者用lsof -i :3845（macOS/Linux）/netstat -ano | findstr 3845（Windows）看端口占用情况。如果 3845 被别的进程占了，Figma 可能会自动换端口，但配置里还是旧的，就对不上了。

我的做法是固定端口：在 Figma 设置里手动指定一个不常用的端口（比如 3855），然后配置里写死这个值，避免自动分配带来的不确定性。

4.4 Windows 上的虚拟化平台报错

claude's workspace requires the virtual machine platform on windows这个报错和 MCP 没直接关系，是 CC 在 Windows 上需要虚拟化平台支持。开启方法：控制面板 → 程序和功能 → 启用或关闭 Windows 功能 → 勾选虚拟机平台和Windows Subsystem for Linux，重启后生效。

这个坑的隐蔽性在于：它报错的时候你可能正在配 MCP，会误以为是 MCP 配置问题。实际上 CC 的某些功能依赖 WSL2，没开虚拟化平台就跑不起来。先把这个基础环境搞定，再谈 MCP。

5. 从画布到代码：实际使用中的技巧与边界

5.1 什么样的 Frame 适合直接转代码

不是所有 Figma 设计稿都适合丢给 AI 转代码。我实测下来，适合的 Frame 有几个特征：用了 Auto Layout、命名规范（不是Frame 123这种）、组件化程度高、没有复杂的矢量插画。

Auto Layout 是关键。因为 AI 读取的是布局约束信息，如果设计稿是绝对定位堆出来的，AI 生成的代码也会是一堆position: absolute，维护性极差。而 Auto Layout 对应到代码里就是 flex 布局，生成质量高很多。

命名规范也很重要。一个叫Button/Primary/Default的组件，AI 能直接生成PrimaryButton组件；一个叫Rectangle 47的图层，AI 只能瞎猜。花十分钟整理命名，能省后面一小时的返工。

5.2 提示词怎么写才能拿到可用的代码

直接说"把这个 Frame 转成代码"效果一般。我的提示词模板是这样的：

读取 Figma 当前选中的 Frame，分析它的布局结构（Auto Layout 方向、间距、对齐方式）， 然后生成一个 React + Tailwind 的组件。要求： 1. 用语义化的组件名，基于 Frame 的命名 2. 间距用 Tailwind 的 spacing scale，不要写死 px 3. 颜色提取成 CSS 变量 4. 响应式断点参考 Frame 的约束设置

这样 AI 拿到的指令是结构化的，生成结果可用度高很多。关键是第 2 点——让它用 spacing scale 而不是写死 px，这样生成的代码和设计系统能对齐。

5.3 MCP 读取的数据边界

Figma MCP 能读到什么、读不到什么，这个边界得清楚。它能读：节点树、布局属性、样式（颜色、字体、圆角、阴影）、组件实例关系、文本内容。它读不到：交互原型逻辑、动效参数、设计意图（为什么这么设计）。

所以别指望 AI 能理解"这个按钮点击后要跳转到详情页"——那是交互逻辑，不在画布数据里。你得在提示词里补充这些信息。MCP 解决的是"长什么样"的问题，不是"怎么动"的问题。

另外，复杂组件（比如带嵌套实例的 Design System 组件）读取时可能会有层级丢失。我的经验是：如果组件嵌套超过三层，先在设计稿里 flatten 一下，或者分块读取，别一次性丢给 AI。

6. 多工具协同：Codex、CC、Trae 的 MCP 复用思路

6.1 一套 Figma 服务，多个客户端共用

Figma MCP Server 是本地 HTTP 服务，这意味着它可以同时被多个客户端连接。你可以在 Codex 里配一份，在 CC 里配一份，在 Trae 里再配一份，它们连的都是同一个http://127.0.0.1:3845/sse，互不干扰。

这个特性很实用：比如你用 Codex 做代码生成，用 CC 做代码审查，两个工具都能读同一份设计稿数据，不用来回切换 Figma 文件。我现在的习惯是 Codex 负责"从设计稿生成初版代码"，CC 负责"对照设计稿检查还原度"，形成一个小闭环。

6.2 配置文件的统一管理

多工具配置的痛点是：Figma 端口一改，三个配置文件都得改。我的做法是写一个简单的同步脚本，把端口值抽成一个环境变量，配置生成时动态替换。

#!/bin/bash FIGMA_MCP_PORT=${FIGMA_MCP_PORT:-3845} # 生成 Codex 配置 cat > ~/.codex/config.toml <<EOF [mcp_servers.figma] transport = "sse" url = "http://127.0.0.1:${FIGMA_MCP_PORT}/sse" EOF # 生成 CC 配置 cat > ~/.claude/claude_desktop_config.json <<EOF { "mcpServers": { "figma": { "type": "sse", "url": "http://127.0.0.1:${FIGMA_MCP_PORT}/sse" } } } EOF

这样改端口只需要改一个环境变量，重跑脚本就行。虽然简单，但省去了每次手动改三个文件的麻烦。

6.3 什么时候该用 MCP，什么时候该用截图

MCP 不是万能的。有些场景下，直接截图丢给 AI 反而更快：比如设计稿里有大量自定义插画、渐变、复杂阴影，MCP 读取的样式数据 AI 未必能准确还原，不如截图让它"看着办"。

我的判断标准是：如果设计稿是标准组件拼的，用 MCP；如果设计稿有大量视觉创意元素，用截图 + 文字描述。MCP 的优势在于精确读取布局和样式数值，截图的优势在于 AI 能理解整体视觉意图。两者结合用效果最好。

7. 我踩过的几个真实坑与最终稳定方案

第一个坑是 Figma 客户端更新后 MCP 开关重置。有一次 Figma 自动更新到新版本，我打开文件发现 MCP Server 又关了，配置没动但就是连不上。后来养成习惯：每次 Figma 更新后，第一件事是检查 MCP Server 开关状态。

第二个坑是端口冲突导致的间歇性失败。我本地有个开发服务偶尔会占用 3845，导致 Figma MCP 时好时坏。表现是"有时候能连有时候不能"，特别难排查。后来固定用 3855 端口，再没出现过这个问题。

第三个坑是 CC 和 Codex 同时连接时的资源竞争。两个客户端同时高频读取 Figma 数据时，偶尔会出现响应超时。我的解决方案是错开使用——生成代码时用 Codex，审查时用 CC，不同时跑。

最终我的稳定方案是：Figma 桌面端固定开 MCP Server 在 3855 端口，Codex 和 CC 各配一份 SSE 连接，用一个同步脚本管理配置。日常使用中，Codex 负责生成，CC 负责审查，Figma 画布保持打开状态。这套方案跑了两个月，除了 Figma 更新时需要重新开一下开关，没再出过其他问题。

如果你刚开始搭，我的建议是先用最简配置跑通一条链路（Figma + Codex），确认能读取数据了，再往上加 CC 或其他工具。一次性配一堆，出问题的时候根本不知道是哪一环的锅。