Figma 评论导出(Export Comments)与 Jira / Asana / Linear 研发工单双向闭环实战:REST API 批注 CSV 归档、Dev Mode 工单关联与防漏改指南

2026 年 11 月 21 日

在大型产研项目或外包交付周期里,Figma 画布里的 Comments(批注评论) 往往承载着最核心的产品决策与验收修改意见(基础精准下钉与降噪技巧可先参阅 Figma 协同评审与设计批注全流程实战)。然而到了提测封版或客户验收归档时,团队常常会卡在两个工程断层上:

  1. 缺乏可归档的结构化台账:设计总监、法务合规或甲方要求将评审意见导出为 Excel / CSV 验收清单,但 Figma 原生界面没有“导出所有评论为表格”的按钮;
  2. 评论与研发工单脱节:测试和产品经理在画布上钉了几十条图钉,研发却只在 Jira / Linear / Asana 看任务排期,最后漏改了关键交互细节,或者分支合并后评论找不到原位置。

打通 “评论批量提取归档 + 研发工单双向同步”,才能让画布上的每一条意见真正落地成可追踪的工程闭环。


一、批注导出与工单联动四大方案选型对比 #

在动手配置前,先依据团队权限和安全边界挑选最稳妥的联动方案:

方案路径 实现方式与技术门槛 导出/同步字段完整性 适用业务场景 权限与安全注意事项
1. Figma REST API 脚本导出(推荐) 仅需只读 Personal Access Token 调用 GET /v1/files/:key/comments 100% 全量字段:评论 ID、父子盖楼关系、节点 node_id、作者、解决时间戳 企业内部自动归档、周报统计、Design QA 验收表生成 令牌只需 file_comments:read 权限,零第三方插件泄密风险
2. 社区评论导出插件(Export Comments) 画布内运行导出 CSV / PDF 报告插件 含文案、作者、状态与页面归属;部分高级导出带截图标注 外包阶段交付、临时给非 Figma 用户发送审阅台账 若团队启用插件白名单,需联系管理员放行并核查网络权限
3. Dev Mode Dev Resources + Jira/Linear 插件 在 Dev Mode 右侧直接挂接工单链接或双向同步状态卡 支持工单标题、经办人、状态徽标与画板 node-id 双向跳转 产研日常迭代:开发点组件直达需求,PM 在工单直看设计稿 挂载与编辑开发资源需对应 Dev / Full Seat 席位
4. 跨平台实时嵌入(Jira / Asana Live Embed) 在工单系统安装官方插件并粘贴 Figma 分区或画框 URL 实时渲染云端最新画面并显示修改提示 需求评审单附图自动刷新、消除“截图过期”扯皮 注意文档与文件权限匹配(详见 Jira 官方集成指南)

二、实操一:3 分钟用官方 REST API 将全文件评论无损导出为 CSV 台账 #

相比授权不明第三方插件读取整个设计文件,自己用 30 行 Node.js 脚本直接调 Figma 官方接口导出 CSV 是最安全、零成本且可融入 CI/CD 流水线的方案(更多 API 鉴权规范可参阅 Figma REST API 自动化流水线实战)。

第 1 步:创建最小权限只读 Token 与提取 FILE_KEY #

  1. 登录 Figma 后点击左上角头像进入 Settings -> Security -> Personal access tokens;
  2. 点击 Generate new token,仅勾选 File comments (Read only) 作用域,妥善复制生成的 figd_... 令牌;
  3. 从浏览器打开目标设计文件,复制地址栏 /design/ 或 /file/ 后面的那串字母数字组合(即 FILE_KEY)。

第 2 步:运行导出脚本生成兼容 Excel 中文不乱码的 CSV #

在本地新建 export-comments.mjs,执行后即可输出按线程聚合、带直达画布定位链接的台账表格:

import fs from 'node:fs';

const TOKEN = process.env.FIGMA_TOKEN;
const FILE_KEY = process.env.FIGMA_FILE_KEY;

