【Scratch×AI 系列 01】先搞懂 SB3：为什么 AI 生成的 project.json 常常“导不进 Scratch”

摘要.sb3 不是“神秘格式”本质就是 ZIP结构错一处Scratch 直接拒收或白屏project.json 有一套“最小可用”骨架targets、meta 等字段缺失会导致 target 不加载素材必须放在压缩包根目录且文件名要符合md5.ext规范否则就会出现“舞台/精灵不显示”这一篇把 SB3 的容器规则讲透后面 3 篇再逐层深入 targets、blocks、inputs/fields 与监视器/克隆等坑系列导航01先搞懂 SB3本文02Target 与素材引用舞台/精灵为什么会消失03Blocks 结构与 inputs/fieldsAI 最容易写错的地方04进阶与踩坑清单从“能导入”到“能稳定跑”05为什么要做 xw-scratch-init目录规范就是生产力06为什么要拆成 plan/exec/build把 AI 从“胡写 JSON”变成“稳定流水线”07流程使用上从想法到 planX.md验收标准怎么写才有用08流程使用下从 planX 到可导入的 .sb3打包与自检背景我为什么要写一份“SB3 规范文件”起因很简单家里老大信息技术课要做 Scratch 小游戏我想用 AI 来加速开发。结果第一轮就翻车AI 生成了一个看似“像那么回事”的 project.json但导入 Scratch 后要么直接报错要么能打开却啥都不显示。后来我才意识到Scratch 的工程文件SB3是一套严格的结构约定。AI 只要漏掉某个字段、把资源放错位置、把素材命名写成路径而不是 md5ext就会出现“导不进”“导入白屏”“精灵消失”等问题。所以我做了两件事把 Scratch 3SB3工程结构写成一份可执行的“规范参考”Scratch3_SB3_配置文件规范.md再把需求 → 生成 project.json → 打包 sb3 这条链路做成工具化流程避免每次都靠运气本文先讲最外层.sb3 容器到底是什么它对“文件摆放”和“命名”有什么硬要求。1. .sb3 到底是什么一句话.sb3 就是 ZIP 压缩包。它必须满足两件事压缩包根目录包含project.json压缩包根目录包含该 project.json 引用到的素材文件背景/造型/声音等Scratch 不会去压缩包子目录里“递归找素材”也不会理解你把素材命名成assets/sprite/hero.svg这种路径式引用。你可以把 SB3 想成一个“自包含的可移植工程快照”它不是仓库结构不认识你的 assets 目录。2. project.json 的顶层骨架最小可用根据 Scratch Wiki 的格式描述Scratch 3 项目顶层字段主要是targetsmonitorsextensionsmeta一个最常见、最稳妥的骨架如下字段允许为空数组但建议都保留{targets:[],monitors:[],extensions:[],meta:{semver:3.0.0,vm:0.2.0-...,agent:...}}这里的关键点不是“能不能省略”而是“你要对齐 Scratch 的读取习惯”targets必须存在且至少包含 1 个舞台isStage: truename: Stagemeta强烈建议保留很多第三方解析器/工具链会依赖它判断兼容性规范参考文件在这里建议先收藏后面会反复用到Scratch3_SB3_配置文件规范.md3. 素材文件为什么必须叫md5.extSB3 的素材命名规则非常“工程化”每个素材文件按内容计算 MD532 位十六进制小写文件名就是md5.ext例如3d5f1c7e6a8b9c0d1e2f3a4b5c6d7e8f.svga1b2c3d4e5f60718293a4b5c6d7e8f90.wav然后 project.json 里会记录两类信息assetIdmd5不带扩展名md5extmd5 扩展名带扩展名如果你写成“相对路径”{md5ext:assets/sprite/sprite1/plane.svg}Scratch 官方编辑器导入 .sb3 时通常不会去找assets/...这种路径于是你会得到最常见的现象项目能打开但舞台/精灵一片空白角色列表还在但造型面板是空的这也是为什么我把流程拆成两段生成阶段允许用assets/...这种人类可读路径方便在仓库里管理素材打包阶段统一转换为md5.ext并把素材平铺到 build 根目录再压缩成标准 .sb34. 最小自检你手里的 .sb3 真的“合格”吗如果你已经有一个 .sb3 文件或准备自己打包可以用这个清单做快速自检压缩包根目录必须有project.json压缩包根目录所有素材文件名形如md5.ext不要带目录project.json顶层必须有targets且第一个 target 通常是舞台name: Stagetargets[].costumes[].md5ext/targets[].sounds[].md5ext引用到的文件名在压缩包根目录真实存在结语容器规则是“第一道闸门”很多 AI 生成失败其实不是“逻辑写错”而是连容器规范都没过文件没放对、命名不对、引用对不上。下一篇我们进到 project.json 的第一层targets舞台/精灵应该有哪些字段素材与 target 如何绑定。