企业官网建设流程全解析

先交代一下我遇到的具体场景。我在一个依赖 Figma 做日常设计协作的项目里，经常需要让 AI 帮忙处理设计稿中的机械性工作：批量替换旧文案、统一按钮配色、检查样式中漏掉的字重。第一反应肯定是用现成的 AI 集成能力，但试下来发现，官方方案虽然体验顺滑，却绑定了付费套餐，账号权限要申请、用量要审批，光流程就能耗掉半天。

后来我把目光转向了本地运行的一类工具：通过 MCP（Model Context Protocol，模型上下文协议）把 Figma 的设计数据暴露给 Codex。这个思路不需要额外开通企业版席位，只要本机跑一个 Figma Agent MCP 服务，Codex 就能按标准协议读取设计稿里的图层，还能完成颜色、文本、间距等修改操作。

这篇就把我这次完整跑通的部署过程和踩坑记录整理出来，适合初级到中级的开发者按步骤复现，也帮还没决定选哪条路线的人做一个清晰的横评。

1. 为什么要把 Figma Agent 拉回本地：官方托管方案的成本墙

1.1 官方集成体验好，但托管成本被转嫁给了使用者

一开始我按常规思路搜索，看到官方合作演示里，AI 能直接选中画板里的某个按钮，根据一句“把按钮颜色改成品牌主色”就完成修改。效果确实漂亮，但仔细研究过后你会发现，这种方案背后的架构是“云端托管 Agent”：你的设计文件要被复制到云端工作区，Agent 在那边打开画布，执行每一步操作，再把结果同步回来。

因为涉及云端算力和存储，这部分能力在企业版套餐里是单独计费的。平台基础版不包含，即使你只是一个人想在测试稿里做几个样式调整，也得按整个工作区的席位来开通。对于个人开发者、小团队、内部自动化工具这三类场景，这笔开销非常不划算，更不用说权限审批链条长，配置完兴趣也凉了一半。

后来我换了一个思路：既然 AI 操作 Figma 的本质就是“拿到文件数据、把意图转成编辑指令、把结果存回去”，那这些步骤是不是可以全部在本地完成？答案是肯定的。本地 Figma Agent MCP 就是把整条链路放在自己机器上，用标准 MCP 协议给 Codex 提供工具调用入口。

1.2 本地 Agent 绕开的不是权限，而是托管额度

这里要先澄清一个容易误解的点：本地方案并不是在钻什么空子，也不是破解了什么特殊接口。它和官方方案的授权模型是一致，只是把执行位置从别人的服务器挪到了你自己的电脑上。

官方付费套餐对应的服务，解决了“我没有环境也能跑 Agent”的托管问题。但如果你本来就有开发机，也有 Figma 工作区文件的访问权限，那么跑一个本地服务，用个人访问令牌读写自己名下的设计稿，完全在正常开发流程范围内。

所以更准确地说，本地 Figma Agent MCP 绕开的是“托管 Agent 套餐”这部分成本，而不是 Figma 本身的权限体系。你要是把它用在团队付费流程强制要求的企业项目里，还是要先确认官方许可条款。个人开发、测试用途、非核心资产的自动化处理，本地方案的合法性基本没有含糊地带。

1.3 这条路线适合谁，不适合谁

我自己的判断是这样的：

适合的场景包括个人学习、Demo 演示、独立开发者维护自己产品的设计稿，以及 CI 里对测试稿做批量检查。这些场景对审计、权限细分、团队协作没有强诉求，本地服务反而更快更灵活。

不适合的场景是大型团队的核心设计资产库、需要完整操作日志、涉及多部门权限隔离的企业文件。这类需求建议老老实实走官方商业方案，别拿测试稿的玩法去碰核心资产。下面所有内容都假设你属于前者。

2. 拆解 MCP 工具背后的数据通道

2.1 Agent 眼里的一份 Figma 设计稿长什么样

