在实际游戏开发或界面原型制作中设计师使用 Figma 完成高保真设计而开发者则需要将设计稿中的图标、图片等资源导入到 Cocos Creator 项目中并手动进行切图、重命名、调整格式。这个过程不仅重复枯燥而且容易出错一旦设计稿更新所有工作又得重来一遍。对于使用 Codex、Claude Code、Cursor、OpenCode 等 AI 辅助编程工具的开发者来说如果能将设计资源自动化导入就能将更多精力集中在核心逻辑和 AI 提示工程上而不是繁琐的资源管理上。本文将围绕如何搭建一个从 Figma 到 Cocos Creator 的自动化导入流程展开。这个流程的核心是通过 Figma API 获取设计稿资源编写脚本自动下载、处理并放置到 Cocos Creator 项目的正确目录中最终实现“设计稿更新 - 一键同步资源”的自动化链路。我们将从理解 Figma API 和 Cocos Creator 项目结构开始逐步完成环境配置、脚本编写、流程集成和错误排查最终形成一个稳定可用的自动化工具链。无论你是独立开发者还是团队中的技术美术掌握这套方法都能显著提升 UI 资源的生产效率。1. 理解自动化流程的核心Figma API 与 Cocos 资源规范在动手写代码之前必须搞清楚两件事Figma 如何以编程方式提供设计资源以及 Cocos Creator 对资源文件有什么硬性要求。盲目调用 API 或随意放置文件只会导致流程在后期崩溃。1.1 Figma API 能提供什么节点、导出与约束Figma 的核心是一个基于节点的设计数据库。每个画板Frame、组件Component、实例Instance、矢量图形Vector甚至文本Text都是一个节点Node拥有唯一的id。通过 Figma 的 REST API我们可以获取文件结构、节点信息并请求导出特定节点为图片。一个关键概念是“导出设置”Export Settings。在 Figma UI 中设计师可以为节点预设导出格式如 PNG、JPG、SVG和倍率如 1x, 2x, 3x。API 可以读取这些预设也可以动态指定导出参数。对于 Cocos Creator 项目我们通常需要 PNG 格式并且可能根据平台需要不同倍率的图片。另一个重要约束是访问权限与速率限制。你需要一个 Figma 个人访问令牌Personal Access Token来调用 API。免费账户的 API 调用有频率限制在脚本中需要加入适当的延时例如setTimeout以避免触发限制。1.2 Cocos Creator 的资源管理规则路径、Meta 与导入Cocos Creator 并非简单地将图片文件放入assets目录就能使用。引擎通过“资源管理器”Assets面板管理资源每个资源文件都对应一个.meta文件用于存储资源的 UUID、导入配置如纹理类型、裁剪数据等元数据。资源路径所有游戏资源都应放在assets目录或其子目录下。常见的做法是为 UI 资源创建assets/textures/ui这样的子目录。Meta 文件当你在 Cocos Creator 编辑器中拖入一个新图片时引擎会自动为其生成一个同名的.meta文件。如果你通过脚本直接复制图片文件到assets目录下次打开项目时Cocos Creator 会检测到没有.meta文件的资源并为其生成一个。但是自动生成的.meta文件可能使用默认配置不一定符合你的需求例如SpriteFrame 的裁剪矩形可能不对。最佳实践更可靠的方式是要么在 Cocos Creator 中先手动创建一次正确的资源将其.meta文件作为模板要么在脚本中调用 Cocos Creator 的命令行接口或理解其.meta文件格式以编程方式创建或修改.meta文件。对于自动化导入我们通常采用“模板.meta文件 复制替换”的策略。理解了这两端的基本规则我们就可以开始设计自动化流程了通过 Figma API 拿到图片 URL - 下载图片 - 根据命名规则保存到指定 Cocos 目录 - 处理或复用.meta文件 - 在 Cocos Creator 中刷新资源。2. 环境准备与关键配置这个自动化流程不依赖于特定操作系统可以在 Windows、macOS 或 Linux 上运行。我们将使用 Node.js 环境来编写脚本因为它能很好地处理 HTTP 请求和文件系统操作。2.1 基础环境配置首先确保你的开发机器上已经安装了 Node.js建议版本 16 或以上和 npm。你可以通过命令行验证node --version npm --version接下来创建一个新的目录作为我们的脚本项目并初始化package.jsonmkdir figma-to-cocos-automation cd figma-to-cocos-automation npm init -y2.2 获取 Figma 访问凭证登录你的 Figma 账号。点击右上角个人头像进入 “Settings”。在左侧菜单找到 “Account”向下滚动找到 “Personal access tokens” 部分。点击 “Create new token”为其命名例如 “Cocos Auto Import”并确认创建。重要立即复制生成的令牌字符串。它只会显示一次如果丢失需要重新生成。将令牌保存在安全的地方。我们将在脚本中通过环境变量来使用它避免将敏感信息硬编码在代码里。在项目根目录创建一个.env文件确保该文件已被添加到.gitignore中# .env FIGMA_ACCESS_TOKEN你的个人访问令牌 FIGMA_FILE_ID你的设计文件IDFIGMA_FILE_ID可以从 Figma 设计文件的 URL 中获取。例如URL 为https://www.figma.com/file/AbCdEfGhIjKlMnOpQrStUv/My-Design那么AbCdEfGhIjKlMnOpQrStUv就是文件 ID。2.3 安装必要的 Node.js 依赖我们将安装几个关键的 npm 包axios或node-fetch用于调用 Figma API 和下载图片。dotenv用于加载.env文件中的环境变量。fs-extra提供比原生fs模块更强大的文件操作功能。sharp一个高性能的图片处理库可用于格式转换、缩放等可选但推荐。在项目目录下运行npm install axios dotenv fs-extra sharp3. 构建自动化导入脚本我们的脚本将分为几个模块化步骤获取文件数据、筛选需要导出的节点、批量下载图片、保存到 Cocos 项目。3.1 步骤一连接 Figma API 并获取文档结构创建一个名为sync.js的文件。首先配置环境并定义基础函数。// sync.js require(dotenv).config(); const axios require(axios); const fs require(fs-extra); const path require(path); // 从环境变量读取配置 const FIGMA_TOKEN process.env.FIGMA_ACCESS_TOKEN; const FIGMA_FILE_ID process.env.FIGMA_FILE_ID; // 你的 Cocos Creator 项目 assets 目录的绝对路径 const COCOS_ASSETS_PATH path.resolve(/path/to/your-cocos-project/assets); // UI 资源存放的子目录 const UI_TEXTURES_DIR textures/ui; // 创建 Axios 实例统一设置请求头 const figmaApi axios.create({ baseURL: https://api.figma.com/v1/, headers: { X-Figma-Token: FIGMA_TOKEN }, }); /** * 获取 Figma 文件的结构数据 */ async function getFigmaFile() { try { const response await figmaApi.get(files/${FIGMA_FILE_ID}); return response.data; } catch (error) { console.error(获取 Figma 文件失败:, error.message); if (error.response) { console.error(响应状态:, error.response.status); console.error(响应数据:, error.response.data); } process.exit(1); } }3.2 步骤二定位并筛选需要导出的节点Figma 文件是一个复杂的节点树。我们需要一个策略来定位哪些节点是需要导出的图片。常见策略有页面或画板命名约定例如将需要导出的画板命名为Export/Icon_Home。组件标记导出特定的组件Component。节点ID硬编码直接指定已知的节点ID适用于固定设计稿。下面的函数演示了如何递归遍历节点树并收集那些设置了导出设置exportSettings的节点。/** * 递归遍历节点树收集所有设置了导出设置的节点 * param {Object} node - Figma 节点对象 * param {Array} exportNodes - 收集到的节点数组 */ function collectExportNodes(node, exportNodes []) { // 如果该节点有导出设置则收集它 if (node.exportSettings node.exportSettings.length 0) { exportNodes.push({ id: node.id, name: node.name, exportSettings: node.exportSettings, }); } // 递归遍历子节点 if (node.children) { for (const child of node.children) { collectExportNodes(child, exportNodes); } } return exportNodes; } /** * 主函数执行同步流程 */ async function syncFigmaToCocos() { console.log(开始从 Figma 同步资源...); const figmaData await getFigmaFile(); const document figmaData.document; // 收集所有可导出节点 const nodesToExport collectExportNodes(document); console.log(找到 ${nodesToExport.length} 个待导出节点。); if (nodesToExport.length 0) { console.log(未找到任何设置了导出设置的节点。请检查 Figma 设计稿。); return; } // 下一步处理这些节点 await processNodes(nodesToExport); }3.3 步骤三批量下载图片并保存Figma API 提供了/v1/images/{file_id}端点来获取图片的下载 URL。我们需要传入节点 ID 和格式等参数。/** * 获取多个节点的图片下载URL * param {Array} nodeIds - 节点ID数组 * param {String} format - 导出格式如 png * param {Number} scale - 导出倍率如 1, 2, 3 */ async function getImageUrls(nodeIds, format png, scale 1) { const idsParam nodeIds.join(,); try { const response await figmaApi.get(images/${FIGMA_FILE_ID}, { params: { ids: idsParam, format, scale }, }); return response.data.images; // 返回一个 { nodeId: url } 的对象 } catch (error) { console.error(获取图片URL失败:, error.message); throw error; } } /** * 下载图片并保存到本地 * param {String} url - 图片下载地址 * param {String} filePath - 本地保存路径 */ async function downloadImage(url, filePath) { try { const response await axios({ url, method: GET, responseType: stream, }); const writer fs.createWriteStream(filePath); response.data.pipe(writer); return new Promise((resolve, reject) { writer.on(finish, resolve); writer.on(error, reject); }); } catch (error) { console.error(下载图片失败 ${url}:, error.message); throw error; } } /** * 处理节点集合获取URL、下载、保存 * param {Array} nodes - 待处理的节点信息数组 */ async function processNodes(nodes) { const nodeIds nodes.map(node node.id); // 假设我们导出1倍图 const imageUrls await getImageUrls(nodeIds, png, 1); // 创建目标目录 const targetDir path.join(COCOS_ASSETS_PATH, UI_TEXTURES_DIR); await fs.ensureDir(targetDir); for (const node of nodes) { const imageUrl imageUrls[node.id]; if (!imageUrl) { console.warn(未找到节点 ${node.name} (${node.id}) 的图片URL跳过。); continue; } // 生成文件名这里简单使用节点名建议根据项目规范清洗文件名如替换空格、特殊字符 let fileName ${node.name}.png; // 简单的文件名清洗替换空格为下划线移除非法字符 fileName fileName.replace(/\s/g, _).replace(/[:/\\|?*]/g, ); const filePath path.join(targetDir, fileName); console.log(正在下载: ${node.name} - ${fileName}); await downloadImage(imageUrl, filePath); console.log(已保存: ${filePath}); // 可选处理 .meta 文件见下文 await handleMetaFile(filePath, node); // 礼貌延时避免触发 Figma API 速率限制 await new Promise(resolve setTimeout(resolve, 200)); } console.log(所有资源同步完成); }3.4 步骤四处理 Cocos Creator 的 .meta 文件关键步骤这是确保资源能被 Cocos Creator 正确识别的关键。有两种策略策略A复制并重命名模板 .meta 文件推荐用于简单资源在 Cocos Creator 编辑器中手动导入一张正确配置的参考图片例如template.png。将其.meta文件template.png.meta复制到脚本目录作为模板。在脚本中每当下载新图片后复制这个模板.meta文件并重命名为与新图片对应的.meta文件名。重要.meta文件中的uuid字段必须是唯一的。Cocos Creator 使用 UUID 来标识资源。因此你需要生成一个新的 UUID 并替换模板文件中的旧 UUID。const { v4: uuidv4 } require(uuid); // 需要安装 uuid 包npm install uuid /** * 处理或生成资源的 .meta 文件 * param {String} imageFilePath - 图片文件路径 */ async function handleMetaFile(imageFilePath, nodeInfo) { const metaFilePath ${imageFilePath}.meta; const templateMetaPath path.resolve(__dirname, template.png.meta); if (await fs.pathExists(templateMetaPath)) { // 读取模板内容 let metaContent await fs.readFile(templateMetaPath, utf8); // 生成新的 UUID const newUuid uuidv4().replace(/-/g, ); // 替换 UUID注意.meta 文件是 JSON 格式但直接字符串替换需谨慎 // 更稳妥的方式是解析 JSON修改再序列化。 try { const metaObj JSON.parse(metaContent); metaObj.uuid newUuid; // 可以根据 nodeInfo 进一步调整其他属性如 ver、subMetas等 metaContent JSON.stringify(metaObj, null, 2); } catch (e) { console.warn(解析模板 .meta 文件失败将使用新 UUID 简单替换: ${e.message}); // 简单替换假设模板中有一个占位符 UUID metaContent metaContent.replace(/[a-f0-9]{32}/g, newUuid); } // 写入新的 .meta 文件 await fs.writeFile(metaFilePath, metaContent, utf8); console.log(已生成 .meta 文件: ${metaFilePath}); } else { console.warn(未找到模板 .meta 文件: ${templateMetaPath}。Cocos Creator 将在下次打开时自动生成但配置可能为默认值。); } }策略B调用 Cocos Creator 命令行更准确但复杂Cocos Creator 提供了命令行工具cocos可以执行资源导入等操作。理论上可以通过child_process执行cocos命令来触发资源导入并生成.meta文件。但这需要配置 Cocos Creator 的环境变量并且不同版本命令可能不同实现起来更复杂通常用于 CI/CD 流水线。对于大多数情况策略A已经足够。确保你的template.png.meta文件中的纹理类型textureType等配置符合你的项目要求例如UI 精灵通常使用Sprite类型。4. 运行验证与集成到工作流4.1 首次运行与验证确保.env文件已正确配置。在 Cocos Creator 项目中准备好template.png和template.png.meta。将sync.js中的COCOS_ASSETS_PATH修改为你项目的绝对路径。在 Figma 中为几个测试节点设置好导出设置格式 PNG。在终端运行脚本node sync.js观察控制台输出确认图片被下载并保存到assets/textures/ui/目录下同时生成了对应的.meta文件。打开或刷新你的 Cocos Creator 项目。在资源管理器中你应该能看到新导入的图片资源并且可以正常拖拽到场景或 UI 中使用。4.2 与 AI 辅助工具Codex/Cursor 等集成自动化脚本的价值在于可重复执行。你可以创建 npm 脚本在package.json中添加scripts: { sync:figma: node sync.js }之后只需运行npm run sync:figma。设置文件监听使用nodemon等工具监听本地某个 Figma 导出的 JSON 文件需额外编写导出逻辑变化时自动触发同步脚本。在 AI 工具中快速调用在 Cursor、VS Code 等编辑器中你可以通过终端面板直接运行命令。更进阶的做法是为 AI 助手如 Claude Code编写清晰的提示词Prompt描述整个流程AI 可以帮助你调试脚本或根据新的设计需求修改节点筛选逻辑。4.3 设计稿更新后的同步当 Figma 设计稿更新后确保需要同步的新节点已设置导出设置。再次运行node sync.js。脚本会根据当前文件结构重新获取所有设置了导出设置的节点并下载图片。如果图片已存在且未变化从网络层面可能仍会重新下载你可以添加本地文件哈希对比逻辑来优化。在 Cocos Creator 中刷新资源管理器即可。5. 常见问题排查与优化自动化流程难免会遇到问题。下面是一个排查清单按照从外到内、从网络到本地的顺序进行检查。问题现象可能原因检查与解决步骤脚本报错FIGMA_ACCESS_TOKEN未定义1..env文件不存在或路径不对。2..env文件格式错误。3. 未安装dotenv包。1. 确认.env文件在脚本同级目录。2. 检查.env文件内容确保是KEYVALUE格式无多余空格和引号。3. 运行npm list dotenv确认包已安装。Figma API 返回 403 或 401 错误1. 访问令牌无效或已过期。2. 令牌权限不足。3. 文件 ID 错误或无权访问该文件。1. 去 Figma 设置页重新生成令牌并更新.env文件。2. 确认文件 URL 中的 ID 是否正确并确认该账号有访问权限。API 返回 429 错误请求过多触发了 Figma API 的速率限制。在processNodes循环中增加延时如setTimeout建议每次请求间隔 200-500 毫秒。图片下载成功但 Cocos Creator 中不显示或显示为粉色1. 图片未放在assets目录下。2. 缺少.meta文件或.meta文件损坏。3..meta文件 UUID 重复或格式错误。4. 图片格式 Cocos 不支持。1. 检查COCOS_ASSETS_PATH配置的路径是否正确。2. 确认图片文件旁有同名的.meta文件。3. 检查.meta文件是否为合法 JSON且uuid是唯一的 32 位十六进制字符串无横杠。4. 确保从 Figma 导出的是 PNG 或 JPG 格式。图片在 Cocos 中裁剪框不正确模板.meta文件中的trimType、width,height等属性与下载的图片尺寸不匹配。1. 使用一个尺寸和内容与目标资源接近的图片创建模板。2. 考虑在脚本中动态计算图片尺寸并更新.meta文件中的width和height字段需要解析 PNG 文件头或使用sharp库。节点名称包含特殊字符导致保存失败文件名包含操作系统不允许的字符如 \ / : * ? 。只想导出特定画板或页面的内容脚本当前导出了所有带导出设置的节点。修改collectExportNodes函数添加过滤逻辑。例如只遍历特定页面node.name ‘Page 1’下的节点或只处理名称以icon/开头的节点。6. 生产环境最佳实践与扩展方向将脚本用于个人项目或小团队很方便但要集成到团队工作流或生产环境还需要考虑以下几点配置文件化将 Figma 文件 ID、目标目录、导出格式、命名规则、需要跳过的页面等配置抽离到单独的config.json文件中便于不同项目或设计稿复用脚本。增量更新与哈希对比每次全量下载既慢又浪费流量。可以为每个下载的图片计算 MD5 哈希并存储起来下次同步时先比较哈希只下载有变化的图片。多倍图支持UI 资源通常需要2x,3x等高清图。可以修改processNodes函数循环遍历不同的scale参数如 [1,2,3]并为下载的图片添加后缀如icon_home2x.png。同时需要生成或调整对应的.meta文件这可能涉及 Cocos Creator 的自动缩放配置或cc.Sprite组件的srcSize设置。SVG 格式支持Figma 支持导出 SVG。Cocos Creator 也支持 SVG但需要不同的导入配置.meta文件内容不同。你需要为 SVG 准备另一个模板.meta文件并在脚本中根据导出格式决定使用哪个模板。与 CI/CD 集成在团队开发中可以将此脚本集成到 Git 钩子或 CI如 Jenkins、GitHub Actions中。当设计稿文件 ID 对应的版本有更新时自动触发同步流程并将变更提交到资源仓库。这需要妥善管理 Figma 令牌的保密问题。错误处理与通知增加更完善的错误处理当同步失败时通过邮件、Slack 或钉钉机器人通知相关负责人。生成资源索引文件脚本可以额外生成一个 JavaScript 或 TypeScript 文件导出一个对象将资源名称映射到其动态加载路径方便代码中引用避免硬编码路径字符串。自动化导入的核心价值在于将开发者从重复劳动中解放出来。通过搭建这样一个流程你可以确保设计资源与开发资源始终保持同步减少沟通成本让包括 AI 编程助手在内的整个工具链都运行在准确、最新的资源基础上。开始可以从一个简单的脚本入手覆盖核心的 PNG 导出流程再根据项目的实际复杂度逐步添加上述高级特性。 Figma到Cocos Creator自动化资源导入：基于Node.js的工程实践
在实际游戏开发或界面原型制作中设计师使用 Figma 完成高保真设计而开发者则需要将设计稿中的图标、图片等资源导入到 Cocos Creator 项目中并手动进行切图、重命名、调整格式。这个过程不仅重复枯燥而且容易出错一旦设计稿更新所有工作又得重来一遍。对于使用 Codex、Claude Code、Cursor、OpenCode 等 AI 辅助编程工具的开发者来说如果能将设计资源自动化导入就能将更多精力集中在核心逻辑和 AI 提示工程上而不是繁琐的资源管理上。本文将围绕如何搭建一个从 Figma 到 Cocos Creator 的自动化导入流程展开。这个流程的核心是通过 Figma API 获取设计稿资源编写脚本自动下载、处理并放置到 Cocos Creator 项目的正确目录中最终实现“设计稿更新 - 一键同步资源”的自动化链路。我们将从理解 Figma API 和 Cocos Creator 项目结构开始逐步完成环境配置、脚本编写、流程集成和错误排查最终形成一个稳定可用的自动化工具链。无论你是独立开发者还是团队中的技术美术掌握这套方法都能显著提升 UI 资源的生产效率。1. 理解自动化流程的核心Figma API 与 Cocos 资源规范在动手写代码之前必须搞清楚两件事Figma 如何以编程方式提供设计资源以及 Cocos Creator 对资源文件有什么硬性要求。盲目调用 API 或随意放置文件只会导致流程在后期崩溃。1.1 Figma API 能提供什么节点、导出与约束Figma 的核心是一个基于节点的设计数据库。每个画板Frame、组件Component、实例Instance、矢量图形Vector甚至文本Text都是一个节点Node拥有唯一的id。通过 Figma 的 REST API我们可以获取文件结构、节点信息并请求导出特定节点为图片。一个关键概念是“导出设置”Export Settings。在 Figma UI 中设计师可以为节点预设导出格式如 PNG、JPG、SVG和倍率如 1x, 2x, 3x。API 可以读取这些预设也可以动态指定导出参数。对于 Cocos Creator 项目我们通常需要 PNG 格式并且可能根据平台需要不同倍率的图片。另一个重要约束是访问权限与速率限制。你需要一个 Figma 个人访问令牌Personal Access Token来调用 API。免费账户的 API 调用有频率限制在脚本中需要加入适当的延时例如setTimeout以避免触发限制。1.2 Cocos Creator 的资源管理规则路径、Meta 与导入Cocos Creator 并非简单地将图片文件放入assets目录就能使用。引擎通过“资源管理器”Assets面板管理资源每个资源文件都对应一个.meta文件用于存储资源的 UUID、导入配置如纹理类型、裁剪数据等元数据。资源路径所有游戏资源都应放在assets目录或其子目录下。常见的做法是为 UI 资源创建assets/textures/ui这样的子目录。Meta 文件当你在 Cocos Creator 编辑器中拖入一个新图片时引擎会自动为其生成一个同名的.meta文件。如果你通过脚本直接复制图片文件到assets目录下次打开项目时Cocos Creator 会检测到没有.meta文件的资源并为其生成一个。但是自动生成的.meta文件可能使用默认配置不一定符合你的需求例如SpriteFrame 的裁剪矩形可能不对。最佳实践更可靠的方式是要么在 Cocos Creator 中先手动创建一次正确的资源将其.meta文件作为模板要么在脚本中调用 Cocos Creator 的命令行接口或理解其.meta文件格式以编程方式创建或修改.meta文件。对于自动化导入我们通常采用“模板.meta文件 复制替换”的策略。理解了这两端的基本规则我们就可以开始设计自动化流程了通过 Figma API 拿到图片 URL - 下载图片 - 根据命名规则保存到指定 Cocos 目录 - 处理或复用.meta文件 - 在 Cocos Creator 中刷新资源。2. 环境准备与关键配置这个自动化流程不依赖于特定操作系统可以在 Windows、macOS 或 Linux 上运行。我们将使用 Node.js 环境来编写脚本因为它能很好地处理 HTTP 请求和文件系统操作。2.1 基础环境配置首先确保你的开发机器上已经安装了 Node.js建议版本 16 或以上和 npm。你可以通过命令行验证node --version npm --version接下来创建一个新的目录作为我们的脚本项目并初始化package.jsonmkdir figma-to-cocos-automation cd figma-to-cocos-automation npm init -y2.2 获取 Figma 访问凭证登录你的 Figma 账号。点击右上角个人头像进入 “Settings”。在左侧菜单找到 “Account”向下滚动找到 “Personal access tokens” 部分。点击 “Create new token”为其命名例如 “Cocos Auto Import”并确认创建。重要立即复制生成的令牌字符串。它只会显示一次如果丢失需要重新生成。将令牌保存在安全的地方。我们将在脚本中通过环境变量来使用它避免将敏感信息硬编码在代码里。在项目根目录创建一个.env文件确保该文件已被添加到.gitignore中# .env FIGMA_ACCESS_TOKEN你的个人访问令牌 FIGMA_FILE_ID你的设计文件IDFIGMA_FILE_ID可以从 Figma 设计文件的 URL 中获取。例如URL 为https://www.figma.com/file/AbCdEfGhIjKlMnOpQrStUv/My-Design那么AbCdEfGhIjKlMnOpQrStUv就是文件 ID。2.3 安装必要的 Node.js 依赖我们将安装几个关键的 npm 包axios或node-fetch用于调用 Figma API 和下载图片。dotenv用于加载.env文件中的环境变量。fs-extra提供比原生fs模块更强大的文件操作功能。sharp一个高性能的图片处理库可用于格式转换、缩放等可选但推荐。在项目目录下运行npm install axios dotenv fs-extra sharp3. 构建自动化导入脚本我们的脚本将分为几个模块化步骤获取文件数据、筛选需要导出的节点、批量下载图片、保存到 Cocos 项目。3.1 步骤一连接 Figma API 并获取文档结构创建一个名为sync.js的文件。首先配置环境并定义基础函数。// sync.js require(dotenv).config(); const axios require(axios); const fs require(fs-extra); const path require(path); // 从环境变量读取配置 const FIGMA_TOKEN process.env.FIGMA_ACCESS_TOKEN; const FIGMA_FILE_ID process.env.FIGMA_FILE_ID; // 你的 Cocos Creator 项目 assets 目录的绝对路径 const COCOS_ASSETS_PATH path.resolve(/path/to/your-cocos-project/assets); // UI 资源存放的子目录 const UI_TEXTURES_DIR textures/ui; // 创建 Axios 实例统一设置请求头 const figmaApi axios.create({ baseURL: https://api.figma.com/v1/, headers: { X-Figma-Token: FIGMA_TOKEN }, }); /** * 获取 Figma 文件的结构数据 */ async function getFigmaFile() { try { const response await figmaApi.get(files/${FIGMA_FILE_ID}); return response.data; } catch (error) { console.error(获取 Figma 文件失败:, error.message); if (error.response) { console.error(响应状态:, error.response.status); console.error(响应数据:, error.response.data); } process.exit(1); } }3.2 步骤二定位并筛选需要导出的节点Figma 文件是一个复杂的节点树。我们需要一个策略来定位哪些节点是需要导出的图片。常见策略有页面或画板命名约定例如将需要导出的画板命名为Export/Icon_Home。组件标记导出特定的组件Component。节点ID硬编码直接指定已知的节点ID适用于固定设计稿。下面的函数演示了如何递归遍历节点树并收集那些设置了导出设置exportSettings的节点。/** * 递归遍历节点树收集所有设置了导出设置的节点 * param {Object} node - Figma 节点对象 * param {Array} exportNodes - 收集到的节点数组 */ function collectExportNodes(node, exportNodes []) { // 如果该节点有导出设置则收集它 if (node.exportSettings node.exportSettings.length 0) { exportNodes.push({ id: node.id, name: node.name, exportSettings: node.exportSettings, }); } // 递归遍历子节点 if (node.children) { for (const child of node.children) { collectExportNodes(child, exportNodes); } } return exportNodes; } /** * 主函数执行同步流程 */ async function syncFigmaToCocos() { console.log(开始从 Figma 同步资源...); const figmaData await getFigmaFile(); const document figmaData.document; // 收集所有可导出节点 const nodesToExport collectExportNodes(document); console.log(找到 ${nodesToExport.length} 个待导出节点。); if (nodesToExport.length 0) { console.log(未找到任何设置了导出设置的节点。请检查 Figma 设计稿。); return; } // 下一步处理这些节点 await processNodes(nodesToExport); }3.3 步骤三批量下载图片并保存Figma API 提供了/v1/images/{file_id}端点来获取图片的下载 URL。我们需要传入节点 ID 和格式等参数。/** * 获取多个节点的图片下载URL * param {Array} nodeIds - 节点ID数组 * param {String} format - 导出格式如 png * param {Number} scale - 导出倍率如 1, 2, 3 */ async function getImageUrls(nodeIds, format png, scale 1) { const idsParam nodeIds.join(,); try { const response await figmaApi.get(images/${FIGMA_FILE_ID}, { params: { ids: idsParam, format, scale }, }); return response.data.images; // 返回一个 { nodeId: url } 的对象 } catch (error) { console.error(获取图片URL失败:, error.message); throw error; } } /** * 下载图片并保存到本地 * param {String} url - 图片下载地址 * param {String} filePath - 本地保存路径 */ async function downloadImage(url, filePath) { try { const response await axios({ url, method: GET, responseType: stream, }); const writer fs.createWriteStream(filePath); response.data.pipe(writer); return new Promise((resolve, reject) { writer.on(finish, resolve); writer.on(error, reject); }); } catch (error) { console.error(下载图片失败 ${url}:, error.message); throw error; } } /** * 处理节点集合获取URL、下载、保存 * param {Array} nodes - 待处理的节点信息数组 */ async function processNodes(nodes) { const nodeIds nodes.map(node node.id); // 假设我们导出1倍图 const imageUrls await getImageUrls(nodeIds, png, 1); // 创建目标目录 const targetDir path.join(COCOS_ASSETS_PATH, UI_TEXTURES_DIR); await fs.ensureDir(targetDir); for (const node of nodes) { const imageUrl imageUrls[node.id]; if (!imageUrl) { console.warn(未找到节点 ${node.name} (${node.id}) 的图片URL跳过。); continue; } // 生成文件名这里简单使用节点名建议根据项目规范清洗文件名如替换空格、特殊字符 let fileName ${node.name}.png; // 简单的文件名清洗替换空格为下划线移除非法字符 fileName fileName.replace(/\s/g, _).replace(/[:/\\|?*]/g, ); const filePath path.join(targetDir, fileName); console.log(正在下载: ${node.name} - ${fileName}); await downloadImage(imageUrl, filePath); console.log(已保存: ${filePath}); // 可选处理 .meta 文件见下文 await handleMetaFile(filePath, node); // 礼貌延时避免触发 Figma API 速率限制 await new Promise(resolve setTimeout(resolve, 200)); } console.log(所有资源同步完成); }3.4 步骤四处理 Cocos Creator 的 .meta 文件关键步骤这是确保资源能被 Cocos Creator 正确识别的关键。有两种策略策略A复制并重命名模板 .meta 文件推荐用于简单资源在 Cocos Creator 编辑器中手动导入一张正确配置的参考图片例如template.png。将其.meta文件template.png.meta复制到脚本目录作为模板。在脚本中每当下载新图片后复制这个模板.meta文件并重命名为与新图片对应的.meta文件名。重要.meta文件中的uuid字段必须是唯一的。Cocos Creator 使用 UUID 来标识资源。因此你需要生成一个新的 UUID 并替换模板文件中的旧 UUID。const { v4: uuidv4 } require(uuid); // 需要安装 uuid 包npm install uuid /** * 处理或生成资源的 .meta 文件 * param {String} imageFilePath - 图片文件路径 */ async function handleMetaFile(imageFilePath, nodeInfo) { const metaFilePath ${imageFilePath}.meta; const templateMetaPath path.resolve(__dirname, template.png.meta); if (await fs.pathExists(templateMetaPath)) { // 读取模板内容 let metaContent await fs.readFile(templateMetaPath, utf8); // 生成新的 UUID const newUuid uuidv4().replace(/-/g, ); // 替换 UUID注意.meta 文件是 JSON 格式但直接字符串替换需谨慎 // 更稳妥的方式是解析 JSON修改再序列化。 try { const metaObj JSON.parse(metaContent); metaObj.uuid newUuid; // 可以根据 nodeInfo 进一步调整其他属性如 ver、subMetas等 metaContent JSON.stringify(metaObj, null, 2); } catch (e) { console.warn(解析模板 .meta 文件失败将使用新 UUID 简单替换: ${e.message}); // 简单替换假设模板中有一个占位符 UUID metaContent metaContent.replace(/[a-f0-9]{32}/g, newUuid); } // 写入新的 .meta 文件 await fs.writeFile(metaFilePath, metaContent, utf8); console.log(已生成 .meta 文件: ${metaFilePath}); } else { console.warn(未找到模板 .meta 文件: ${templateMetaPath}。Cocos Creator 将在下次打开时自动生成但配置可能为默认值。); } }策略B调用 Cocos Creator 命令行更准确但复杂Cocos Creator 提供了命令行工具cocos可以执行资源导入等操作。理论上可以通过child_process执行cocos命令来触发资源导入并生成.meta文件。但这需要配置 Cocos Creator 的环境变量并且不同版本命令可能不同实现起来更复杂通常用于 CI/CD 流水线。对于大多数情况策略A已经足够。确保你的template.png.meta文件中的纹理类型textureType等配置符合你的项目要求例如UI 精灵通常使用Sprite类型。4. 运行验证与集成到工作流4.1 首次运行与验证确保.env文件已正确配置。在 Cocos Creator 项目中准备好template.png和template.png.meta。将sync.js中的COCOS_ASSETS_PATH修改为你项目的绝对路径。在 Figma 中为几个测试节点设置好导出设置格式 PNG。在终端运行脚本node sync.js观察控制台输出确认图片被下载并保存到assets/textures/ui/目录下同时生成了对应的.meta文件。打开或刷新你的 Cocos Creator 项目。在资源管理器中你应该能看到新导入的图片资源并且可以正常拖拽到场景或 UI 中使用。4.2 与 AI 辅助工具Codex/Cursor 等集成自动化脚本的价值在于可重复执行。你可以创建 npm 脚本在package.json中添加scripts: { sync:figma: node sync.js }之后只需运行npm run sync:figma。设置文件监听使用nodemon等工具监听本地某个 Figma 导出的 JSON 文件需额外编写导出逻辑变化时自动触发同步脚本。在 AI 工具中快速调用在 Cursor、VS Code 等编辑器中你可以通过终端面板直接运行命令。更进阶的做法是为 AI 助手如 Claude Code编写清晰的提示词Prompt描述整个流程AI 可以帮助你调试脚本或根据新的设计需求修改节点筛选逻辑。4.3 设计稿更新后的同步当 Figma 设计稿更新后确保需要同步的新节点已设置导出设置。再次运行node sync.js。脚本会根据当前文件结构重新获取所有设置了导出设置的节点并下载图片。如果图片已存在且未变化从网络层面可能仍会重新下载你可以添加本地文件哈希对比逻辑来优化。在 Cocos Creator 中刷新资源管理器即可。5. 常见问题排查与优化自动化流程难免会遇到问题。下面是一个排查清单按照从外到内、从网络到本地的顺序进行检查。问题现象可能原因检查与解决步骤脚本报错FIGMA_ACCESS_TOKEN未定义1..env文件不存在或路径不对。2..env文件格式错误。3. 未安装dotenv包。1. 确认.env文件在脚本同级目录。2. 检查.env文件内容确保是KEYVALUE格式无多余空格和引号。3. 运行npm list dotenv确认包已安装。Figma API 返回 403 或 401 错误1. 访问令牌无效或已过期。2. 令牌权限不足。3. 文件 ID 错误或无权访问该文件。1. 去 Figma 设置页重新生成令牌并更新.env文件。2. 确认文件 URL 中的 ID 是否正确并确认该账号有访问权限。API 返回 429 错误请求过多触发了 Figma API 的速率限制。在processNodes循环中增加延时如setTimeout建议每次请求间隔 200-500 毫秒。图片下载成功但 Cocos Creator 中不显示或显示为粉色1. 图片未放在assets目录下。2. 缺少.meta文件或.meta文件损坏。3..meta文件 UUID 重复或格式错误。4. 图片格式 Cocos 不支持。1. 检查COCOS_ASSETS_PATH配置的路径是否正确。2. 确认图片文件旁有同名的.meta文件。3. 检查.meta文件是否为合法 JSON且uuid是唯一的 32 位十六进制字符串无横杠。4. 确保从 Figma 导出的是 PNG 或 JPG 格式。图片在 Cocos 中裁剪框不正确模板.meta文件中的trimType、width,height等属性与下载的图片尺寸不匹配。1. 使用一个尺寸和内容与目标资源接近的图片创建模板。2. 考虑在脚本中动态计算图片尺寸并更新.meta文件中的width和height字段需要解析 PNG 文件头或使用sharp库。节点名称包含特殊字符导致保存失败文件名包含操作系统不允许的字符如 \ / : * ? 。只想导出特定画板或页面的内容脚本当前导出了所有带导出设置的节点。修改collectExportNodes函数添加过滤逻辑。例如只遍历特定页面node.name ‘Page 1’下的节点或只处理名称以icon/开头的节点。6. 生产环境最佳实践与扩展方向将脚本用于个人项目或小团队很方便但要集成到团队工作流或生产环境还需要考虑以下几点配置文件化将 Figma 文件 ID、目标目录、导出格式、命名规则、需要跳过的页面等配置抽离到单独的config.json文件中便于不同项目或设计稿复用脚本。增量更新与哈希对比每次全量下载既慢又浪费流量。可以为每个下载的图片计算 MD5 哈希并存储起来下次同步时先比较哈希只下载有变化的图片。多倍图支持UI 资源通常需要2x,3x等高清图。可以修改processNodes函数循环遍历不同的scale参数如 [1,2,3]并为下载的图片添加后缀如icon_home2x.png。同时需要生成或调整对应的.meta文件这可能涉及 Cocos Creator 的自动缩放配置或cc.Sprite组件的srcSize设置。SVG 格式支持Figma 支持导出 SVG。Cocos Creator 也支持 SVG但需要不同的导入配置.meta文件内容不同。你需要为 SVG 准备另一个模板.meta文件并在脚本中根据导出格式决定使用哪个模板。与 CI/CD 集成在团队开发中可以将此脚本集成到 Git 钩子或 CI如 Jenkins、GitHub Actions中。当设计稿文件 ID 对应的版本有更新时自动触发同步流程并将变更提交到资源仓库。这需要妥善管理 Figma 令牌的保密问题。错误处理与通知增加更完善的错误处理当同步失败时通过邮件、Slack 或钉钉机器人通知相关负责人。生成资源索引文件脚本可以额外生成一个 JavaScript 或 TypeScript 文件导出一个对象将资源名称映射到其动态加载路径方便代码中引用避免硬编码路径字符串。自动化导入的核心价值在于将开发者从重复劳动中解放出来。通过搭建这样一个流程你可以确保设计资源与开发资源始终保持同步减少沟通成本让包括 AI 编程助手在内的整个工具链都运行在准确、最新的资源基础上。开始可以从一个简单的脚本入手覆盖核心的 PNG 导出流程再根据项目的实际复杂度逐步添加上述高级特性。