faq.md

/faq — 高频问题速查

用法：用户在 AI 客户端里说 /faq 或 figma 用不了 / 装不上 / 连不上 / 字不对，Agent 进入本流程。

目标：快速定位"安装、连接、字体、变量、组件、导出"六个高频痛点，给出可执行修复步骤；每个用户的环境（Python 版本、Node 版本、终端、字体库）都不一样，一定先问环境再开方子。

工作方式

1. 先做一次自检：跑 scripts/check_connection.sh，看是否有 FAIL 项。把脚本输出读进来作为诊断起点。
2. 询问关键症状：让用户描述最近一次出错的具体动作和完整报错信息（截图/复制粘贴都行）。
3. 匹配问题分类：对照下面 6 个分类找到最像的一项。
4. 执行修复：每个分类下有诊断命令 + 修复步骤。
5. 验收：修复后再跑一次 check_connection.sh 或让用户实测一句"用 figma_editor 检查连接"。

---

类别 A：连接 / 安装

A1. pluginConnected: false

含义：MCP 通了，但 Figma 桌面里没运行 figma_editor 插件。

修复：

1. 让用户在 Figma 桌面端打开任意设计文件。
2. Plugins → Development → figma_editor，点击运行。
3. 看到弹出的小面板后保持开启（关掉就断）。
4. 在 AI 客户端里再次调用 figma_editor.get_connection_status 验证。

A2. connected: false / 调用 figma_editor 工具时抛 "MCP server not running"

含义：MCP 服务本身没起来。

诊断：

• 让用户检查 AI 客户端的 MCP 配置文件是否有 figma_editor 条目。
• 看 Node 版本：node -v ≥ 18。
• 看 npx 是否能拉到包：npx -y figma_editor --version（首次会比较慢）。

修复：

• 配置文件不对：参考 scripts/install_guide.md 的 §2.3 重写一份。
• Node 太老：升级到 18+（推荐 nvm）。
• 网络拉不到 npm 包：换 npm 镜像或 clone 仓库本地 build（参考 install_guide §2.3 末尾）。
• 配置写完没生效：重启 AI 客户端（Cursor / Claude Code / Codex）。

A3. 端口冲突 port 3055 already in use

含义：默认端口被占用。如果是另一个 figma_editor 进程，新进程会自动作为 proxy 接入，这是正常的。如果是别的程序占用，需要让路。

诊断：

lsof -i :3055

修复：

• 是另一个 figma_editor 进程 → 不用管，第二个 AI 客户端会自动 proxy 进同一个 hub。
• 是别的程序 → 在所有 AI 客户端的 MCP 配置里加 "env": {"FIGSOR_PORT": "3056"}，统一换端口。

A4. Cannot find module 'figma_editor'

含义：npx 拉包失败或缓存损坏。

修复：

npm cache clean --force
npx -y figma_editor --version

如果还失败，clone 仓库本地 build：

git clone https://github.com/liaocaoxuezhe/figma_editor.git
cd figma_editor && npm run setup

然后把 MCP 配置里的 command 改成 node、args 改成 ["/绝对路径/figma_editor/mcp-server/dist/server.js"]。

---

类别 B：字体

B1. 调 create_text 报 "Font not loaded"

含义：本机 Figma 没装这个字体，或字体名拼错。

诊断：先调 figma_editor.list_available_fonts，搜一下用户想用的字体是否在列表里。

修复：

• 字体不在列表：换成本机有的字体；或让用户去 Figma 字体助手装上（macOS 用户：到字体册添加 → 重启 Figma 桌面）。
• 字体名拼错：注意 PingFang SC 和 PingFangSC 的区别；以 list_available_fonts 返回的精确名字为准。

B2. 中文字回退到难看的默认字体

含义：fontFamily 是英文字体（比如 Inter），缺中文字形时浏览器/Figma 回退。

修复：用 style_text_range 给中文段落单独设 fontFamily 为中文字体，或一开始 create_text 时就传 "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei" 作为完整 fontFamily 链。

B3. 字号显示不对（变小或变大）

含义：通常是绑了变量但变量值不对。

修复：调 read_node_properties 看实际 fontSize；调 get_variables 看变量定义；用 bind_variable 重新绑或解绑后手设。

---

类别 C：自动布局 / 排版

C1. 元素叠在一起

含义：父 frame 没有 set_auto_layout，子节点用了绝对坐标重叠。

修复：对父 frame 调 set_auto_layout(direction="VERTICAL"|"HORIZONTAL", gap=N)，子节点会自动排开。

C2. 文字溢出画框

含义：文本节点宽度固定但内容超长，或父 frame 没设 primaryAxisSizing="AUTO"。

诊断：调 read_node_properties 看 width / textAutoResize。

修复：

• 让文本节点 textAutoResize="HEIGHT" 配合父 frame counterAxisSizing="AUTO"。
• 或把文本宽度设为父 frame 的 STRETCH（layoutAlign="STRETCH"）。

C3. 整个画面挤在左上角

含义：根 frame 的 auto layout padding 设太小或没设。

修复：根 frame 加 padding [64, 96, 64, 96]（上右下左），section 之间 gap 48-96。

---

类别 D：颜色 / 变量

D1. 改颜色没生效

含义：节点 fill 写的是死 hex，没绑变量。

诊断：调 read_node_properties 看 fills 数组，boundVariables 字段为空就是死值。

修复：调 bind_variable(nodeId, "fills", variableId) 把节点 fill 绑到变量。

D2. 变量值看起来不对

修复：调 get_variables 看变量集合的 modes（light / dark）和当前值。Figma 变量可能在某些 mode 下被覆盖。

---

类别 E：组件 / 库

E1. create_library_instance 报 "library not found"

修复：

• 让用户在 Figma 插件面板里粘贴 Figma 个人 access token（manifest 已申请 teamlibrary 权限）。
• 调 scan_library / get_library_info 看哪些库被识别到。

E2. 实例和源不同步

修复：检查源组件是否真的发布了（图书馆需要 publish）。

---

类别 F：导出

F1. export_as_image 导出空白图

含义：导出的 nodeId 不对，或那个 frame 没有可见内容。

修复：先调 get_screenshot 看那个 nodeId 长什么样；或换 get_selection 后导出选中。

F2. PNG 太糊

修复：在 export_as_image 里指定 scale: 2 或 3（默认 1x）。

F3. SVG 文件太大 / 含位图

修复：用 flatten_nodes 先把矢量扁平化，或导出前 boolean_operation 合并。

---

一键自检脚本

bash scripts/check_connection.sh

如果它说"全部检查通过"但具体使用还有问题，那基本是 Figma 插件没运行 / 没 Foreground。回到类别 A 排查。

---

还是搞不定？

• 把 check_connection.sh 完整输出 + AI 客户端的报错截图发到 figma_editor 仓库 issue： https://github.com/liaocaoxuezhe/figma_editor/issues
• 或者跑 commands/optimize.md 让 Agent 复盘本次会话，找出可以改进的地方写进 SKILL.md。