企业官网建设流程全解析

前阵子有个朋友问我，怎么让 AI 直接帮忙改 Figma 设计稿，而不是每次都导图、截图、对着标注一点点描述需求。我第一反应是：用官方 MCP 插件啊。结果他一句话给我噎回来了——那玩意要付费套餐才开放，个人项目、小团队根本不想花这个钱。后来我翻了一圈社区方案，发现有个思路特别讨巧：Local Figma Agent MCP。简单说，就是在本地跑一个轻量代理服务，把 Figma 的文档树、节点属性、样式信息暴露成 MCP 工具，让 Codex 这类 Agent 不仅能看懂设计稿结构，还能真动手改文本、改颜色、甚至批量调样式，关键是全程不碰官方付费墙。这篇文章就把这套方案的原理、配置、实战效果和坑完整说一遍，适合被付费限制卡住、又想自己搭一套免费 Figma 自动化工作流的开发者。

1. 先聊清楚痛点：为什么需要绕开官方付费墙

1.1 官方 MCP 插件的限制到底在哪

Figma 官方确实针对 AI 集成出了 MCP（Model Context Protocol，模型上下文协议）能力，方向上没问题：让模型读取画板、图层、样式、导出配置，再通过接口实现“看得见、改得动”。

但问题也出在这。官方 MCP 的实际可用范围和服务器的付费套餐强绑定。免费版用户拿到的权限非常有限，核心的读取节点属性、写入设计变更、读取样式库这类高频操作，基本都被关在付费能力后面。对个人开发者、独立产品负责人、小团队来说，每个月几十上百美元的订阅费，就为了给 AI 开个读写口子，性价比真心不高。尤其你只是想做个“设计稿自动走查”、“批量改文案”、“按规范抽成变量”的工具，为了这个付年费套餐，预算上不划算。

1.2 本地代理方案的核心思路

Local Figma Agent MCP 的立足点很简单：不依赖官方付费套餐的开关，而是自己写一个本地服务，夹在 Codex 和 Figma 之间。这个服务做两件事：

• 通过 Figma 的公开 REST API（只需要个人访问令牌，免费额度即可用）拉取文档结构、节点信息、样式数据；
• 把这部分数据封装成符合 MCP 协议的工具，让 Codex 像调用普通函数一样读取和修改。

换句话说，它不碰官方 MCP 的付费能力，而是把 Figma 本来就开放的 HTTP API 二次封装了一下，把原始 JSON 变成了 AI 好理解、好操作的工具接口。这个思路本质上跟“自己写脚本调接口”是一回事，但胜在把繁琐的请求、鉴权、字段映射全部封装好了，Agent 直接用就行。

1.3 和其他免付费方案的对比

免付费让 Agent 操作 Figma 的方案主要有这么几类，我大概花了两个晚上逐个试过：

对比下来就很清楚了，本地代理方案在“免付费”“可自主操作”“结构化读取”三点上做到了平衡，用来做个人项目和内部工具完全够用。

2. 原理拆解：本地“翻译官”是怎么工作的

2.1 整体架构分三层

Local Figma Agent MCP 跑起来之后，其实是一个三层结构：

• 第一层：Codex。 它是发起方，你通过自然语言描述需求，比如“把首页这个标题改成四号字，颜色换成品牌主色 #3366FF”。Codex 根据需求决定调用哪些 MCP 工具。

• 第二层：Local MCP Server。 由你本地启动的一个 Node.js 服务，它是中间翻译官。一方面通过标准 MCP 协议和 Codex 通信，把工具列表、参数结构暴露给模型；另一方面通过 HTTPS 请求，与 Figma 的 REST API 交换数据。

• 第三层：Figma 云端服务。 真正的数据存这里。所有文档树、样式、图层属性都在远端，本地服务只是替 Agent 做数据存取。

用生活类比的话，这就是一个同声传译：设计师和 AI 语言不通，本地服务一边听 AI 的请求，一边翻译成 Figma API 能懂的 HTTP 调用，再把结果翻译回结构化格式给 AI。

2.2 工具集合：实际暴露了哪些能力

配置好之后，Codex 侧会多出一组工具，名称大概是这种风格：

• get_document_tree：获取整个文档的画板、图层层级结构，返回节点 ID 和名称列表；
• get_node_info：读取某个特定节点的坐标、尺寸、文本内容、填充色等属性；
• update_text_content：批量替换指定文本节点的内容；
• update_fill_color：修改节点填充色，支持 hex 或 rgb 输入；
• list_styles：列出文档中命名样式（颜色、文本、效果）；
• export_node_png：导出节点截图，方便 Agent 确认视觉效果。