很多人的误区是：让 AI 读设计稿，就是把一张屏幕截图丢给它。真实情况完全不是这样。MCP 工具返回的是结构化 JSON 数据，里面包含页面、画板、图层、文本节点的完整属性树。

一个文本节点在我的工具返回值里大概是这样的结构：

{ "id": "112:345", "type": "TEXT", "name": "主标题", "characters": "欢迎体验本地 Agent", "x": 240.0, "y": 96.0, "width": 320.0, "height": 56.0, "fills": [ { "type": "SOLID", "color": { "r": 0.02, "g": 0.13, "b": 0.23, "a": 1 } } ] }

注意它不是一个像素位图，而是一棵节点树。Codex 拿到这样的结构后，能判断“标题在什么位置”“颜色值是多少”“字号用了多少”，然后调用对应的修改工具去改这些属性。这也是为什么本地 MCP 方案能实现精确修改，而不是像截图方案那样只能靠猜。

2.2 读取走 REST，修改走本地编辑通道

本地 Figma Agent MCP 内部一般会把能力拆成两类工具。

读取类工具，比如 listPages、getNodes，大部分通过 Figma 公开的 REST API 获取。调用方只要传入文件键（file key）和页面节点路径，就能拿到最新的文件结构。这类工具稳定、快速、适合频繁调用。

修改类工具，比如 updateText、updateFill、updateCornerRadius，通常走另一条通道。常见实现方式是本地启动一个代理编辑会话，这个会话以你的账号身份连接目标文件，接收 Agent 发来的操作事件，再转换成设计编辑器能识别的动作。因为它在你的本机运行，所以可以持续维持这个会话，而不需要每次请求都去云端拉起一个新实例。

这也是“本地 Agent”这个叫法的由来：不是简单地调接口，而是真的有一个 Agent 进程在本地盯住画布状态，随时准备执行修改。

2.3 为什么个人令牌能做“改图”这件事

如果你之前只用过 Figma 的只读令牌，可能会疑惑：修改文件权限从哪来？

个人访问令牌在创建的时候，可以选择权限范围。文件基本读取、文件内容写入、团队成员访问、变量库读取、变量库写入，这些 scope 是可以勾选的。只要你勾了写权限，并且这个文件的编辑权在你的账号名下，本地服务就可以用令牌发起修改。

这背后的产品逻辑很简单：你在 Figma 网页端手动改图，本质也是你自己的会话在改。本地 Agent 只不过是把同一种身份验证换成程序化调用，API 层识别为已授权编辑会话。区别在于，官方托管套餐把“云端会话”当成一个计费资源，而本地服务用的是你本机已有的授权。这也是为什么“不买付费套餐也能让 Agent 改稿”是可行的。

3. 部署记录：把本地 Figma Agent MCP 挂到 Codex

3.1 环境准备与服务安装

先摆一下前置条件：本机需要 Node.js 20 以上，Codex 命令行工具或者桌面端都可以，另外最好有个可以随时拿来试错的 Figma 测试文件。

以我从开源仓库拉取的实现为例，安装命令大致是这样：

git clone https://example.com/local-figma-agent-mcp.git cd local-figma-agent-mcp npm install npm run build npm run start

启动成功时，控制台会打印MCP server running on stdio。不同的开源项目包名和目录结构可能不同，你实际操作时以自己拉到的仓库为准，但整体流程差不多。

如果是第一次接触 MCP，可以先把它理解成一个翻译层：Codex 通过标准协议询问“你有哪些工具”，服务进程回答“我有读取节点、修改文本、修改填充色等工具”，后续对话里 Codex 就用这些工具去操作外部系统。

3.2 生成并配置 Figma 个人访问令牌

这一步不能跳过。入口在 Figma 桌面端的右上角头像菜单：Account Settings → Security → Personal access tokens。

创建令牌时，权限范围一定不要按默认勾选，至少要包含：

• file_content:read：读取文件内容和节点结构
• file_content:write：修改文件内容
• file_dev:read：读取 Dev Mode 下的标注信息

