使用TypeScript构建包¶

JavaScript足够写出脚本，但当项目变大时，TypeScript会更舒服：编辑器能提示类型，编译器能提前发现一部分错误，调试器也能通过源映射把运行中的JavaScript对应回main.ts。这一课会把上一课的脚本项目升级成“编写TypeScript、编译JavaScript、部署到游戏”的工作流。

安装工具¶

你需要准备以下工具：

Node.js：安装官方长期支持版本，NPM会随Node.js一起安装。
Visual Studio Code：用于编辑TypeScript和调试脚本。
Minecraft Bedrock Edition Debugger：可选，但推荐安装；它可以让Visual Studio Code附加到正在运行的Minecraft脚本。

官方TypeScript教程使用minecraft-scripting-samples仓库中的ts-starter作为起点。这个启动项目已经包含常见的构建和部署脚本，适合第一次学习时直接使用。

取得启动项目¶

打开https://github.com/microsoft/minecraft-scripting-samples/。
下载仓库压缩包，解压后找到ts-starter文件夹。
把ts-starter复制到你的项目目录，例如C:\projects\cotta。
在PowerShell中进入项目目录：

cd C:\projects\cotta

安装项目依赖：

npm i

然后用Visual Studio Code打开当前目录：

code .

配置部署目标¶

打开项目根目录的.env。常见配置如下：

.env

PROJECT_NAME="starter"
MINECRAFT_PRODUCT="BedrockGDK"
CUSTOM_DEPLOYMENT_PATH=""

PROJECT_NAME决定部署到游戏开发目录时使用的文件夹名。
MINECRAFT_PRODUCT可以选择正式版或预览版安装位置；官方示例使用BedrockGDK和PreviewGDK。
CUSTOM_DEPLOYMENT_PATH用于非标准安装位置。

然后打开行为包中的manifest.json，修改名称、描述和UUID。不要直接复用模板UUID，否则多个包同时存在时会互相冲突。

本地部署¶

第一次运行部署脚本前，如果PowerShell阻止脚本执行，可以只对当前进程放宽策略：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

执行本地部署：

npx just-scripts local-deploy

这个命令会编译TypeScript，并把生成结果复制到.env指定的Minecraft开发目录。启动游戏、创建测试世界并启用行为包后，如果模板脚本输出类似Hello starter!的消息，就说明工具链已经工作。

开发时可以使用监听模式：

npx just-scripts local-deploy --watch

监听模式会在文件变化后自动重新编译和部署。你仍然需要在游戏内执行/reload，或在不支持热重载的改动后重新进入世界。

编写TypeScript脚本¶

打开scripts/main.ts，可以先写一个和上一课等价的版本：

scripts/main.ts

import { world, system } from "@minecraft/server";

system.runInterval(() => {
  world.sendMessage(`TypeScript脚本正在运行。当前刻：${system.currentTick}`);
}, 200);

保存后，监听模式会把它编译成Minecraft可以执行的JavaScript。TypeScript项目通常还会生成源映射文件，以便调试器把运行位置对应回原始.ts文件。

调试与检查¶

如果脚本没有按预期运行，按这个顺序排查：

看终端中的TypeScript编译错误。
看Minecraft内容日志中的包加载和脚本运行错误。
确认package.json中安装了项目实际使用的@minecraft/*模块。
确认manifest.json中的脚本模块依赖和package.json里的NPM依赖没有遗漏。

官方校验规则会检查行为包清单和package.json之间的脚本模块注册关系：清单里用了某个@minecraft/*模块，但package.json没有注册时，会被视为缺少包注册；包名不存在时，也会报错。

什么时候使用调试器

打印日志适合快速确认代码是否执行；当你需要看变量、单步执行、检查调用栈时，再使用Minecraft Bedrock Edition Debugger。调试脚本时，Visual Studio Code的launch.json通常会使用minecraft-js调试类型和19144端口。