Windows 本地安装 Scratch-GUI 和 ML2Scratch 指南

本指南适用于 Windows 系统，帮助非技术人员在本地环境中安装 Scratch-GUI 及 ML2Scratch 扩展模块。请按照以下步骤依次操作，不要跳过任何步骤。

前期准备

在开始安装之前，请确认您的电脑上已经准备好以下文件和文件夹结构：

C:\Users\Digitallab\ai\
├── scratch-gui\          ← 从 GitHub 克隆下来的 scratch-gui 项目
├── scratch-gui-file\     ← 预先准备好的配置文件包
│   ├── prepublish.mjs
│   ├── index.jsx
│   ├── extension-manager.js
│   └── microbit\
│       └── scratch-microbit-1.2.0.hex
└── ml2scratch\           ← ml2scratch 扩展模块包
    ├── scratch-vm\
    │   └── src\extensions\scratch3_ml2scratch\
    │       └── index.js
    └── scratch-gui\
        └── src\lib\libraries\extensions\ml2scratch\
            ├── ml2scratch.png
            └── ml2scratch-small.png

⚡ 重要提示：PowerShell 执行权限设置

在 Windows 系统中，PowerShell 默认禁止执行脚本，运行 npm 等工具时可能会遇到“无法加载文件，因为在此系统上禁止运行脚本”的错误提示。
在正式安装之前，必须先以管理员身份开启脚本执行权限。

方法一：临时提升权限（推荐，仅当次会话有效）

  1. 在 Windows 搜索栏中输入 PowerShell
  2. 右键点击 Windows PowerShell，选择 “以管理员身份运行”
  3. 在弹出的 PowerShell 窗口中输入以下命令：
# 仅对当前 PowerShell 会话临时开放脚本执行权限
# 关闭窗口后自动恢复原有限制，较为安全
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

✅ 输入后按 Enter，若没有报错即设置成功。之后在同一个窗口中继续执行后续安装步骤。

方法二：永久修改执行权限（适合长期使用）

如果您希望以后每次打开 PowerShell 都不需要重复设置，可以使用此方法永久修改。

  1. 同样以 管理员身份 打开 PowerShell
  2. 输入以下命令：
# 永久允许运行本地脚本（对所有用户生效）
Set-ExecutionPolicy -Scope LocalMachine -ExecutionPolicy RemoteSigned
  1. 系统会提示您确认，输入 Y 后按 Enter 确认
参数说明 含义
RemoteSigned 允许运行本地脚本；从网络下载的脚本需要有数字签名才能运行
Bypass 完全绕过限制，不建议长期使用
Restricted 默认值，禁止所有脚本运行

⚠️ 注意：若公司电脑有 IT 管理策略，可能无法修改此设置，请联系 IT 人员协助处理。

验证权限是否设置成功

# 查看当前执行策略
Get-ExecutionPolicy

# 若返回 RemoteSigned 或 Bypass，说明设置成功

STEP 0：安装必要的软件环境

在运行项目之前，需要先安装 Node.js 和 Git。这两个工具是运行 Scratch-GUI 的基础环境。

安装 Node.js

  1. 打开浏览器，访问 https://nodejs.org
  2. 下载 LTS（长期支持版本） 并按照提示完成安装
  3. 安装完成后，以管理员身份打开 PowerShell，输入以下命令验证安装是否成功：
node -v   # 应显示 Node.js 版本号，例如 v18.x.x
npm -v    # 应显示 npm 版本号，例如 9.x.x

安装 Git

  1. 访问 https://git-scm.com 下载并安装 Git
  2. 安装完成后，在 PowerShell 中输入以下命令验证：
git --version   # 应显示 git 版本号

STEP 1：克隆 Scratch-GUI 项目

此步骤将从 GitHub 上下载 Scratch-GUI 的源代码到您的本地电脑。

以管理员身份打开 PowerShell，依次输入以下命令：

# 进入工作目录
cd C:\Users\Digitallab\ai

# 从 GitHub 克隆 scratch-gui 项目
git clone https://github.com/scratchfoundation/scratch-gui.git

# 进入 scratch-gui 目录
cd scratch-gui

⚠️ 注意：克隆过程需要网络连接，请确保网络正常。如果下载速度较慢，请耐心等待。

STEP 2：复制配置文件并安装依赖

由于网络原因，部分文件需要从本地预先准备好的 scratch-gui-file 文件夹中复制，以替代从网络下载的版本。

请确保您当前仍在 C:\Users\Digitallab\ai\scratch-gui 目录下，依次执行以下命令：

# 创建存放 microbit 文件所需的文件夹
mkdir .\static
mkdir .\static\microbit

# 复制预置的构建脚本文件
copy ..\scratch-gui-file\prepublish.mjs scripts\prepublish.mjs