如果是团队设计系统场景，还要勾上file_variables:read和file_variables:write，否则后面读不到变量库，也没法改 Design Token。

生成后立刻复制保存，因为这个令牌只会完整显示一次。我见过不少人把令牌只读权限配好，结果写操作一直是 403，查了半天才发现是当初少勾了写权限。老令牌如果权限范围不对，唯一的办法是删除重新生成，没有中途修改的口子。

3.3 用环境变量存放敏感信息

令牌不要直接写进 Codex 的配置文件里，尤其当你的编辑器配置会和别人共享时。推荐的做法是放在本机环境变量中：

export FIGMA_ACCESS_TOKEN="figd_xxx_xxx" export FIGMA_LOCAL_AGENT_PORT=8765

本地 MCP 服务启动时会自动从环境变量里读取令牌。这样即使配置文件被同步到其他机器，也不会把凭证泄露出去。

如果你平时会用 dotenv 管理环境变量，也可以把它写进项目根目录的.env文件，然后启动命令改成node --env-file=.env dist/index.js，效果一样。

3.4 在 Codex 配置文件中注册 MCP 服务器

我用的是 Codex CLI，配置文件在~/.codex/config.toml。在文件末尾新增一段mcp_servers配置：

mcp_servers = [ { name = "local-figma-agent", command = "node", args = ["/path/to/local-figma-agent/dist/index.js"] } ]

保存后重启 Codex，执行codex mcp list验证。如果能看到local_figma_agent以及它的工具列表，比如get_nodes、update_text、update_fill，就说明接入成功。

不同版本的 Codex 对配置字段的兼容性有差异，如果你用的版本不识别mcp_servers数组，去查一下当前版本的配置结构，改成对应的对象格式就行。

3.5 连通性验证

配置完先别急着改图，跑一个最小验证。我用的提示词是：

连接到文件键为 yB7dXxK 的测试文件，列出首页中名为 Header 的画板下所有文本节点。

如果 Codex 能正确返回节点列表，说明读取链路通畅。接着再试一次写操作，比如把某个文本节点改成“测试”，看 Figma 画布上是否实时刷新。两条链路都通，才算真正完成准备。

4. 实测：Agent 从读懂画布到完成修改

4.1 案例一：把整个页面图层整理成样式清单

我先建了一个模拟项目X，里面是一个简单的落地页，包含导航栏、主视觉区、功能说明区三个板块。第一次实测目标是：让 Agent 把文件里的样式信息整理成清单。

提示词是：

汇总这个文件里所有文本节点的字号、字重和颜色，整理成一张表格。

Codex 做了两次工具调用：先列出所有页面，再读取指定主画板下的节点树。最后输出的结果类似这样：

这次测试证明一个关键点：Agent 能通过 MCP 定位到每一个文本节点的 ID。只要能拿到 ID，后续修改就有了精确目标，不需要靠视觉识别猜位置。

4.2 案例二：按自然语言修改标题颜色和文本

接下来进入真正的修改测试。我的指令是：

把 hero-title 的文本改成“新版首页文案”，填充色改成 #E63329；同时把 hero-subtitle 的字号改成 28。

Codex 按顺序调用了update_text、update_fill、update_style三个工具，每次调用都传了节点 ID 和修改后的值。执行过程中，Figma 画布上的标签会有短暂的刷新闪动，退出并重新进入文件后，修改结果全部生效。

整个过程中没有人手动碰过画布，改色、改文案、改字号都是 Agent 自己完成的。我把修改前后的关键属性放在一起做了个对比：

4.3 实测注意事项：修改不可逆，先开副本

所有写操作类工具，我都强烈建议在副本文件上运行。虽然 Figma 有版本历史可以恢复，但 Agent 批量修改可能一次动几十处，真要回滚时会发现你分不清哪些改动是有意的，哪些是模型抽风带来的副作用。

