简介sketch-json-cli 是一款面向 Sketch 设计协作与版本管理场景的命令行工具适合需要将设计稿纳入 Git 工作流的前端工程师、UI 设计师及团队协作开发者。它解决的核心问题是Sketch 原生文件为二进制格式难以进行差异比对与版本追踪而该工具可在 Sketch 文件与 JSON 之间双向转换让设计稿也能像代码一样被审阅、合并与回溯。资源包共 8 个文件以 json 配置、js 主逻辑脚本、md 说明文档为主另含 yml 持续集成配置、license 授权文件与 lock 依赖锁定文件压缩包约 34KB体量轻巧、结构清晰。安装方式为全局 npm 安装通过 sketch-json 命令即可完成 Sketch 转 JSON加 --json 参数则反向将 JSON 还原为 Sketch 文件命令行帮助信息完整。目前已有 390 人学习关注适合希望打通设计与开发协作链路、建立设计稿版本管理机制的读者参考使用。1. 草图文件与 JSON 互转一个被低估的版本管理入口设计稿的版本管理一直是个尴尬话题。Sketch 文件本质是个 zip 包二进制结构让 git diff 完全失效团队协作时只能靠v1-final-真的最终版.sketch这种命名硬扛。sketch-json-cli 这个工具的思路很直接把.sketch文件拆成可读的 JSON让版本控制系统能看懂每一处改动改完再打包回.sketch。它解决的不是设计问题而是工程问题——让设计稿进入和代码一样的版本管理流程。适合谁用前端团队需要追踪设计变更、设计系统维护者要批量处理图层、以及任何被「设计稿又更新了但不知道改了哪里」折磨过的人。下面从安装到双向转换再到实际协作场景把这条链路走通。2. 拆解 sketch-json-cli从安装到第一次双向转换2.1 环境准备与安装路径选择这个工具是 Node.js 生态的 CLI安装前先确认本机 Node 版本。Sketch 文件格式在不同版本间有差异工具本身对 Node 版本有最低要求常见做法是 Node 14 以上。安装方式有两种全局安装适合频繁使用本地安装适合锁定版本配合 CI。# 全局安装适合日常手动转换 npm install -g sketch-json-cli # 验证安装是否成功 sketch-json-cli --version # 如果全局安装权限有问题用 npx 直接跑 npx sketch-json-cli --help逻辑说明全局安装把命令注册到系统 PATH后续在任何目录都能调用。--version不只是看版本号还能验证二进制是否正确链接。如果公司内网 npm 源同步滞后用 npx 可以临时拉取最新版避免全局版本过旧导致解析失败。参数方面安装阶段没有太多可调的但要注意一点如果你之前装过旧版先npm uninstall -g sketch-json-cli再重装避免残留的旧解析器和新格式打架。我一般会在项目根目录放一个.nvmrc锁定 Node 版本团队里每个人nvm use之后版本一致减少「我这能跑你那报错」的玄学问题。2.2 把 .sketch 拆成 JSON命令与输出结构核心命令就一个方向sketch转json。但输出目录的结构决定了后续怎么用值得先看清楚。# 基本转换把 design.sketch 拆到 output 目录 sketch-json-cli to-json design.sketch -o ./output # 查看 output 目录结构 ls -la ./output # 典型输出 # document.json —— 画板、图层、文本的完整树 # meta.json —— 文件元信息、Sketch 版本 # user.json —— 用户自定义数据 # pages/ —— 按页面拆分的 JSON # images/ —— 提取出的位图资源逻辑说明.sketch文件解压后本身就是一组 JSON 加资源文件这个命令做的是解包加格式化让 JSON 可读、可 diff。-o指定输出目录不指定的话默认在当前目录建一个同名文件夹。pages/目录是按页面拆的大文件拆开后单页 diff 更精准不会因为一个页面改动导致整个 document.json 全变。参数上如果只想看结构不想提取图片可以加--no-images跳过资源导出转换速度会快很多。反过来如果设计稿里嵌了大量位图转换后 images 目录可能几百 MB提交 git 前记得配.gitignore排除只提交 JSON 部分。这里有个血泪经验第一次用的时候没排除 images一个 commit 塞了 200MB 进去后来清理历史花了半小时。2.3 JSON 回写为 .sketch还原时的参数控制反向转换是把改过的 JSON 重新打包成.sketch这一步的坑比正向多因为 JSON 里任何结构错误都会导致 Sketch 打不开。# 把 output 目录的 JSON 还原成 sketch 文件 sketch-json-cli to-sketch ./output -o design-restored.sketch # 带校验的还原先检查 JSON 结构再打包 sketch-json-cli to-sketch ./output -o design-restored.sketch --validate # 如果只想还原某个页面 sketch-json-cli to-sketch ./output --page Homepage -o homepage-only.sketch逻辑说明to-sketch读取目录里的 document.json、meta.json 和 pages/ 下的分页文件按 Sketch 的文件格式重新压缩打包。--validate会在打包前跑一遍结构校验检查必填字段和引用完整性能提前拦住大部分「打包成功但打开报错」的情况。--page参数适合只改了一个页面的场景避免全量还原引入意外变更。参数控制上-o指定输出文件名不加的话默认叫output.sketch。注意还原时的 Sketch 版本兼容性meta.json 里记录了原始文件的 Sketch 版本如果团队里有人用新版 Sketch 打开旧版还原的文件可能提示升级。常见做法是还原后先用 Sketch 打开确认再提交到设计稿仓库。如果还原后图层错位八成是 JSON 里某个坐标字段被手动改坏了用--validate能定位到具体文件。3. 版本管理实战让设计稿 diff 变得可读3.1 把 JSON 纳入 git 的工作流拆成 JSON 之后git diff 终于能看出设计稿改了什么。但直接提交整个 output 目录也有问题meta.json 里的时间戳每次转换都变会造成无意义的 diff。常见做法是配一个.gitattributes和过滤规则。# 在项目根目录初始化 git init mkdir design-json sketch-json-cli to-json design.sketch -o design-json # 添加 .gitignore排除图片和临时文件 cat design-json/.gitignore EOF images/ *.tmp EOF # 提交 JSON 版本 git add design-json/ git commit -m design: 初始版本 JSON 化逻辑说明排除 images 是因为位图资源体积大且 diff 无意义需要时从原始 .sketch 重新提取即可。meta.json 里的时间戳问题可以在提交前用脚本把generatedAt字段固定或者干脆在 diff 时忽略这个文件。我一般会在 CI 里加一步每次设计稿更新自动跑 to-json然后对比 JSON 差异生成变更摘要发到团队频道。参数上如果团队用 monorepo建议把 design-json 放在独立目录和前端代码分开提交避免设计变更触发前端构建。另外JSON 文件建议用 2 空格缩进diff 时行数少、可读性好工具默认输出就是 2 空格不用额外调。3.2 用 diff 定位图层级变更JSON 化之后最大的收益是能精确到图层级别看变更。下面是一个典型的 diff 场景按钮颜色从蓝色改成绿色。# 假设已经提交了 v1现在转换 v2 并对比 sketch-json-cli to-json design-v2.sketch -o design-json-v2 diff -r design-json design-json-v2 # 输出示例简化 # diff design-json/pages/Homepage.json design-json-v2/pages/Homepage.json # fillColor: #007AFF # --- # fillColor: #34C759逻辑说明diff -r递归对比两个目录输出里能直接看到哪个页面的哪个字段变了。上面这个例子能一眼看出是按钮填充色从系统蓝改成了系统绿。如果变更涉及图层增删diff 会显示整块 JSON 的增减配合--unified参数能看到上下文。参数上diff的-u选项输出统一格式更适合贴到 PR 描述里。如果变更量大可以用git diff --stat先看概览再决定要不要逐文件看。这里有个技巧把 JSON 按页面拆分后diff 的输出天然按页面分组review 时一个页面一个页面过不会漏。3.3 合并冲突的处理策略多人同时改设计稿时JSON 也会出现 merge conflict。和代码冲突不同设计稿的冲突往往涉及图层树结构手动合容易出错。# 拉取远程变更时出现冲突 git pull origin main # 提示design-json/pages/Homepage.json 冲突 # 查看冲突标记 grep -n design-json/pages/Homepage.json # 常见做法以某一版为基础用工具重新生成 # 先保留两版原始 sketch分别转换后对比 sketch-json-cli to-json design-mine.sketch -o /tmp/mine sketch-json-cli to-json design-theirs.sketch -o /tmp/theirs # 然后用 diff 工具逐块决定保留哪边逻辑说明JSON 冲突的根源是两个人改了同一个图层的同一个属性。直接编辑 JSON 合并风险高因为图层 ID 引用关系复杂。更稳的做法是回到 .sketch 文件层面让设计工具自己合并或者指定一个人作为「合并负责人」以他的版本为基础重新应用另一方的改动。参数上git 的merge.conflictStyle可以设成diff3这样冲突标记里会显示原始版本方便判断。另外如果团队用 Sketch 的 Cloud 协作其实可以绕过 git 合并但那样就失去了版本追溯能力。我一般建议小团队用 git 人工合并大团队用设计系统 组件化减少冲突面。4. 避坑与排查转换失败时的五个检查点4.1 转换报错「Invalid sketch file」现象执行to-json时直接报错提示文件格式无效。原因通常是 .sketch 文件本身损坏或者是从聊天工具下载时被截断。解决先用 Sketch 打开确认文件正常如果打不开就是源文件问题如果能打开但工具报错检查文件是否被其他进程占用。另外Sketch 新版本有时会改内部格式工具版本过旧也会误判升级到最新版再试。4.2 还原后图层错位或丢失现象to-sketch成功但用 Sketch 打开发现图层位置全乱或部分图层消失。原因一般是 JSON 里某个图层的frame字段被手动改成了非法值或者layers数组的引用 ID 对不上。解决还原时加--validate它会输出具体哪个文件的哪个字段有问题。如果是手动改过 JSON回退到上一次提交的版本重新改。4.3 git diff 出现大量无意义变更现象只改了一个按钮颜色diff 却显示几百行变化。原因是 meta.json 里的时间戳或版本号每次转换都变或者 JSON 的键顺序不稳定。解决在.gitattributes里把 meta.json 标记为-diff或者提交前用脚本固定时间戳字段。另外确认工具版本一致不同版本的序列化顺序可能不同。4.4 图片资源丢失现象JSON 转换时加了--no-images后来需要图片时发现 images 目录是空的。原因就是跳过了资源导出。解决重新跑一次不带--no-images的转换或者从原始 .sketch 文件里手动解压。注意 images 目录不要提交到 git但本地要保留否则还原时图片会缺失。4.5 大文件转换超时现象设计稿超过 100MB 时转换命令卡住或超时。原因是 Node 默认内存限制和递归解析深度。解决用NODE_OPTIONS--max-old-space-size4096提高内存上限或者先用 Sketch 把大文件拆成多个小文件再转换。常见做法是超过 50MB 的设计稿就拆分按页面或模块分开管理。5. 进阶技巧用脚本自动化设计稿同步5.1 写一个监听变更的同步脚本手动转换终究麻烦我一般会写个脚本监听 .sketch 文件变化自动转 JSON 并提交。下面是一个基于 Node 的简易实现// watch-sketch.js const fs require(fs); const { execSync } require(child_process); const path require(path); const SKETCH_FILE ./design.sketch; const OUTPUT_DIR ./design-json; // 监听文件变化 fs.watch(SKETCH_FILE, (eventType) { if (eventType change) { console.log(检测到设计稿变更开始转换...); try { // 转换 JSON execSync(sketch-json-cli to-json ${SKETCH_FILE} -o ${OUTPUT_DIR}, { stdio: inherit }); // 自动提交 execSync(git add ${OUTPUT_DIR} git commit -m design: 自动同步 $(date %Y%m%d-%H%M%S), { stdio: inherit }); console.log(同步完成); } catch (err) { console.error(转换失败, err.message); } } }); console.log(正在监听 ${SKETCH_FILE} 的变化...);逻辑说明fs.watch监听文件修改事件触发后依次执行转换和 git 提交。execSync用同步方式保证顺序避免转换没完就提交。提交信息里带时间戳方便回溯。这个脚本适合本地开发时挂着设计稿一保存就自动进版本库。参数上fs.watch在某些系统上可能触发多次事件可以加个防抖比如 500ms 内只执行一次。另外如果团队用 CI可以把这段逻辑放到流水线里设计稿推到仓库后自动转换并生成变更报告。5.2 验证转换完整性的方法转换完怎么确认没丢东西我习惯用「往返测试」转成 JSON 再转回 .sketch然后用 Sketch 打开对比。更工程化的做法是对比文件哈希和图层数量。# 往返转换 sketch-json-cli to-json design.sketch -o /tmp/roundtrip sketch-json-cli to-sketch /tmp/roundtrip -o design-roundtrip.sketch # 对比原始文件和往返文件的图层数量 # 用 jq 统计 JSON 里的图层数 jq [.. | objects | select(has(layers)) | .layers | length] | add /tmp/roundtrip/document.json # 对比文件大小会有差异但不应差一个数量级 ls -lh design.sketch design-roundtrip.sketch逻辑说明jq命令递归统计所有layers数组的长度之和得到图层总数。往返转换后图层数应该一致如果少了说明转换过程中丢了数据。文件大小对比是辅助判断因为压缩率不同大小有差异正常但差太多就有问题。参数上jq的..是递归下降select(has(layers))筛选出有 layers 字段的对象。如果图层数对不上重点检查 pages 目录下的分页文件是否完整。我一般会在 CI 里加这个校验图层数不一致就阻断合并。5.3 一个我踩过的坑有次团队协作两个人同时改了同一个页面git 合并时我图省事直接选了「保留我的版本」结果对方的改动全丢了。后来发现 JSON 冲突不能靠选边解决得回到 .sketch 层面重新合并。从那以后我每次遇到设计稿冲突都强制走一遍「双方原始文件分别转换 → diff 对比 → 人工逐块合并 → 往返验证」的流程再也不敢偷懒。希望帮到你。本文还有配套的精品资源点击获取