★ FEATURED ARTICLE 简介sketch-json-cli 是一款面向 Sketch 设计协作与版本管理场景的命令行工具适合需要将设计稿纳入 Git 工作流的前端工程师、UI 设计师及团队协作成员。它解决的核心问题是 Sketch 二进制文件难以做差异对比与版本追踪通过命令行即可在 .sketch 与 JSON 之间双向转换让设计文件也能像代码一样被审阅、合并与回溯。资源包共 8 个文件以 json 配置、js 主逻辑脚本、md 说明文档为主另含 yml 持续集成配置、license 授权文件与 lock 依赖锁定文件压缩包约 34KB体量轻巧、结构清晰。安装方式为全局 npm 安装支持 sketch-json 直接转 JSON、加 --json 参数反向还原为草图文件命令简洁易上手。目前已有 390 人学习下载适合希望把设计资产纳入工程化流程、探索设计版本管理的读者参考实践。1. 草图文件与 JSON 互转为什么一线团队开始把设计源文件当数据管设计稿评审完产品经理要一份「页面结构清单」前端要一份「图层命名对照表」测试要一份「组件树快照」——如果每次都靠人工从 Sketch 里复制粘贴这件事迟早会翻车。sketch-json-cli这类工具解决的正是这个痛点把.sketch草图文件转成 JSON让图层、画板、样式、文本变成可 diff、可查询、可脚本处理的结构化数据反过来也能把一份符合规范的 JSON 重新组装回.sketch文件交给设计师继续编辑。它适合三类人想把设计资产接入 CI 的前端工程师、需要批量审计设计稿的团队、以及做设计系统元数据管理的从业者。核心价值不在于「转换」这个动作本身而在于让草图文件从二进制黑匣子变成可版本管理的文本json数组、json查询函数这些日常处理 JSON 的手段终于能用在设计稿上了。2. 拆开 .sketch 文件它到底是不是一个压缩包2.1 草图文件的物理结构很多人第一次听说「把草图转 JSON」会以为要调用某个图形库去解析矢量路径。实际上.sketch文件本身就是一个 ZIP 归档只是扩展名被改了。你把它后缀改成.zip再解压会看到这样的目录结构# 把 .sketch 当作 zip 解压查看内部结构 mkdir sketch_unpacked cd sketch_unpacked unzip ../demo.sketch # 典型输出 # documents/ 页面与画板的 JSON 描述 # meta.json 文件元信息版本、作者、字体 # user.json 用户级配置 # previews/ 预览缩略图关键在documents/目录下每个页面是一个独立的 JSON 文件里面用layers数组描述图层树每个图层对象带_class字段标识类型artboard、text、rectangle、symbolInstance等。也就是说Sketch 官方自己就是用 JSON 存数据的sketch-json-cli做的事情本质上是「解包 规范化 可逆重组」而不是从零解析二进制格式。理解这一点后面所有参数和坑都好解释了。2.2 为什么需要 CLI 而不是手动解压手动解压能看但没法用。原因有三个第一documents/下的 JSON 是 Sketch 内部格式字段名带下划线前缀直接读很别扭第二多个页面文件之间靠do_objectID互相引用手动追踪不现实第三反向转换时 ZIP 的压缩参数、文件顺序、meta.json里的校验字段如果不对Sketch 会直接报「文件已损坏」。CLI 工具把这些脏活封装掉对外暴露干净的--input、--output、--pretty这类参数。常见做法是先用 CLI 转出可读 JSON再用jq或 Node 脚本做查询和统计最后需要回写时再转回去。2.3 转换方向与数据流两个方向的转换不是简单对称的。草图转 JSON 是「解包 扁平化 可选裁剪」JSON 转草图是「校验 重建引用 重新打包」。中间那份 JSON 是核心资产它的 schema 决定了你能做什么。我一般会把中间 JSON 分成三层meta文件级信息、pages页面数组、layers嵌套图层树。这样查询时用json查询函数式的路径表达式就能定位比如pages[0].layers[2].name。下面这张表是三个关键字段的对照方便你判断转换是否丢信息字段草图内部名中间 JSON 名是否可逆图层唯一标识do_objectIDid是图层类型_classtype是样式引用sharedStyleIDstyleRef需共享样式表存在提示如果中间 JSON 里丢了id或改了type的大小写反向转换基本必失败这是最常见的翻车点。3. 用 sketch-json-cli 跑通第一个转换命令、参数与输出校验3.1 安装与最小可运行命令假设你已经有一个 Node 环境建议 18 以上安装方式按你团队的习惯走 npm 或直接跑源码。最小转换命令长这样# 草图转 JSON输出到指定目录 sketch-json-cli to-json \ --input ./designs/homepage.sketch \ --output ./out/homepage.json \ --pretty \ --include-previews false # JSON 转回草图 sketch-json-cli to-sketch \ --input ./out/homepage.json \ --output ./rebuilt/homepage.sketch \ --strict--pretty让输出带缩进方便人读和 git diff--include-previews false跳过预览图能显著减小 JSON 体积--strict在反向转换时开启严格校验字段缺失直接报错而不是静默补默认值。这三个参数是我每次都会显式写的尤其是--strict它能把问题暴露在转换阶段而不是等 Sketch 打开时才炸。3.2 参数逐个说清楚--input和--output不用多解释但路径里的坑不少输入路径含空格要加引号输出目录不存在时部分版本不会自动创建建议先mkdir -p。--pretty的代价是文件变大如果只是给程序消费关掉它。--include-previews默认值各版本可能不同别依赖默认显式写。还有一个容易被忽略的--page-filter可以只导出指定页面做增量处理时很有用# 只导出名为 Checkout 的页面减少无关数据 sketch-json-cli to-json \ --input ./designs/app.sketch \ --output ./out/checkout.json \ --page-filter Checkout \ --pretty--page-filter的值是页面名不是索引所以要先确认页面命名。如果名字里有中文或特殊字符同样加引号。这个参数在大型文件上能把转换时间从几十秒压到几秒因为跳过了无关页面的图层树遍历。3.3 转换后怎么验证没丢东西转完不要直接信做三步校验。第一步比对图层数量# 统计中间 JSON 里的图层总数 jq [.pages[].layers[] | .. | objects | select(.type ! null)] | length \ ./out/homepage.json第二步抽查关键图层是否存在比如某个按钮的文本# 查找所有文本图层的内容 jq -r .pages[].layers[] | .. | objects | select(.typetext) | .text \ ./out/homepage.json第三步做一次往返测试转成 JSON 再转回草图用 Sketch 打开确认无报错、图层结构一致。往返测试是唯一能证明「可逆」的方法别省。如果往返后图层错位或样式丢失问题多半出在id引用或共享样式表上回到 3.1 的--strict模式重新跑一遍看它报哪一行。注意jq的..递归操作符在超大 JSON 上会吃内存图层超过五万时改用流式处理或分页导出。4. 把 JSON 接进日常流程查询、diff 与批量处理4.1 用 jq 做设计稿查询中间 JSON 一旦生成json查询函数那套思路就能直接搬过来。比如找出所有宽度小于 44 的可点击区域移动端触控热区审计# 筛选宽度小于 44 的矩形图层输出名称和尺寸 jq -r .pages[].layers[] | .. | objects | select(.typerectangle and .frame.width 44) | \(.name)\t\(.frame.width)x\(.frame.height) ./out/homepage.json这段的逻辑是递归遍历所有图层对象过滤出类型为矩形且宽度小于 44 的输出名称和尺寸。select里的条件可以按需叠加比如再加and .name | test(btn)只查按钮。参数上注意frame字段名要和你的中间 JSON schema 对齐不同工具可能叫frame或bounds先jq keys看一眼顶层结构再写。4.2 设计稿 diff 与 CI 集成把每次转换出的 JSON 提交到仓库就能用git diff看设计变更。但原始 JSON 的字段顺序可能不稳定导致 diff 噪音大。解决办法是转换时加--sort-keys如果工具支持或者在 CI 里先规范化# 规范化 JSON 键顺序减少无意义 diff jq -S . ./out/homepage.json ./out/homepage.sorted.json-S是 jq 的排序键选项。规范化后再 diff变更就只剩真正的内容改动。CI 里可以加一条规则如果 diff 中出现type或id的删除就阻断合并因为这通常意味着图层被误删。这套做法在多人协作的设计系统里特别值相当于给设计稿上了版本管理的后悔药。4.3 批量转换与增量处理一个项目几十个.sketch文件时逐个跑命令不现实。写个循环# 批量转换目录下所有草图文件 for f in ./designs/*.sketch; do name$(basename $f .sketch) sketch-json-cli to-json \ --input $f \ --output ./out/${name}.json \ --pretty --strict echo done: $name done逻辑很直白遍历、取基名、转换、打印进度。参数上--strict在批量场景更重要因为一个文件失败不该拖垮整批配合set -e或错误捕获决定是继续还是中断。增量处理则靠文件修改时间判断只转比上次输出新的文件避免每次全量跑。批量转换的坑在于内存几十个大文件连续跑可能 OOM中间加个sleep 1或分批处理能缓解。5. 避坑与排查转换失败时先看这五条5.1 现象反向转换后 Sketch 提示文件损坏原因通常是 ZIP 打包参数不对或者meta.json里的commit、version字段和实际内容不匹配。解决用--strict模式重跑确认工具是否自动重建了meta.json如果手动改过中间 JSON检查有没有动meta层。最稳的办法是拿一个官方 Sketch 新建的空文件解包对照它的meta.json字段结构。5.2 现象图层 ID 冲突打开后图层重叠原因是对中间 JSON 做了合并或复制操作产生了重复的id。Sketch 靠do_objectID唯一标识图层重复就会错乱。解决在写回前跑一遍去重脚本用jq检查id是否有重复# 检查重复的图层 id jq -r [.pages[].layers[] | .. | objects | .id] | group_by(.) | map(select(length1)) | .[] \ ./out/homepage.json有输出就说明有冲突需要重新生成 ID。别手动改用工具或脚本统一重分配。5.3 现象文本内容丢失或变成乱码原因是字符编码没统一或者中间 JSON 在传输时被转成了非 UTF-8。解决确认转换命令的输入输出都是 UTF-8jq处理时加--raw-output避免转义。如果原文含 emoji 或特殊符号检查工具版本是否支持必要时先做一次编码探测。5.4 现象共享样式和 Symbol 引用断裂原因是中间 JSON 只导出了页面图层没带上sharedStyles和symbols定义。解决转换时确认是否包含这些顶层字段--include-shared之类的参数要打开。如果工具不支持就得在中间 JSON 里手动保留sharedStyleRef的映射表写回时重建。5.5 现象大文件转换卡死或内存溢出原因是递归遍历整棵图层树时把预览图也读进了内存。解决关掉--include-previews用--page-filter缩小范围或者分页导出。Node 环境可以加--max-old-space-size4096提高堆上限但根治还是减少单次处理的数据量。6. 进阶把中间 JSON 当设计系统元数据源走到这一步转换本身已经不是目的了。我现在的习惯是把每次生成的中间 JSON 存进一个专门的仓库按版本打 tag然后用它驱动三件事。第一件是组件覆盖率统计——用jq统计symbolInstance的数量和分布看哪些页面还在用游离图层而不是组件# 统计每个页面的 Symbol 实例数 jq -r .pages[] | \(.name)\t\([.layers[] | .. | objects | select(.typesymbolInstance)] | length) \ ./out/app.json第二件是设计 token 提取——把文本样式和颜色样式抽出来生成一份和前端主题变量对照的表发现不一致就报警。第三件是变更影响分析——当某个 Symbol 被修改时通过symbolID反查所有引用它的页面提前通知相关开发。这三件事的价值远超「转个格式」它让设计稿真正进入了工程化的数据流。验证方法上我一般会维护一个「黄金样本」挑一个结构完整、包含文本/形状/Symbol/共享样式的草图文件每次工具升级或参数调整后对它跑一遍往返转换比对输出 JSON 的哈希和图层数量。哈希变了不一定是错但必须人工确认变更原因。这个习惯帮我拦下过好几次因为工具默认值变化导致的静默丢数据。最后说个具体技巧中间 JSON 的 schema 版本一定要显式记录在文件里比如加一个schemaVersion字段。工具升级后 schema 可能变没有版本号的话旧 JSON 写回新工具就是灾难。我吃过这个亏现在所有转换产物第一行就是版本标记。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