我的习惯是先 Duplicate 一个测试副本，拿到副本的文件键后，再让 Agent 对着副本操作。确认结果没问题，再把同样的修改流程同步到正式文件。多花一分钟，后面能省掉大半天的恢复时间。

5. 常见踩坑与排查路径

5.1 报“找不到节点”：多半是版本 ID 过期

我遇到最多的错误是node not found或invalid node id。原因通常是 Codex 在会话早期读取了节点 ID，但它使用系统时文件的版本已经被其他协作者更新了，旧 ID 不再指向当前版本。

解决办法很简单：在每次写操作前，重新调用读取工具获取当前节点 ID。不要让模型拿一个旧 ID 反复试。如果会话上下文太长导致模型一直复用旧结果，直接开一个新会话会比层层纠正要快得多。

5.2 读取正常但写入总是 403

读取没问题，一写就报权限错误，大概率是令牌创建时权限范围没勾全。去重新生成一个包含file_content:write的令牌，并且生成后重启 MCP 服务。

另一种情况是文件本身对你只读：你是协作者但编辑权限不足，或者文件在团队项目里但你的角色是 Viewer。这种情况不管换什么令牌都救不了，直接在自己有编辑权限的副本上操作。

还有个小坑：如果你只在 Figma 网页端换过令牌，MCP 服务进程还占着旧环境变量，重启服务这一步别漏掉。

5.3 大文件读取非常耗时且浪费 Token

一个大型设计文件可以有两三千个节点。如果 Agent 每次都用不带过滤条件的读取工具，返回的 JSON 能轻松把上下文塞爆，响应速度也会肉眼可见地变慢。

解决办法是善用工具的过滤参数。尽量指定页面名、Frame 名或节点类型，比如“只返回首页中类型为 TEXT 的节点”。我在实测中感受尤为明显：带过滤条件的调用，返回体量能降到完整节点的十分之一，Codex 的响应准确率也同步提高。

5.4 端口冲突导致多个会话互相干扰

如果本地服务同时开启了 WebSocket 通道和 stdio 通道，而你在 Codex 桌面端开了多个会话，偶尔会出现端口被占用、服务连接失败的情况。

我后来直接改用纯 stdio 模式，把 WebSocket 端口关闭，稳定性和兼容性反而更好。需要多会话并行时，每个会话共用同一个 stdio 进程，不会出现端口抢占的问题。

5.5 修改后画布没刷新

修改工具返回成功，但 Figma 画布内容不变，通常不是执行失败，而是本地缓存没有立刻刷新。等三到五秒再看一次基本能解决。频繁出现这个问题时，检查一下 MCP 服务日志里有没有 WebSocket 断开重连的记录。

如果日志显示连接中断，说明本地编辑会话提前结束了，后面的写操作只是进了队列但没真正推送到画布。重启服务，重新触发一次修改即可。

6. 几个让我省下真实成本的使用习惯

整套流程跑通之后，我最大的体会是：成本节省不只是省在套餐费上，更省在“把一次性人工操作变成可重复脚本”的长期收益上。

比如我现在每周都会让 Agent 扫一遍产品落地页的设计稿，检查所有按钮的圆角半径是否统一、标题字重是否符合规范。过去这个工作要靠设计师手动翻画板，现在变成了一条固定提示词加两次 MCP 调用，从开头到拿到结果不超过一分钟。

不过我也给自己定了三条纪律：第一，只在本人的测试文件上跑写操作，正式文件永远手动确认后再允许修改；第二，每次改稿前先复制一份测试副本，不给回滚留隐患；第三，涉及敏感设计资产的场景，绝不为了省成本把本地方案硬套上去。

这个方案对独立开发者和技术驱动的小团队来说，是性价比很高的一条路。它的学习成本主要在头半小时：搞清楚 MCP 工具调用方式、配好令牌、摸清过滤参数。过了那个坎之后，你会发现自己不是在“教” Agent 改图，而是在真正批量生产设计稿的自动化能力。