const res = await fetch(`https://api.figma.com/v1/files/${FILE_KEY}/comments`, {
  headers: { 'X-Figma-Token': TOKEN }
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);

const { comments } = await res.json();
const esc = (v) => `"${String(v ?? '').replace(/"/g, '""')}"`;

const rows = [
  ['ID', 'Parent_ID', 'Status', 'Author', 'Created_At', 'Resolved_At', 'Node_ID', 'Deep_Link', 'Message'].join(',')
];

for (const c of comments) {
  const status = c.resolved_at ? 'Resolved' : 'Open';
  const nodeId = c.client_meta?.node_id || '';
  const deepLink = nodeId
    ? `https://www.figma.com/design/${FILE_KEY}?node-id=${encodeURIComponent(nodeId)}#${c.id}`
    : `https://www.figma.com/design/${FILE_KEY}#${c.id}`;
  rows.push([
    esc(c.id),
    esc(c.parent_id || ''),
    esc(status),
    esc(c.user?.handle || ''),
    esc(c.created_at),
    esc(c.resolved_at || ''),
    esc(nodeId),
    esc(deepLink),
    esc(c.message)
  ].join(','));
}

// 写入 UTF-8 BOM,确保 Windows Excel 双击打开中文零乱码
fs.writeFileSync('figma-comments-report.csv', '\uFEFF' + rows.join('\n'), 'utf8');
console.log(`已成功导出 ${comments.length} 条评论至 figma-comments-report.csv`);

执行 FIGMA_TOKEN=figd_xxx FIGMA_FILE_KEY=xxx node export-comments.mjs,拿到的每一行都包含可点击的 Deep_Link,研发或测试在表格里点击链接就能瞬间飞跃到画布对应图钉上。


三、实操二:打通 Figma 与 Jira / Linear / Asana 的工单双向闭环 #

导出了历史台账后,日常敏捷迭代更需要让评审意见和开发任务实时咬合,防止“评论标了已解决,但代码根本没排进 Sprint”。

1. 在设计评审前先锁定“精准锚点链接”,再嵌入工单 #

  1. 切勿直接复制整个文件的顶层链接:把含几十页的整文件 URL 贴进 Jira 或 Linear,研发点开后根本找不到需求对应哪张画板;
  2. 使用 Section 或单画板 node-id 锚点:选中本轮需求所在的 Section(或按 ⌘ + L 复制单个画板链接),再贴入 Jira / Linear / Asana 的 Design 扩展字段中(跨文档嵌入方法亦可对照 Live Embed 实时嵌入指南 与 Notion / 飞书 / Linear 协同闭环实战);
  3. 权限一致原则:如果团队启用了私有项目隔离,嵌入工单时请确保研发成员在当前浏览器已通过企业 SSO 登录 Figma,并在 项目分享权限设置 中至少赋予团队成员 Can view 权限,避免工单内预览框显示空白报错。

2. 在 Dev Mode 用 Dev Resources 反向绑定工单状态 #

研发从 Jira 看设计稿只是单向链路;要实现双向闭环,设计师和前端应在 Dev Mode 内建立反向锚点(详细面板操作见 Dev Mode 研发资源挂载实战):

  1. 切入 Dev Mode(⇧ + D),选中待开发的组件或弹窗画板;
  2. 在右侧 Dev resources 面板点击 + Add link,粘贴对应的 Jira Issue、Linear 议题或 GitHub PR 链接;
  3. 如果安装了官方 Jira / Linear / GitHub 插件,右侧还能直接渲染出工单的实时状态标签(如 In Progress / In Review),以及最近一次改稿对比提示,配合 Dev Mode 原生 Annotations 标注实战 把交互异常说明直接钉在控件上,彻底替代零散的普通气泡评论。

四、实操三:提测封版前的评论清零与防漏改 SOP #

在每次版本发版或设计系统主库合并前,建议按以下四步执行评论清零仪式(并发协同防覆盖规范见 多人协同 CRDT 与版本恢复实战):

  1. 开启按页过滤:点击评论面板顶部过滤器,勾选 Current page 与 Hide resolved,集中清点当前交付页所有仍处于 Open 状态的未决图钉;
  2. 区分“技术交付约束”与“视觉修改讨论”:
    • 视觉与交互修改意见在画布改完后,回复修改结果并立即点击左上角 ✓(Resolve) 归档;
    • 涉及前端边界规则或埋点参数的长效说明,切忌留在普通气泡评论里(容易被误点 Resolve 隐藏),务必转写入 Dev Mode Annotations;
  3. 把未决阻塞项转为工单再归档:若某条评论确认延期至下一迭代处理,先在评论区创建或粘贴对应的 Jira/Linear 工单号(例如 已转工单 FE-1042 跟进),再点击 Resolve,防止画布长期堆满“僵尸评论”;
  4. 运行脚本留档并打版本快照:提测瞬间跑一次上文 CSV 导出脚本留存验收证据,同时按 ⌥ + ⌘ + S 保存命名版本快照(例如 v2.4 提测封版-所有评审已清零)。

五、评论导出与工单集成高频异常排查对照表 #

遇到接口报错、评论消失或外链预览加载失败时,对照下表 1 分钟定位根因(全站排查汇总见 Figma 常见报错与疑难故障诊断手册):

异常现象 底层原因定位 标准化排查与解决动作
调用 /comments 接口返回 403 Forbidden 或 Invalid scope 创建 Personal Access Token 时未勾选 file_comments:read,或当前账号对该私有文件连只读权限都没有 重新生成 Token 并勾选 File comments (Read only);确认当前账号在目标文件拥有 Can view 及以上权限
执行 Duplicate 备份或 Save local copy (.fig) 后,新文件里所有评论全消失了 设计机制限制:Figma 的评论数据存储在云端独立元数据表,复制副本(Duplicate)与 .fig 本地归档默认不迁移历史评论 若需留存历史验收记录,务必在复制或归档前通过 REST API 导出 CSV 台账,或直接在原文件内使用 Design Review 历史视图 溯源
从 Branch 分支合并回主干后,原本在分支里讨论的评论找不到了 分支的评论归属于独立分支 FILE_KEY,合并后主文件不会自动把分支气泡搬运过来 进入版本菜单切回已归档的 Archived Branches,打开原分支的 branch_key 仍可完整查看与 API 导出历史讨论
在 Jira / Asana / Linear 粘贴 Figma 链接后,卡片只显示纯文字或空白报错 1. 目标链接是加密或私密文件且当前浏览器拦截第三方 Cookie;2. 工单系统未安装/未授权最新 Figma OAuth 应用 确认 Jira/Linear 已完成 Figma 账号 OAuth 绑定;内部私有文件需在当前浏览器先登录 Figma SSO,公开嵌入则需关闭密码保护
评论面板明明显示还有未读数,画布上却怎么也找不到图钉 误按 ⇧ + C 隐藏了全局评论显示,或该评论被过滤条件隐藏 / 绑在已跨页移动的节点上 按 ⇧ + C 重新显示评论图钉;清空评论搜索框,把过滤条件重置为 All pages + All comments,点击右侧列表卡片直接视口定位

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Starter 计划中均可完整体验与实操练习,无需额外付费购买付费团队版。