phaser-init

Phaser 4 项目初始化

使用 TypeScript 和 Vite 搭建一个新的 Phaser 4（v4.2.1）项目。

快速搭建（推荐）

使用官方脚手架，快速完成设置：

npm create @phaserjs/game@latest

此交互式 CLI 支持 React、Vue、Angular、Svelte、Next.js、SolidJS 和纯 TypeScript。 对于初学者：出现提示时选择 TypeScript + Vite。

搭建完成后，它会自动安装 phaser。运行：

cd my-game
npm install
npm run dev

手动搭建

适用于需要自定义设置或希望了解各个组成部分的用户。

第 1 步 — 创建项目

mkdir my-game && cd my-game
npm init -y
npm install phaser
npm install -D typescript vite @types/node

第 2 步 — 目录结构

创建以下布局：

my-game/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── public/
│   └── assets/
│       ├── images/
│       ├── spritesheets/
│       ├── atlases/
│       ├── audio/
│       └── tilemaps/
└── src/
    ├── main.ts
    └── scenes/
        ├── BootScene.ts
        ├── PreloaderScene.ts
        └── GameScene.ts

第 3 步 — 配置文件

按照 examples/ 中的示例，准确生成以下文件：

• examples/game-config.ts — 包含 GameConfig 的完整 main.ts
• examples/boot-scene.ts — BootScene 起始模板
• examples/vite-config.ts — Phaser 4 的 Vite 配置

关键配置项：

package.json 脚本：

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  }
}

tsconfig.json 关键字段：

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "types": ["vite/client"]
  },
  "include": ["src"]
}

Phaser 4 通过其 package.json 中的 exports 映射提供自带类型，因此 moduleResolution: "bundler"（或 "node16"/"nodenext"）可通过普通的 import Phaser from 'phaser' 解析这些类型，无需额外配置。

types: ["vite/client"] 是单独的配置，且确实需要：它为 import.meta.env 提供类型， 而必需的 __PHASER_GAME__ 埋点代码会用到它。如果没有此配置，npx tsc --noEmit 会报错：TS2339: Property 'env' does not exist on type 'ImportMeta'。

不要同时添加 typeRoots: ["./node_modules/phaser/types"] 和 types: ["Phaser"]。 这是 Phaser 3 / 早期 v4 RC 的配置方式。在 Phaser 4.2.1 中会直接报错： TS2688: Cannot find type definition file for 'Phaser'，因为随包提供的类型是一个 types/phaser.d.ts 文件，而不是 Phaser/index.d.ts 类型根包。 如果沿用了这种配置，请删除这两个字段。

第 4 步 — 验证安装

npm run dev

预期结果：浏览器会打开 http://localhost:5173，并显示一个深色画布（或设置的其他背景颜色）。如果显示空白页面，请检查浏览器控制台中的错误。

搭建完成后的操作

1. 将 GameScene.ts 替换为实际的游戏逻辑（使用 phaser-coder agent）
2. 将资源添加到 public/assets/
3. 设计完整的场景流程（使用 phaser-architect agent）
4. 调试完成后，将 arcade: { debug: false } 设为关闭状态

常见搭建错误

• 资源无法加载： 在 Vite 中，资源必须放在 public/ 中。不要通过 import 导入。请使用 'assets/image.png' 引用（相对于服务器根目录）。
• Phaser.* 出现 TypeScript 错误： 显式导入 Phaser（import Phaser from 'phaser';），并使用 moduleResolution: "bundler"。如果 tsconfig 仍保留 v3 时代模板中的 typeRoots/types: ["Phaser"]，请将其删除——它们会导致 v4 构建失败。请参阅第 3 步。
• 找不到 phaser： 运行 npm install phaser。不要使用 beta 标签——phaser@beta 仍会解析为 4.0.0-rc.7，比当前稳定版本更旧。
• 黑屏： 检查浏览器控制台中是否有 404 错误或 JS 错误。

更多资源

示例文件

examples/ 中的可运行模板：

• examples/game-config.ts — 包含场景注册的完整 main.ts
• examples/boot-scene.ts — 仅加载少量资源的 BootScene
• examples/vite-config.ts — Phaser 4 的 Vite 配置

参考文件

• references/project-templates.md — TypeScript+Vite、JavaScript+Vite 和纯 HTML 配置的完整文件列表
• references/template-archetypes.md — 平台跳跃、俯视角 RPG、太空射击和三消益智游戏的完整原型规范

模板类型

当用户想要特定类型的游戏，而不是空白脚手架时，可根据游戏类型生成完整可运行的游戏。phaser-coder Agent 会根据类型规范生成所有文件。

可用类型（与 /phaser-new [template] 搭配使用，或触发 phaser-coder Agent）：

类型	命令	核心功能
platformer	/phaser-new platformer	重力、跳跃、平台、敌人、金币、生命系统
topdown	/phaser-new topdown	零重力、8 向移动、瓦片地图世界、NPC 对话
shooter	/phaser-new shooter	滚动背景、子弹池、敌人波次、强化道具
puzzle	/phaser-new puzzle	三消网格、交换瓦片、级联匹配、得分
towerdefense	/phaser-new towerdefense	基于网格放置塔楼、敌人波次、经济系统、投射物池
runner	/phaser-new runner	自动滚动、跳跃/滑行、程序化障碍物、视差、速度递增
cardgame	/phaser-new cardgame	记忆配对卡牌、翻牌动画、配对、步数计分
fighting	/phaser-new fighting	状态机格斗角色、本地双人游戏、受击框系统、回合制
racing	/phaser-new racing	俯视视角旋转转向、瓦片地图赛道、检查点、AI 对手

所有类型都会使用占位素材生成（通过 Graphics.generateTexture() 绘制纯色矩形/圆形），因此游戏无需真实美术素材即可立即运行。准备好后，可替换为真实素材。

类型规范： references/template-archetypes.md