这组工具已经覆盖了日常设计稿操作里 90% 的常见需求。我实测下来，改文案、换颜色、批量统一间距这类操作，基本不需要再手写额外代码。

2.3 一个容易被忽略的边界：读取和写入的差异

用这套方案时要心里有数：它主要通过 Figma REST API 操作，但 REST API 对“读取”的支持非常完整，对“写入”则有一定限制。比如修改文本内容、更改 fill 颜色这类属性更新是支持的；但创建复杂矢量图形、重新排布自动布局这种“设计施工”级别的操作，REST API 不一定支持，官方大部分写操作要走插件 API。

所以我的建议是：把这套方案定位成“设计稿调整助手”，而不是“从零设计生成器”。让它批量改文案、替换图片、调样式、检查一致性，这些活它干得又快又好。真要让它凭空画一个复杂组件，那还是留给设计师本人吧。

3. 实操配置：把 Codex 和 Figma 顺利接起来

3.1 前置条件准备

实际动手前需要准备四样东西：

• 本机 Node.js 环境，建议 18 以上；
• 一个 Figma 账号（免费版即可）；
• 一个 Figma 个人访问令牌，创建路径在账号设置里的 Security 选项卡下；
• Codex 客户端（命令行或桌面版都行）。

个人访问令牌是关键。创建时注意权限选择，建议只勾选File content相关读取能力和必要的写入权限，别图省事开全局权限。

注意：令牌相当于你 Figma 账号的钥匙。用完删掉重建也方便，别写死在公开仓库里。

3.2 安装并启动本地服务

我用的是某个社区开源的本地代理实现（具体包名会变，你搜local-figma-agent-mcp就行）。安装步骤很简单：

npm install -g local-figma-agent-mcp

然后创建一个配置文件，填上令牌和默认文档 ID：

mkdir ~/.figma-agent && cd ~/.figma-agent touch config.json

config.json 里大概长这样：

{ "figmaToken": "你的个人访问令牌", "defaultFileKey": "你的Figma文件Key", "port": 8765, "transport": "stdio" }

启动服务：

local-figma-agent-mcp --config ~/.figma-agent/config.json

启动成功的标志是终端不报错，服务进入等待状态。它默认走 stdio 传输，也就是 Codex 直接和它用标准输入输出通信，不需要额外开端口。

3.3 在 Codex 里注册 MCP Server

Codex 支持通过配置文件加载 MCP Server。找到 Codex 的配置文件（一般在用户目录下的.codex/config.toml），加入这样一段：

[mcp_servers.figma] command = "local-figma-agent-mcp" args = ["--config", "/Users/你的用户名/.figma-agent/config.json"]

保存后重启 Codex，输入命令查看工具列表：

codex mcp list

如果能看到上一条提到的 6 个工具，就说明连接成功。如果看不到，大概率是路径写错或者 config.json 格式有问题。

3.4 首次联调测试

我会先用最小请求验证连通性。在 Codex 里输入这样一句话：

“请获取默认文档的文档树，列出前 5 个画板的名字。”

正常情况下，Codex 会调用get_document_tree，然后把画板名称列表返回给你。这一步能跑通，说明整套链路已经建立：Codex → MCP Server → Figma API → 数据返回，全部正常。

如果这一步卡住了，不要急着怀疑工具，先用 curl 单独测试一下令牌和文档 ID：

curl -H "X-Figma-Token: 你的令牌" \ "https://api.figma.com/v1/files/文档Key"

能返回 JSON，说明令牌和文档 ID 没问题，问题就出在本地服务的参数配置上。

4. 实战：让 Agent 真正修改设计稿的几种典型场景

4.1 批量替换文本，不用一个个去点图层

我最常用的场景是统一替换多画板中的文案。举个例子，一个跨平台系统，几个页面的底部按钮文本都写的是“Confirm”，要把它们全改成“确认”。时间紧的情况下，手动打开 Figma 一个图层一个图层替换，少说一刻钟，还容易漏。

用 Local Figma Agent MCP 就是这么一句话的事：

“查找所有画板里文本内容为‘Confirm’的文本节点，全部替换为‘确认’。”

Codex 会先获取文档树，筛选出文本节点，逐个检查内容，再调用update_text_content批量修改。你只要在 Figma 里按 Cmd+S 保存，刷新页面就能看到变化全部落地。实测下来，几十个文本节点的替换比手工快了一个数量级。

