简介这份资源是一个基于 skpm 构建的 Sketch 插件实验项目面向需要将 JSON 数据批量转换为 Sketch 设计文件的设计师与前端开发者尤其适合熟悉 Sketch 插件机制、希望用脚本打通数据与设计稿流程的中高级用户。压缩包共 9 个文件以 json 配置与示例数据、js 插件逻辑脚本为主另含 md 说明文档、png 图标资源及 lock 依赖锁定文件整体约 81KB体量轻便便于快速阅读源码与二次改造。项目已吸引 672 人学习下载具备一定参考热度。包内提供 sample 示例 JSON 与 manifest 清单配合 my-command.js 命令入口可帮助读者理解从 JSON 结构解析到 Sketch 图层生成的实现路径README 与构建脚本则交代了 npm 安装、build、watch、start 等开发流程适合作为学习 skpm 插件开发、自定义 Babel 配置与调试思路的实践样本。1. 装 Sketch 插件前先把 Node 和 skpm 版本对齐上周帮一位做设计系统的朋友处理一个 Sketch 插件需求很朴素把一份 JSON 设计稿描述转成 Sketch 文件。项目叫 json-sketchapp核心依赖是 skpm 这套 Sketch 插件构建工具链底层还牵着 SketchJavaScript 的运行环境。他本地 Node 是 18skpm 装的是最新版结果skpm build一路报错插件在 Sketch 里加载后直接白屏连日志都看不到。这类问题不是代码写错而是环境版本没对齐——Sketch 插件对 Node、skpm、Sketch 本体三者的版本匹配相当敏感装不好就是玄学白屏。这篇记录面向两类人一是第一次给 Sketch 写插件、想把 JSON 转 Sketch 流程跑通的开发者二是已经装过 skpm、但被构建产物和运行时坑过的熟手。下面按「环境清单 → 安装 → 配置 → 排错 → 验证」走一遍命令都能直接抄。2. 环境清单与版本选择Node、skpm、Sketch 三者怎么配2.1 先确认 Sketch 本体版本和插件目录Sketch 插件不是独立进程它跑在 Sketch 的 JavaScript 运行时里所以第一步永远是确认 Sketch 版本。打开 Sketch菜单里看「关于」常见做法是 70 以上版本对 skpm 构建产物的兼容性更稳。插件安装目录固定在# macOS 下 Sketch 插件目录确认目录存在再往下走 ls -la ~/Library/Application\ Support/com.bohemiancoding.sketch3/Plugins/这个目录是 Sketch 加载插件的唯一入口后面skpm link会把构建产物软链到这里。如果目录不存在说明 Sketch 没正常初始化过先启动一次 Sketch 再回来。注意路径里有空格命令行里必须转义或加引号这是新手第一个翻车点。2.2 Node 版本别追新锁 16 或 18 的 LTSskpm 对 Node 版本有实际要求常见做法是锁在 16.x 或 18.x 的 LTS。Node 20 以上在部分 skpm 版本里会出现依赖解析异常表现是skpm build阶段报Cannot find module但模块明明装了。我一般用 nvm 管理# 安装并切换到 Node 18 LTS避免系统自带 Node 干扰 nvm install 18 nvm use 18 node -v # 期望输出 v18.x.x npm -vnvm use只对当前终端生效换终端会回到默认版本所以每次开工前先node -v确认一遍。如果团队里有人用 16、有人用 18建议在项目根目录放.nvmrc写死版本进目录nvm use自动切换省得互相甩锅。2.3 skpm 版本与全局安装的取舍skpm 是 Sketch 插件脚手架和构建工具安装方式有两种全局npm i -g skpm或者项目内npx skpm。我倾向项目内安装版本跟着仓库走换机器不会因为全局版本不同导致构建产物不一致。初始化时用# 在空目录里初始化 skpm 项目按提示填插件名 npx skpm create json-sketchapp cd json-sketchapp npm installskpm create会生成package.json、src/目录和manifest.json。manifest.json是 Sketch 识别插件的身份证里面的identifier、commands字段后面配置章节会细说。全局安装的唯一好处是命令短但版本漂移的代价更大不建议。2.4 版本对照表照着填不会错组件推荐版本说明Sketch70 及以上低版本对 skpm 产物兼容差Node16.x / 18.x LTS20 以上易出依赖解析问题skpm项目内安装跟随 lock 文件避免全局版本漂移SketchJavaScript随 Sketch 内置不需要单独装这张表不是绝对真理但按它配能避开八成环境问题。装之前先把node -v、npm -v、Sketch 版本三项记下来出问题时对照比盲目重装高效得多。3. 安装与初始化从空目录到能构建的插件骨架3.1 创建项目并认识目录结构接上一章npx skpm create json-sketchapp跑完后目录大致是这样src/放插件源码manifest.json描述插件元信息和命令入口package.json管依赖和脚本。先看一眼package.json里的 scripts{ scripts: { build: skpm-build, watch: skpm-build --watch, start: skpm-build --watch --run, link: skpm-link } }build是一次性构建watch监听改动start构建后自动在 Sketch 里跑起来link把产物链到插件目录。日常开发用npm run start它省掉手动重启 Sketch 的步骤。这里要注意start依赖 Sketch 已经打开否则会提示找不到运行中的 Sketch 实例。3.2 安装依赖并处理原生模块项目初始化后执行npm install。如果package.json里带了需要编译的原生模块Node 版本不对会在这一步报node-gyp相关错误。常见做法是先确认 Xcode Command Line Tools 已装# 确认命令行工具可用缺了 node-gyp 编译会失败 xcode-select -p # 若未安装执行 xcode-select --install装完依赖后跑一次npm run build看dist/目录是否生成.sketchplugin产物。构建成功但 Sketch 里看不到插件多半是没执行link下一节说。3.3 把插件链到 Sketchlink 到底做了什么npm run link会在插件目录里创建一个指向项目dist/的软链。执行后回到 Sketch菜单「插件」下应该能看到插件名。如果没出现按顺序排查Sketch 是否重启过、软链目标是否存在、manifest.json的identifier是否重复。重复的 identifier 会让 Sketch 只认其中一个表现是改了代码没反应这是血泪经验里最常见的一条。# 手动确认软链是否建立成功 ls -la ~/Library/Application\ Support/com.bohemiancoding.sketch3/Plugins/ # 应看到指向项目 dist 目录的符号链接软链的好处是改代码重新构建后不用重新安装Sketch 重新加载插件即可生效。坏处是项目目录一挪软链就断插件在 Sketch 里报加载失败。所以项目路径定下来就别乱动或者断了就重新link一次。3.4 JSON 转 Sketch 的核心入口在哪json-sketchapp 的转换逻辑落在src/下的命令处理函数里manifest.json的commands字段把菜单项映射到具体函数。配置时重点看两处handlers指向的脚本路径要和构建产物一致script字段别写错相对路径。转换 JSON 时读取文件、解析结构、生成 Sketch 图层这一串逻辑在插件运行时执行调试靠console.log输出到 Sketch 的插件日志或者用skpm提供的调试方式看。入口配错的表现是菜单点了没反应日志里也没有输出先查manifest.json的路径映射。4. 配置与调试manifest、构建参数和日志怎么调4.1 manifest.json 三个必改字段manifest.json是插件配置的核心初始化生成的模板有三个字段建议按项目实际改name是菜单显示名identifier全局唯一commands里每个命令的script指向构建后的入口文件。改identifier后必须重新link否则 Sketch 里会出现新旧两个条目。commands的handlers字段决定点击菜单后执行哪个函数写错就是静默失败。{ name: json-sketchapp, identifier: com.example.json-sketchapp, commands: [ { name: Convert JSON to Sketch, identifier: convert-json, script: ./plugin.js, handlers: { run: onRun } } ] }script路径是相对构建产物目录的不是相对src/这点容易搞混。handlers.run对应源码里导出的onRun函数名字必须一致大小写敏感。4.2 构建参数watch 模式和产物路径skpm-build默认把产物输出到dist/--watch监听源码变化增量构建。如果项目里有多入口需要在package.json的skpm字段里配manifest路径和输出目录。常见做法是保持默认除非有特殊目录结构。构建慢的时候先看是不是node_modules被监听进去了watch范围过大是构建卡顿的常见原因。# 开发时用 watch 模式改完保存自动重建 npm run watch # 需要一次性干净构建时先清 dist 再 build rm -rf dist npm run buildrm -rf dist这步在产物异常时很管用尤其是改了manifest.json后 Sketch 行为没变化多半是旧产物没被覆盖。4.3 日志与调试白屏时先看哪里Sketch 插件运行时的console.log不会输出到终端而是进 Sketch 的插件日志。菜单里打开「插件 → 运行插件日志」或类似入口能看到运行时输出和报错堆栈。白屏且无日志通常是manifest.json解析失败或入口脚本没加载先确认dist/里有对应文件。有日志但报undefined is not a function多半是 SketchJavaScript API 版本差异查当前 Sketch 版本对应的 API 文档别照抄旧版示例。4.4 转换流程的参数取舍JSON 转 Sketch 时图层命名、坐标单位、颜色格式这几项参数直接影响产物可用性。坐标单位要和 Sketch 的画板坐标系对齐颜色建议统一转成 Sketch 支持的格式再写入。转换大文件时注意分批处理一次性生成大量图层会让 Sketch 卡死常见做法是加个进度提示或分块写入。这些参数没有标准答案按目标设计稿的规范定定完写进项目 README别只留在脑子里。5. 避坑与排查五条装坏了怎么救的记录5.1 插件菜单不出现link 显示成功现象npm run link没报错Sketch 插件菜单里找不到。原因多半是软链建了但目标dist/不存在或者 Sketch 没重启。解决先ls确认软链指向的目录真实存在再完全退出 Sketch 重开不是关窗口是菜单里退出。还不行就删掉插件目录里的旧软链重新link。5.2 构建报 Cannot find module 但依赖已装现象skpm build报模块找不到node_modules里明明有。原因通常是 Node 版本和依赖不匹配或者package-lock.json与node_modules不一致。解决切到 18 LTS删node_modules和 lock 文件重装别在版本混乱的状态下硬修。5.3 改了代码 Sketch 里没变化现象保存后重新构建成功插件行为还是旧的。原因一是watch没跑产物没更新二是 Sketch 缓存了旧插件。解决确认npm run watch在跑然后在 Sketch 里重新加载插件必要时退出重开。改了manifest.json必须重新link这条单独记。5.4 转换大 JSON 时 Sketch 卡死现象点转换后 Sketch 转圈无响应。原因是同步生成大量图层阻塞了运行时。解决把转换逻辑拆成分批每批之间让出执行权或者先只生成画板和分组图层按需展开。别指望一次写入几千个图层还能流畅。5.5 插件日志里报 API 不存在现象运行时报某个 Sketch API 方法 undefined。原因是 Sketch 版本和代码里用的 API 不匹配旧教程的写法在新版本里可能已废弃。解决对照当前 Sketch 版本的官方 API 参考改调用方式别直接复制网上旧示例。版本差异这块没有捷径只能查对应版本文档。6. 装完怎么验证三步确认 JSON 转 Sketch 真的跑通环境装完、插件链上最后一步是验证整条链路别停在「菜单能点开」就以为成了。我一般走三步每步都有明确的通过标准。第一步构建产物自检。执行干净构建后确认dist/里有.sketchplugin目录和入口脚本rm -rf dist npm run build ls dist/ # 期望看到 plugin.js 和 manifest.json 等产物产物缺失说明构建配置有问题先解决再往下别在残缺产物上调试运行时。第二步Sketch 内加载验证。完全退出 Sketch 再打开插件菜单里应出现配置的命令项。点开后看插件日志有没有初始化输出没有输出就是入口没加载回到manifest.json的script和handlers对照检查。第三步真实 JSON 转换验证。准备一份小体量 JSON字段覆盖画板、图层、颜色三类执行转换后检查 Sketch 里生成的图层数量、命名和坐标是否符合预期。通过标准是图层能选中、属性面板数值正确、再次保存不报错。大文件留到小文件通过后再试避免一上来就卡死分不清是环境问题还是数据问题。验证项通过标准失败先查构建产物dist 下有入口脚本构建配置、Node 版本插件加载菜单出现且日志有输出manifest 路径、软链转换结果图层数量与属性正确转换逻辑、API 版本这套验证顺序的价值在于把问题分层构建层、加载层、运行层哪层挂了就修哪层不用一锅乱炖。从那以后我每次装 Sketch 插件环境都强制先跑一遍这三步再动业务代码省下的排查时间远比多花的十分钟多。希望帮到你。本文还有配套的精品资源点击获取
设计与优化实战指南)
