做信息技术类相关工作或者在学校机房带过课的朋友大概率都遇到过这种场景课表排好了教案写好了结果上课那天外网不稳定学生打开 Scratch 在线版要么加载半天出一个白屏要么角色库空荡荡点啥都没反应。一堂课就四十分钟光折腾网络就耗掉一半。我自己也在这个坑里反复横跳过好几次后来干脆把 Scratch 离线部署这件事彻底研究了一遍——从源码构建、静态资源部署到各种资源缺失、页面显示异常把能踩的坑都踩了一遍。这篇博文就是我整理出来的一套完整复现记录既有操作步骤也有排查思路希望能给同样被这件事困扰的朋友省点时间。再说一句这里说的“from scratch”和那本大模型书籍没关系咱们聊的是 MIT 那个图形化编程工具。下面的内容适合三类人看一是学校和培训机构的老师需要在机房或局域网里部署一套稳定的 Scratch二是教育类软件的技术维护人员需要处理离线环境下的各种资源问题三是对 scratch-gui 二次开发感兴趣的开发者可以借此了解它的构建流程和部署原理。零基础的朋友也可以照着操作我会把涉及的基础概念尽量说明白。1. 想清楚再动手离线版部署的三条路线怎么选1.1 官方 Scratch Desktop单机省事但解决不了机房问题很多人一说“离线版”第一反应就是去官网下载 Scratch Desktop 桌面应用。这个东西确实是官方出的本质上是把 Scratch 3.0 的网页版套了一层 Electron 外壳变成可以在 Windows、macOS 上直接运行的桌面软件。优点很直观下载安装就能用不依赖外网单台电脑上跑得很流畅。但如果你仔细想想机房或者培训机构的场景就会发现它有明显的短板。首先是无法集中管理——每台电脑都要单独安装版本升级时要一台一台重装工作量很大。其次是无法共享作品——学生做好的项目要么存到本地要么靠 U 盘拷贝老师想统一收集作业流程非常麻烦。更关键的是Scratch Desktop 的素材库和联网扩展能力其实依然依赖网络资源只是大概率你不会感知到因为使用路径经过了优化。所以我的结论是家庭个人使用Scratch Desktop 完全够用但如果你要管三十台、五十台机器这套方案效率太低了不是在解决问题是在制造新的负担。1.2 scratch-gui 源码构建灵活可控最适合局域网部署Scratch 3.0 的网页版并不是黑盒官方把主要前端代码开源了项目名就叫 scratch-gui。官网上的在线版、很多第三方定制版本质都是对这个项目进行构建、修改之后得到的产物。scratch-gui 构建完成后会输出一套纯静态文件HTML、JS、CSS、图片、字体等。这意味着你可以把它丢到任何一台能提供 HTTP 服务的机器上——Windows 上的 Nginx、Linux 服务器、树莓派甚至一台老笔记本——然后局域网里所有电脑打开浏览器访问这个地址就能用。好处非常明显一次部署全班访问客户端零安装作品可以通过浏览器直接下载到本地也可以配合其他工具做统一收集源码可控可以自定义语言、图标、扩展甚至屏蔽你不想让学生看到的功能完全掌控静态资源能针对离线环境做各种优化。当然代价是你需要会一点命令行操作能把 Node.js 环境跑起来。这部分我会在后面详细讲。1.3 第三方预打包版本省事但水很深在各类网盘和资源站里你能搜到很多别人打包好的“Scratch 离线版”有的几百 MB号称“完美破解”“全素材内置”。我劝你尽量别用。不是说我怀疑所有分享者而是这种非官方渠道的软件至少存在三类风险第一版本老旧很多是基于早期 scratch-gui 构建的缺功能不说还可能存在已知 bug第二来路不明你无法确认里面有没有被注入广告脚本、跟踪代码甚至恶意程序教育场景里客户端安全是底线第三素材库和扩展没有真离线只是换了个方式从某些服务器拉取一旦那个服务器失效问题依旧。从实际维护的角度讲自己手动构建一次 scratch-gui整个过程熟练后也就十来分钟。与其提心吊胆用别人的包不如把这个技能掌握在自己手里后面遇到问题也好排查。2. 本地构建前的环境准备先把 Node.js、Git 和镜像源搞定2.1 Node.js 版本选择与安装scratch-gui 是一个基于 Node.js 生态的前端项目构建过程依赖 webpack 等一系列工具所以第一步就是把 Node.js 装好。版本上我建议使用 16.x 或 18.x 的 LTS 版本。项目官方文档对版本没有过分苛刻的要求但太老的版本比如 12.x在安装依赖时容易遇到兼容性问题太新的版本比如 21偶尔也会因为依赖包未及时适配而报错。我实际测试下来Node 18 是最稳的整个过程基本不会出幺蛾子。安装方式很简单直接去 Node.js 官网下载对应系统的安装包一路下一步就行。安装完成后打开终端Windows 用 PowerShell 或 CMDmacOS/Linux 用自带的终端输入node -v npm -v如果能看到版本号说明安装成功。有一点需要提醒安装 Node.js 时你会得到一个配套的 npm 包管理器这就够了不需要额外再装 yarn 或 pnpm。除非你在后续步骤中遇到某些依赖只能通过 yarn 解析的情况再考虑安装 yarn 也不迟。2.2 配置 npm 镜像源解决依赖下载慢的问题构建 scratch-gui 需要下载大量 npm 依赖包如果网络条件不理想npm install可能要等很久甚至直接卡死。这里建议提前把 npm 源切换为国内镜像能明显加快下载速度。在终端里执行npm config set registry https://registry.npmmirror.com之后安装依赖时npm 就会从镜像源拉取。如果你已经在用某个镜像工具也可以直接通过工具管理不必非得改全局配置。这里要特别说一句离线部署不代表离线构建。构建过程必须在一台能正常访问 npm 源或镜像源的机器上完成。你完全可以在自己电脑上构建好再把产物拷贝到不联网的机房服务器上部署这条路是走得通的。2.3 Git 拉取源码从 GitHub 获取官方仓库scratch-gui 的源码托管在 GitHub仓库地址是https://github.com/scratchfoundation/scratch-gui。注意项目是从早期的LLK/scratch-gui迁移过来的如果你看到旧链接也别奇怪官方现在统一在 scratchfoundation 组织下维护。在终端中找一个干净的目录执行git clone https://github.com/scratchfoundation/scratch-gui.git cd scratch-gui如果你所在环境访问 GitHub 不稳定可以从能访问的镜像站或通过其他合规方式获取源码只要确保拉下来的是官方原版代码就行。拿到源码之后先别急着跑命令我建议你先看一下项目里的 README对目录结构有个大概了解后面排查问题会顺手很多。3. 从源码到可访问的网页构建与部署实操3.1 安装依赖耐心等待遇到报错也别慌在scratch-gui目录下执行npm install这一步会下载项目所需的全部依赖可能需要几分钟时间取决于你的网络状况。如果中途报错最常见的有两类一类是和 node-sass、node-gyp 相关的编译错误。这通常是因为某些依赖需要本地编译而你的系统缺少编译工具链。Windows 上可以通过安装 Visual Studio Build Tools 解决Linux 上则需要build-essential和python3。不过新版本的 scratch-gui 已经在逐渐移除 node-sass 的硬依赖遇到这类问题的概率比以前小了。另一类是依赖版本冲突npm 会提示你ERESOLVE unable to resolve dependency tree。这种情况下可以先试试把 npm 源切回官方源再安装或者用npm install --legacy-peer-deps绕过依赖树冲突检查。依赖安装完成后可以先用开发模式预览一下跑下面的命令npm start启动成功后终端会提示一个地址默认是http://localhost:8601用浏览器打开你应该能看到完整的 Scratch 编辑器界面。这步验证很关键它说明你的源码和依赖都没问题可以继续往下走。3.2 生产构建生成可直接部署的静态文件开发模式没问题后就可以进行生产构建了npm run build构建过程会持续几十秒到几分钟结束后项目目录下会多出一个build文件夹。这个文件夹就是你要的产物里面主要的几个东西是index.html入口页面static/js/打包压缩后的 JavaScript 文件static/css/样式文件static/media/静态资源包括图标、字体、音效等。你可以先在本地验证一下构建产物是否正常。用一个简单的静态服务器工具npx serve build -l 8080浏览器访问http://localhost:8080能正常打开编辑器就说明构建成功。这里要特别强调一个问题不要直接双击build/index.html用file://协议打开。scratch-gui 涉及大量异步资源加载和跨域请求直接双击打开大概率白屏控制台里还会报各种 CORS 错误。这不是部署环境的问题而是访问方式不对。所有静态页面部署都必须通过 HTTP 协议访问这点要记牢。3.3 用 Nginx 把服务跑起来局域网访问的核心配置正式部署时我推荐用 Nginx 做静态文件服务器。它轻量、稳定、配置简单在 Windows 和 Linux 上都有很好的支持。假设你已经安装好了 Nginx并且把build目录拷贝到了服务器的某个路径比如 Linux 下是/srv/scratch/buildWindows 下是D:\scratch\build。那么可以在 Nginx 配置里加一个 server 块server { listen 8080; server_name _; root /srv/scratch/build; index index.html; location / { try_files $uri $uri/ /index.html; } location /static/ { expires 30d; add_header Cache-Control public; } }说明一下try_files的作用是当请求的文件不存在时自动回退到入口页面避免某些刷新场景下出现 404。location /static/这里给静态资源加了一个 30 天的浏览器缓存目的是让图片、JS、CSS 这些体积较大的文件在客户端缓存住后面再访问时加载速度会快很多。配置完成后重载 Nginxnginx -s reload然后在同一台机器上访问http://localhost:8080测试没问题的话换成局域网内其他电脑访问http://服务器IP:8080。如果打不开先检查服务器防火墙是否放行了 8080 端口。这里再多说一句如果你只有一台可以接入局域网的老电脑不想折腾 Nginx也可以用 Python 临时顶一下。在build目录下执行python3 -m http.server 8080效果一样只是性能和功能性不如 Nginx适合临时测试用。3.4 部署到子路径的坑为什么静态资源全都 404很多校园网络环境里你可能不能独占一个端口往往要把服务挂到已有域名的子路径下面比如http://example.com/scratch/。这种情况下你会发现页面能打开但 JS、CSS 全都加载不出来控制台里一片 404。根因是 scratch-gui 构建时的静态资源路径写的是绝对路径。也就是说它生成的 HTML 里引用的是/static/js/main.js而你的服务在子路径下时实际文件路径是/scratch/static/js/main.js自然找不到。解决的方法有几种但都不算优雅。要么在构建配置里改 publicPath但这需要深入 webpack 配置重新构建时还得保持参数一致比较麻烦要么用 Nginx 的alias或反向代理把子路径转发到独立服务上。我的建议是如果条件允许尽量给 scratch-gui 单独分配一个端口或者子域名从根路径访问这样最省事也不会遇到后续一系列资源路径问题。4. 资源缺失问题为什么素材库空白角色加载不出来4.1 先分清“内嵌资源”和“在线资源”很多人在部署完离线版之后打开一个本地项目文件发现角色图片、背景、声音都很正常但一打开角色库或者背景库就全是空白或者一直转圈。这是为什么因为 .sb3 项目文件本身是一个 zip 压缩包里面已经包含了项目用到的所有素材。所以你打开一个完好的 .sb3 文件时角色和声音都能正常显示播放这些是“内嵌资源”不依赖网络。而素材库——也就是你点击左下角“选择角色”“选择背景”时弹出的那些预设素材——是程序运行时从远程服务器拉取的。scratch-gui 源码里默认配置了两个服务器地址const ASSET_SERVER https://assets.scratch.mit.edu; const MEDIA_LIBRARY_SERVER https://cdn.assets.scratch.mit.edu;前者用来获取项目运行时的动态资源后者用来获取媒体库中的缩略图和素材文件。在没有外网的环境里这两个地址自然是访问不了的于是素材库就变成了空白。4.2 素材库离线不可用的三种应对方案方案一局域网仍然可以访问外网。这种情况最简单保持默认配置就行。学生打开素材库时浏览器会直接请求 Scratch 官方的 CDN虽然速度可能一般但能用。方案二完全离线且不需要素材库。你可以选择在部署时隐藏素材库入口或者直接告诉学生“素材库不可用请导入本地文件或自己绘制”。如果只是上编程课这个限制一般影响不大。方案三完全离线且需要素材库。你需要修改src/lib/storage.js里的服务器地址把ASSET_SERVER和MEDIA_LIBRARY_SERVER指向你自己搭建的静态服务器然后把 Scratch 官方 CDN 上的媒体库素材提前同步到本地。这里要提醒一句官方媒体库素材总量是相当可观的全量同步既费时间又费带宽除非你有明确需求否则我不建议一上来就做全量离线。你可以先同步一部分常用素材或者直接把素材库换成自己整理的本地资源。无论选择哪种方案改完源码后都要重新执行npm run build重新部署build目录才能生效。4.3 项目内的“动态扩展”为什么离线必挂还有一种情况你自己写好的项目文件在在线版里用得好好的放到离线版里一打开要么角色消失要么提示某个扩展不可用。这通常是项目里用了“文字朗读”“翻译”这类依赖外部服务的扩展。比如文字朗读扩展它需要调用系统中集成的语音引擎或在线语音合成接口离线环境下无法工作。翻译扩展就更不用说了它走的是外部翻译服务断网后整个积木都会报错。碰到这种情况我只能说这是离线环境的天然限制不是部署配置的问题。解决办法有两个方向一是做课程设计时避开这些联网扩展二是提前告知学生这些功能在离线版里不可用避免上课时产生混乱。4.4 中文字体与界面乱码最后提一个容易被忽略的资源问题字体。如果你部署的服务器上运行的是 Linux而学生端的浏览器恰好没有安装中文字体界面上的中文就可能显示成方块或者乱码。这个问题在 Windows 机房中一般不会出现因为系统自带中文字体但在使用 Chromebook、瘦客户机或者国产 Linux 系统的环境下就要注意了。解决方案也不复杂给客户端机器装上中文字体或者确保浏览器使用的是标准 Web Font 回退链。另外scratch-gui 支持指定语言可以通过界面右上角的设置把语言切到“简体中文”前提是系统中有可用的中文字体。5. 页面显示异常白屏、样式错乱与兼容性问题排查5.1 白屏问题三层排查法一步到位定位离线部署最常见也最让人头疼的问题就是白屏。页面能打开但就是一个纯白的背景什么都没有。我一般推荐用三层排查法第一层确认资源能不能访问。打开浏览器的开发者工具F12切到 Network 面板刷新页面看有没有请求在加载。如果请求列表里什么都没有说明静态资源服务器根本没跑起来或者你访问的地址不对。第二层确认 JS 和 CSS 有没有正常返回。看 Network 里有没有红色的失败请求。如果 JS 返回 404基本可以确认是资源路径问题比如前面说的子路径部署或者你把build目录里的文件单独挪了一份导致路径失效。第三层看 Console 面板有没有报错。如果 JS 正常加载了但页面还是白屏Console 里通常会有 JavaScript 运行时的错误信息。最常见的是浏览器版本太老不兼容 scratch-gui 用到的某些现代语法导致脚本解析失败。这种时候就要考虑升级浏览器或者更换内核。按照这个顺序排查绝大多数白屏都能在几分钟内定位。我自己最常遇到的其实是第一层问题——服务没启动或者端口被占用因为 Nginx 配置文件写错而导致的启动失败太常见了。5.2 样式错乱多因缓存而起有些时候页面不是白屏而是能显示界面但布局一团糟按钮错位图标不显示。这种问题大概率是缓存导致的。如果你更新了 scratch-gui 源码并重新构建部署但客户端浏览器还在用旧的 JS 和 CSS 缓存新旧资源混用就会表现成样式错乱。解决方法分两步第一服务器端给静态资源设置合理的缓存策略文件名带哈希值的资源可以缓存久一点入口 HTML 不缓存或短缓存可以使用try_files配合index.html第二客户端在遇到问题时先强制刷新快捷键 CtrlShiftR 可以绕过缓存重新加载。5.3 浏览器兼容性教育机房的浏览器噩梦scratch-gui 对浏览器内核的要求并不低。它重度依赖 WebGL 和较新的 JavaScript 特性。在实际机房环境中我见过太多因为浏览器问题导致的显示异常Windows 自带的旧版 EdgeEdgeHTML 内核跑不了IE 想都不用想很多国产浏览器的“兼容模式”也会白屏老旧 Chrome版本低于 80可能部分功能失效。解决方案很粗暴也很直接机房统一安装新版本 Chrome 或新版 Edge然后设置浏览器默认使用 Chromium 内核打开页面。如果某些浏览器默认是兼容模式需要在设置里手动切到“极速模式”。这个工作建议在部署时一次性完成不要指望上课时再去调整。6. 高频问题速查表离线部署后的十种异常为了让你在实际维护时能快速定位问题我把这段时间遇到的典型异常整理成了下面这张速查表现象可能原因处理建议页面白屏Network 无请求静态服务未启动 / 端口被占用 / 访问地址错误检查服务进程和监听端口重新访问正确地址页面白屏Network 中有 404资源路径不对子路径部署未处理用独立端口/域名部署或修正 publicPath页面白屏Console 报语法错误浏览器内核版本太旧升级浏览器或切换到 Chromium 内核素材库空白 / 转圈素材库 CDN 无法访问保持外网访问或替换为本地素材库项目打开后角色消失项目使用了联网扩展或内嵌资源异常检查 .sb3 文件内容移除联网扩展声音无法播放浏览器自动播放策略 / 音频格式问题检查浏览器设置确认音频文件完整界面中文变方块/乱码客户端缺少中文字体安装中文字体或调整浏览器字体设置刷新后样式错乱浏览器缓存了旧的 JS/CSS强制刷新或配置静态资源缓存策略局域网其他电脑打不开防火墙拦截 / Nginx 监听配置错误放行对应端口检查 server 配置页面能开但非常卡顿服务器带宽不足 / 客户端配置过低启用 gzip 压缩优化客户端运行环境这张表基本覆盖了我遇到的绝大多数问题。如果你在实践中碰到了表里没有的情况建议先回到“三层排查法”把 Network 和 Console 两个面板的信息看明白基本上方向就有了。7. 最后分享一点实操经验折腾完这一整套流程我最大的感受是离线部署本身不难难的是理解各种异常背后的原理。资源缺失的问题根源是 scratch-gui 的设计里硬编码了在线服务器地址页面显示异常的问题根源多半是访问方式、缓存策略和浏览器兼容性的组合坑。只要把这几条主线想清楚很多问题不用查资料都能推导出答案。还有一个小技巧部署完成后建议你在服务器上留一份和线上完全一致的build目录拷贝并且记录下构建时的 Node 版本和关键配置。这样以后不管哪台机器出了问题你都可以对照这份基准环境快速复现和排查不会在版本差异上浪费大量时间。毕竟这类系统维护工作稳定和可控永远比花哨更重要。