这种能力真正的价值在于：它不只执行你的明确指令，还能理解模糊需求。比如“把每个画板里第一屏的标题都加上统一的副标题”，它能自己通过节点层级和名称判断哪一层是“标题”，再决定往哪插内容。

4.2 按照代码规范抽取设计变量

做前端对接时，设计稿里的颜色值经常不统一，有的是#333333，有的是rgba(51,51,51,0.8)，还有的直接用默认黑色。让 AI 一个个看又怕漏。

我用它做过一次全局颜色走查，命令是：

“扫描所有画板的填充色，找出所有非品牌色变量定义的硬编码颜色，按使用频率排序输出。”

这个请求会触发多个工具的组合使用：get_document_tree找到节点，get_node_info读取填充色，list_styles拉取现有样式库，最后在输出里给出一个比对清单。有了这个清单，统一规范就成了一次批量修改的事。

4.3 生成设计稿的结构化描述

有时候要给其他开发同事说明页面结构，或者给 Agent 提供上下文，手动截图加标注特别费劲。Local Figma Agent MCP 可以直接让 Codex 生成结构描述：

“获取首页画板的结构，按层级输出每个区域的功能、类型、包含的文本和按钮。”

返回的内容是标准的嵌套列表，可以作为 prompt 直接喂给其他 AI，也可以整理成文档。因为数据直接来自文档树，准确度和完整性比人工截图的描述高不少，还不受文档大小限制。

5. 常见问题与排查实录

5.1 启动本地服务时提示找不到配置

这个问题我遇到过两次，罪魁祸首都是路径。很多人把config.json放在当前目录，然后从其他目录启动服务，自然找不到。

解决办法：给命令行传绝对路径，或者把配置文件固定放在用户主目录下的隐藏目录里。命令写成：

local-figma-agent-mcp --config "$HOME/.figma-agent/config.json"

5.2 文档树能读到，但节点操作一直超时

这个典型症状是：get_document_tree正常返回，但读取深度节点或修改节点时超时。

多数原因是大文档的节点层级太深，get_document_tree一次性把全树拉回来，数据量非常大，后续操作反而变慢。我的经验是先用文档树定位大的画板 ID，再针对单个画板调用get_node_info，缩小每次读取的范围。

5.3 修改文本和颜色后，Figma 页面里没变化

这个坑比较隐蔽。REST API 写入成功后，Figma 编辑器的实时同步不一定立刻刷新。我一开始以为修改没生效，后来发现是本地缓存和网络延迟的问题。

等十几秒再刷新页面，或者直接重新加载文件窗口，修改就会显示出来。如果多次刷新还是看不到，才需要检查令牌是否有写入权限。

5.4 和官方 MCP 插件冲突

如果你之前已经配过官方 MCP 插件，两边可能会抢工具名。比如update_text_content两边都有，Codex 会混淆。

解决办法是在 Codex 配置里临时注释掉官方插件，或者把本地服务改到另一个 MCP Server 名字下，避免命名冲突。我个人建议：本地服务和官方插件不要同时启用，用哪个开哪个。

5.5 令牌权限不足，读取报 403

创建令牌时如果只勾了File content: read-only，那读取没问题，但所有写入操作都会报权限错误。

创建令牌时选权限时，除了读取，还要勾选File content: write对应的写入能力。如果已经创建了，直接重新生成一个，稍微麻烦一点但最省心。

6. 最后分享一个实操习惯

这套方案我用了快两个月，最大的体会是：它最适合的不是“让 AI 从零设计”，而是“让 AI 帮你做设计稿体力活”，比如批量改文字、换主题色、抽变量、检查一致性、生成结构化说明。把这类重复操作交给 Agent 以后，设计师能省出一大块时间去盯有创造性的部分。

另外一个小技巧：在 Codex 里和一个 Figma 文件反复协作时，文件 Key 一定要写在 config 里，并且每次会话开始时都明确说一句“目标文件是默认配置中的那个”，能大幅减少 Agent 拿错文件的情况。如果你有多个项目文档，可以多复制几个 MCP Server 配置，每个对应一个文档，比让 Agent 自己猜要稳定得多。

如果你的核心诉求也是“不花钱、能让 Agent 读懂设计稿、还想让它动手改”，那 Local Figma Agent MCP 这条路值得一试。按上面步骤配置一遍，前后不到十分钟，剩下的就是慢慢摸索它能帮你省多少事了。