# 复制 microbit 的固件文件
copy ..\scratch-gui-file\microbit\scratch-microbit-1.2.0.hex .\static\microbit\

# 安装项目所需的所有依赖包（此过程可能需要几分钟，请耐心等待）
npm install

⚠️ 注意： - npm install 执行时间较长，请不要关闭 PowerShell 窗口，等待出现命令提示符 > 后再进行下一步。 - 若出现权限错误，请确认 PowerShell 是以管理员身份运行的。

STEP 3：安装 ML5 机器学习依赖库

ML2Scratch 扩展依赖 ML5 这个机器学习库，需要单独安装。

# 进入 scratch-vm 子目录
cd node_modules\scratch-vm

# 安装指定版本的 ml5 机器学习库
npm install ml5@0.12.2

# 安装完成后，返回 scratch-gui 根目录
cd ..\..

💡 提示：这里必须安装 ml5@0.12.2 这个特定版本，不要随意更改版本号，否则可能导致功能异常。

STEP 4：安装 ML2Scratch 扩展模块

此步骤将把 ML2Scratch 的核心功能文件复制到对应位置，让 Scratch 能够识别并加载这个扩展。

# 创建 ml2scratch 扩展的目录
mkdir node_modules\scratch-vm\src\extensions\scratch3_ml2scratch

# 复制 ml2scratch 的核心逻辑文件
copy .\ml2scratch\scratch-vm\src\extensions\scratch3_ml2scratch\index.js .\node_modules\scratch-vm\src\extensions\scratch3_ml2scratch\

# 备份原始的扩展管理器文件（以防需要还原）
copy node_modules\scratch-vm\src\extension-support\extension-manager.js node_modules\scratch-vm\src\extension-support\extension-manager.js_orig

# 创建 ml2scratch 图标资源目录
mkdir .\src\lib\libraries\extensions\ml2scratch

# 复制 ml2scratch 的图标文件
copy .\ml2scratch\scratch-gui\src\lib\libraries\extensions\ml2scratch\ml2scratch.png .\src\lib\libraries\extensions\ml2scratch\
copy .\ml2scratch\scratch-gui\src\lib\libraries\extensions\ml2scratch\ml2scratch-small.png .\src\lib\libraries\extensions\ml2scratch\

# 备份原始的扩展列表文件
copy src\lib\libraries\extensions\index.jsx src\lib\libraries\extensions\index.jsx_orig

# 用预置的扩展列表文件替换原始文件（此文件中已包含 ml2scratch 的注册信息）
copy ..\scratch-gui-file\index.jsx src\lib\libraries\extensions\index.jsx

# 用预置的扩展管理器替换原始文件（此文件中已包含 ml2scratch 的加载逻辑）
copy ..\scratch-gui-file\extension-manager.js node_modules\scratch-vm\src\extension-support\extension-manager.js

STEP 5：启动 Scratch-GUI

所有文件配置完成后，可以启动 Scratch-GUI 本地服务器，并在浏览器中访问。

# 确保当前在 scratch-gui 目录下
cd C:\Users\Digitallab\ai\scratch-gui

# 启动开发服务器
npm start

💡 提示： - 启动过程需要约 1~3 分钟，请耐心等待，不要关闭 PowerShell 窗口。 - 当命令提示符中出现类似 Compiled successfully 的提示后，打开浏览器。 - 在浏览器地址栏输入：http://localhost:8601 即可访问 Scratch-GUI。 - 若需要在后台持续运行（关闭窗口后服务不中断），请参考下方说明。

后台持续运行（可选）

如果希望关闭 PowerShell 窗口后服务仍然继续运行，可以使用以下方式：

# 使用 Start-Process 在后台独立运行 npm start
Start-Process -FilePath "npm" -ArgumentList "start" -WorkingDirectory "C:\Users\Digitallab\ai\scratch-gui" -WindowStyle Hidden

⚠️ 注意：后台运行后，若需要停止服务，请打开任务管理器，找到 node.exe 进程并结束任务。

常见问题

问题 可能原因 解决方法
npm 提示”无法加载文件，禁止运行脚本” PowerShell 执行权限不足 参考本文 “重要提示：PowerShell 执行权限设置” 章节
npm install 报错 Node.js 未正确安装 重新安装 Node.js 并验证版本
git clone 失败 网络连接问题 检查网络，或使用代理
浏览器无法访问 localhost:8601 服务器未成功启动 查看 PowerShell 中是否有报错信息
复制文件时提示”找不到路径” 文件夹结构不正确 检查 scratch-gui-file 和 ml2scratch 是否放置在正确位置
修改执行权限时提示”访问被拒绝” 没有以管理员身份运行 右键 PowerShell 选择”以管理员身份运行”后重试

✅ 安装完成！ 如果您能在浏览器中看到 Scratch 编辑器界面，并且在扩展列表中找到 ML2Scratch，说明安装已成功完成。