应批量合并figma中重复的本地变量以避免冗余和主题失效，方法包括：一、手动归并同名变量；二、用tokens studio插件跨文件去重；三、通过figma cli脚本重写作用域与引用；四、用figma ai生成条件化清理脚本；五、借助mcp server实现跨项目拓扑归一。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在Figma设计稿中发现大量命名相似、值重复的本地变量（如多个页面各自定义了名为“primary/500”的颜色变量），不仅占用冗余空间，还会导致主题切换失效或同步冲突。以下是针对该问题的多种批量合并处理方法：
一、使用Figma Variables面板手动归并同名变量
该方法适用于变量数量较少（≤20个）、命名规范且存在明显重复前缀的场景，通过界面操作直接识别并覆盖重复定义，保留全局唯一变量实例。
1、点击右上角“资源”→“Variables”，打开变量管理面板。
2、在搜索栏输入疑似重复的变量名片段，例如“primary”或“text/default”。
3、逐个查看匹配变量的“Scope”列，筛选出作用域为“Local”且值完全相同的条目。
4、选中其中一条，点击右侧“⋯”菜单，选择“Copy variable ID”。
5、回到画布，选中所有使用该变量的图层（可按住Shift多选或框选），在右侧属性面板中将填充/描边/文本颜色等字段粘贴该ID，完成引用切换。
6、确认所有图层已成功引用新变量后，在Variables面板中右键其余重复变量，选择“Delete”彻底移除。
二、借助Tokens Studio插件执行跨文件变量去重合并
该方法利用Tokens Studio对W3C标准格式标记的解析能力，自动识别语义等价但命名/作用域不同的本地变量，并生成统一变量集，支持批量导出与重载。
1、确保所有目标文件均已安装并启用Tokens Studio for Figma插件。
2、在任意一个含重复变量的文件中，点击右上角“资源”→“插件”→“Tokens Studio”→“Import tokens from file”。
3、选择当前文件的tokens.json（若未配置则先通过“Export tokens”生成），插件将自动解析全部本地变量并映射至Token Sets结构。
4、在插件界面左侧Token Sets列表中，展开各集合，勾选所有含重复定义的Set（如“colors.light”与“ui.colors.primary”）。
5、点击顶部“Merge selected sets”，在弹出窗口中选择“Merge by value”，系统将按$value字段比对并合并语义一致的变量。
6、确认合并结果无误后，点击“Publish to Figma Variables”，新变量将统一注册为文件级变量，原分散本地变量自动失效。
三、通过Figma CLI脚本批量重写变量作用域与引用路径
该方法适用于大型设计系统（≥50个文件），需命令行操作，可将全部本地变量强制提升为团队变量或文件变量，并批量更新图层引用，避免手动逐个修复。
1、在终端中进入项目根目录，运行bun run figma-cli login完成身份认证。
2、执行bun run figma-cli list-variables --file-id=abc123xyz --scope=local，导出当前文件全部本地变量元数据至local-vars.json。
3、使用文本编辑器打开local-vars.json，删除重复项（依据"value"和"type"字段判断），仅保留每个唯一值的一条记录，并将"scope"字段统一改为"FILE"。
4、保存后运行bun run figma-cli update-variables --file-id=abc123xyz --input=local-vars.json，脚本将覆盖写入新变量定义。
5、再执行bun run figma-cli replace-references --file-id=abc123xyz --from-scope=local --to-scope=file，自动扫描全文件图层，将旧本地引用替换为新文件变量ID。
四、利用Figma AI生成条件化变量清理脚本
该方法面向非技术设计师，通过自然语言指令驱动AI生成可执行JavaScript，精准定位并合并满足特定条件（如“所有以bg/开头且值为#FFFFFF的本地颜色变量”）的变量。
1、在画布空白处右键，选择“Ask Figma AI”，输入指令：“查找当前文件中所有作用域为Local、类型为Color、值等于#FFFFFF且名称以bg/开头的变量，将它们全部合并为一个名为bg/white的文件级变量，并更新所有引用该值的图层”。
2、等待AI返回JavaScript代码块，确认逻辑符合预期（重点关注filter条件与updateVariables调用部分）。
3、点击“Run script”按钮，AI将自动执行变量查询、创建、引用替换全流程。
4、刷新Variables面板，验证新增的bg/white变量已存在，且原分散变量不再显示于Local分组中。
五、采用MCP Server自动化服务实现跨项目变量拓扑归一
该方法依赖本地运行的Cursor Talk To Figma MCP服务，构建变量依赖图谱，识别跨文件语义重复节点，并按预设策略（如优先保留主设计系统文件中的定义）执行拓扑级合并。
1、确保MCP服务已启动（终端中可见WebSocket连接日志），并在Figma设置中开启“Allow local connections”。
2、在Figma中打开任一目标文件，右键空白处选择“MCP: Analyze variable graph”。
3、等待分析完成，界面弹出可视化图谱，红色高亮节点即为被识别为“语义重复”的本地变量集群（基于value哈希与name语义向量双重判定）。
4、点击图谱右上角“Apply merge policy”，选择“Keep first declared in team library”，系统将自动锁定主库变量ID。
5、勾选全部红色节点，点击“Execute merge”，MCP服务将并发向所有关联文件发送原子化更新指令，强制统一引用指向主库变量。
