游戏引擎 / 系统课时

用 Vite 初始化 Phaser 工程

用 Vite 初始化 Phaser 工程

从空目录创建可运行的 Phaser 4.2.1 首屏:使用 Vite 初始化 JavaScript 项目、固定引擎版本、接好 HTML 与入口模块,再在本地开发服务器中验收画布、文字和控制台输出。本例不需要下载图片素材。

学习目标

  • 用 Vite 的 vanilla 模板创建 JavaScript 工程并安装指定版本的 Phaser。
  • 理解 index.html、src/main.js、Phaser.Game 与 Scene 的启动关系。
  • 在浏览器中验证首屏,并定位常见的空白页问题。

创建工程并固定依赖

准备 Node.js 22.12 或更高的受支持版本(也可使用 20.19+)和 npm。可先用 node -v 查看本机版本;不满足要求时先升级 Node.js,避免 Vite 报 EBADENGINE。在一个尚不存在 phaser-first-screen 子目录的位置打开终端,执行:

bash
npm create vite@latest phaser-first-screen -- --template vanilla
cd phaser-first-screen
npm install
npm install --save-exact phaser@4.2.1
node -p "require('./package.json').dependencies.phaser"

预期输出(前面还会出现脚手架和 npm 安装日志,最后一行应为):

text
4.2.1

--template vanilla 创建原生 JavaScript 工程;--save-exact 将 package.json 中的 Phaser 版本记录为 4.2.1 而非带 ^ 的范围,并由 package-lock.json 记录安装结果。安装要求和命令可对照 Vite 官方指南;引擎版本见 Phaser 4.2.1 发布页。

设置页面容器与样式

将项目根目录的 index.html 改为下面的完整内容。#game 是 Phaser 画布的挂载点,type="module" 让 Vite 从 src/main.js 处理模块导入。

html
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Phaser 4 First Screen</title>
  </head>
  <body>
    <main id="game" aria-label="游戏画布"></main>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

将 src/style.css 改为下面的样式,页面居中显示画布且没有浏览器默认外边距。

css
html, body {
  margin: 0;
  min-height: 100%;
}
body {
  min-height: 100vh;
  display: grid;
  place-items: center;
  background: #0c1220;
}
#game canvas {
  display: block;
}

这两份文件不是单独执行的程序;启动 Vite 后,浏览器应在深色页面中央看到一个固定大小的 Canvas。

编写游戏入口与首屏

将 src/main.js 完整替换为下列代码。Phaser 4.2.1 仍使用 Phaser.Scene、Phaser.Game 和 this.add.text;此处不加载外部素材,因此只需 create(),无需 preload()。

js
import './style.css';
import Phaser from 'phaser';

class StartScene extends Phaser.Scene {
  constructor() {
    super('StartScene');
  }

  create() {
    // 用内置文字验证场景已创建,不依赖外部图片。
    this.add.text(400, 270, 'Phaser 4.2.1', {
      fontFamily: 'Arial, sans-serif',
      fontSize: '40px',
      color: '#ffffff',
    }).setOrigin(0.5);

    this.add.text(400, 335, 'Vite + Phaser are running', {
      fontFamily: 'Arial, sans-serif',
      fontSize: '20px',
      color: '#80e0cf',
    }).setOrigin(0.5);

    console.log(`Phaser ${Phaser.VERSION}: scene ready`);
  }
}

// parent 必须对应 index.html 中的 id="game"。
new Phaser.Game({
  type: Phaser.AUTO,
  parent: 'game',
  width: 800,
  height: 600,
  backgroundColor: '#14213d',
  scene: StartScene,
});

预期结果(启动服务器并打开页面后):#game 内生成 800 × 600 的深蓝画布,两行文字居中;浏览器开发者工具的 Console 显示:

text
Phaser 4.2.1: scene ready

启动时,浏览器加载 HTML,Vite 处理模块导入,new Phaser.Game() 创建游戏和画布,然后自动启动唯一的 StartScene 并执行 create()。Phaser.AUTO 会优先选择 WebGL;Phaser 4 的 Canvas 渲染器虽仍存在,但已不推荐用于新项目。

Vite 与 Phaser 首屏启动和画布挂载关系

启动服务并排查首屏

在项目根目录执行:

bash
npm run dev

预期输出(关键行,实际端口可能不同):

text
Local: http://localhost:<PORT>/

通常 <PORT> 为 5173。访问终端实际给出的地址,按 F12 → Console 核对日志,并在 Elements 中确认 main#game 内出现 canvas。修改 src/main.js 中的标题后保存,页面应由 Vite 热更新或自动刷新并显示新文字。

如果出现空白页,按顺序检查:① 终端有无 Vite 报错;② index.html 的脚本路径是否仍为 /src/main.js;③ 游戏配置的 parent: 'game' 是否与页面 id 完全一致;④ Console 是否有导入失败或 WebGL 初始化报错。若 5173 被占用,以终端实际打印的端口为准;若 WebGL 无法初始化,先检查浏览器硬件加速与显卡驱动,而不是盲目修改场景坐标。

最终验收标准是:打开本地地址后显示 800 × 600 画布、两行文本和 scene ready 日志;修改文本后页面同步更新。达到这些条件,工程入口与首屏渲染链路就已经贯通。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Vite 初始化 Phaser 工程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通