当前位置：首页 > news >正文

保姆级教程：手把手教你为Scratch 3.0添加第一个自定义插件（从下载到测试）

news 2026/8/13 12:52:49

从零开始：Scratch 3.0自定义插件开发实战指南

Scratch作为全球最受欢迎的少儿编程工具，其开放架构允许开发者通过插件扩展功能边界。本教程将带您完成第一个Hello World插件的完整开发流程，即使您从未接触过Scratch二次开发，也能在30分钟内看到自己的插件运行在Scratch编辑器中。我们将重点关注环境搭建、文件配置和调试技巧三个核心环节，过程中会特别标注新手容易踩坑的细节。

1. 开发环境准备

在开始插件开发前，需要确保本地具备完整的Scratch开发环境。推荐使用Node.js 16.x LTS版本，这是经过Scratch官方测试最稳定的运行环境。

# 验证Node.js版本 node -v # 应显示v16.x.x # 安装yarn包管理器 npm install -g yarn

接下来克隆Scratch官方仓库。建议在GitHub桌面客户端中操作，避免命令行操作可能带来的路径问题：

访问 scratch-gui 仓库
点击"Code"按钮选择"Open with GitHub Desktop"
将仓库克隆到本地无中文路径的目录（如D:\ScratchDev）

安装依赖时需要注意网络环境，建议配置npm镜像源：

# 设置淘宝镜像源 npm config set registry https://registry.npmmirror.com # 进入项目目录安装依赖 cd scratch-gui yarn install

提示：如果安装过程中出现node-gyp相关错误，需要先安装Windows构建工具：
npm install --global windows-build-tools

2. 插件文件结构解析

Scratch插件采用前后端分离架构，需要同时在scratch-vm（逻辑核心）和scratch-gui（用户界面）两个部分进行配置。典型的Hello World插件包含以下文件：

scratch3_hello_world/ ├── index.js # 插件核心逻辑 └── locale/ └── en.json # 国际化文本 helloworld/ ├── helloworld.png # 插件图标(80x80像素) └── helloworld-small.svg # 缩略图标(24x24像素)

新建插件目录时，务必遵循Scratch的命名规范：

逻辑目录：scratch3_[插件名]（全小写，单词间用下划线连接）
资源目录：[插件名]（驼峰命名或全小写）

3. 核心逻辑实现

在scratch-vm/src/extensions目录下创建scratch3_hello_world文件夹，新建index.js文件：

class Scratch3HelloWorld { constructor(runtime) { this.runtime = runtime; } getInfo() { return { id: 'helloWorld', name: 'Hello World', blocks: [ { opcode: 'sayHello', blockType: Scratch.BlockType.COMMAND, text: 'say hello', arguments: {} } ] }; } sayHello() { console.log('Hello from Scratch plugin!'); } } module.exports = Scratch3HelloWorld;

接着需要注册插件到扩展管理器。打开scratch-vm/src/extension-support/extension-manager.js，在合适位置添加：

// 顶部引入模块 const Scratch3HelloWorld = require('../extensions/scratch3_hello_world'); // 在builtinExtensions对象中添加 helloWorld: () => require('../extensions/scratch3_hello_world')

重要提醒：对象属性间必须用逗号分隔，最后一个属性后不能有逗号，这是JavaScript语法要求。

4. 用户界面集成

插件需要在GUI中显示图标和描述信息。在scratch-gui/src/lib/libraries/extensions目录下：

创建helloworld文件夹
准备两张图片：
- helloworld.png(80×80像素)
- helloworld-small.svg(24×24像素)

修改同目录下的index.jsx文件，在extensionData数组中添加：

{ name: 'Hello World', extensionId: 'helloWorld', iconURL: helloworldIcon, insetIconURL: helloworldInsetIcon, description: 'My first Scratch extension', featured: true, disabled: false }

5. 本地运行与调试

完成上述步骤后，在项目根目录运行：

yarn start

访问http://localhost:8601即可看到开发服务器。打开Scratch编辑器后，在扩展面板中应该能看到新添加的Hello World图标。点击图标后，左侧积木区会出现"say hello"积木块。

调试技巧：

按F12打开开发者工具，查看Console输出
修改代码后需要重启开发服务器才能生效
如果插件不显示，检查浏览器控制台是否有404错误（通常表示图片路径不正确）

6. 进阶配置与优化

为了让插件更专业，建议添加以下增强功能：

多语言支持：在插件目录下创建locale文件夹，添加en.json：

{ "helloWorld/description": "My first extension", "helloWorld/sayHello": "say hello" }

积木颜色定制：在getInfo()方法中指定颜色值：

color1: '#FF6680', color2: '#E64D66', color3: '#CC3355'

参数化积木：创建带参数的积木块：

{ opcode: 'greet', blockType: Scratch.BlockType.COMMAND, text: 'say hello to [NAME]', arguments: { NAME: { type: Scratch.ArgumentType.STRING, defaultValue: 'world' } } }

7. 常见问题排查

下表列出了新手开发者常遇到的问题及解决方案：

问题现象	可能原因	解决方法
插件不显示	扩展ID不匹配	检查extensionId是否一致
积木块无响应	方法名拼写错误	确认opcode与方法名相同
图片不显示	图片尺寸不符	确保图片为PNG/SVG格式
控制台报错	缺少逗号	检查JS对象语法规范