phaser-build

Phaser 4 构建与部署

开发服务器

启动支持热重载的开发服务器：

npm run dev

在 http://localhost:5173 打开（Vite 默认地址）。更改会在浏览器中自动重新加载。

生产构建

npm run build     # Compiles TypeScript + bundles with Vite → dist/
npm run preview   # Serve the dist/ folder locally to test production build

输出位于 dist/ 中，是可供任何 Web 主机托管的静态文件。

诊断项目

构建前运行验证脚本：

bash scripts/validate-project.sh

脚本会自动检查常见问题。

TypeScript 类型检查

npx tsc --noEmit

发布前修复所有类型错误。常见的 Phaser 4 TypeScript 问题：

缺少 Phaser 类型：

// tsconfig.json — Phaser 4 resolves its own types via its exports map
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "skipLibCheck": true
  }
}

然后在每个文件中显式导入：import Phaser from 'phaser';

如果看到 TS2688: Cannot find type definition file for 'Phaser'，说明项目仍沿用了 v3 时代的 typeRoots + types: ["Phaser"] 配置组合。删除这两个键——Phaser 4 提供的是单个 types/phaser.d.ts，它不是有效的类型根目录包。

this.input.keyboard 可能为空：

// Wrong:
const cursors = this.input.keyboard.createCursorKeys();
// Correct:
const cursors = this.input.keyboard!.createCursorKeys();

sprite.body 可能为空：

// Wrong:
sprite.body.velocity.x
// Correct:
(sprite.body as Phaser.Physics.Arcade.Body).velocity.x
// Or:
sprite.body?.velocity.x

this.scene.get() 返回基础 Scene 类型：

// Cast to specific scene class:
const game = this.scene.get('GameScene') as GameScene;

常见构建错误

“Cannot find module 'phaser'”

npm install phaser   # installs Phaser 4 (latest stable). Do NOT use phaser — that tag still points at 4.2.1

资源出现 404 错误（游戏已加载，但资源缺失）

在 Vite 中，资源必须放在 public/ 目录下。它们会原样从根路径提供。

✅ public/assets/images/sky.png  → loads as 'assets/images/sky.png'
❌ src/assets/images/sky.png     → won't work with this.load.image()

不要通过 ES 导入为 Phaser 导入资源。只需引用路径字符串：

this.load.image('sky', 'assets/images/sky.png');  // ✅

“Phaser.Geom.Point is not a constructor”

这是 v3 → v4 的重大变更。替换为 Vector2：

// Old (v3):
const pt = new Phaser.Geom.Point(x, y);
// New (v4):
const pt = new Phaser.Math.Vector2(x, y);

“Math.PI2 is undefined”

这是 v3 → v4 的重大变更：

// Old (v3):
const angle = Math.PI2;        // was π (wrong!) in v3
// New (v4):
const angle = Math.TAU;        // π×2
const half = Math.PI_OVER_2;   // π/2

启动时黑屏

1. 检查浏览器控制台中的错误（F12）
2. 检查 Network 标签页中是否有 404（资源缺失）
3. 确认场景已添加到 GameConfig 的 scene: [] 数组中
4. 如果使用 parent: 'game-container'，确认 HTML 中有 <div id="game-container">
5. 尝试移除 parent 配置，直接将内容添加到 document.body

WebGL 上下文丢失

// Try Canvas renderer as fallback
const config = {
  type: Phaser.CANVAS,   // instead of Phaser.AUTO or Phaser.WEBGL
  // ...
};

或者添加 WebGL 上下文丢失恢复监听器：

this.game.renderer.on('contextlost', () => {
  console.warn('WebGL context lost — attempting recovery');
});

Vite 配置

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  base: './',             // IMPORTANT for itch.io and subdirectory deployment
  build: {
    outDir: 'dist',
    assetsDir: 'assets',
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          phaser: ['phaser'],  // Bundle Phaser separately for caching
        },
      },
    },
  },
  server: {
    port: 5173,
  },
});

对于 itch.io、GitHub Pages 和任何子目录部署，base: './' 至关重要。如果不设置，资源会从 /（根目录）加载，在子目录主机上会出错。

部署目标

本节介绍如何将构建产物部署到主机。关于如何判断游戏是否已准备就绪——就绪门槛、版本控制、商店上线和发布日等，请参阅 skills/phaser-release/。

itch.io

1. npm run build
2. 将 dist/ 文件夹中的内容压缩为 zip（不要压缩文件夹本身——只压缩其中的内容）
3. 将 zip 上传到 itch.io → “Upload files” → HTML game
4. 设置“This file will be played in the browser”
5. 如果需要，勾选“SharedArrayBuffer support”

GitHub Pages

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with: { node-version: '18' }
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

在 vite.config.ts 中设置 base: '/repo-name/'，以用于 GitHub Pages（子目录）。

Netlify / Vercel

连接 git 仓库。设置：

• 构建命令：npm run build
• 输出目录：dist

两者都会在推送到 main 后自动部署。

Capacitor（iOS/Android）

npm install @capacitor/core @capacitor/cli @capacitor/ios @capacitor/android
npx cap init
npx cap add ios
npx cap add android
npm run build
npx cap sync
npx cap open ios    # Opens Xcode
npx cap open android  # Opens Android Studio

发布前性能检查清单

• GameConfig 中的 arcade: { debug: false }
• 资源放在纹理图集中（而非单独的图像文件）
• 音频已压缩（BGM 使用 128kbps MP3，SFX 使用 96kbps）
• 为子弹/粒子/敌人使用对象池
• 为所有粒子发射器设置 maxParticles
• npx tsc --noEmit 运行通过，错误数为 0
• 已在 Chrome、Firefox 和 Safari 中测试
• 已进行移动端测试（若面向移动端）

如需详细的性能指南（以测量为先的提示、消除逐帧分配、空间网格、音频延迟加载、图集打包、修复 tween 泄漏），请参阅 skills/phaser-analyze/references/performance-playbook.md。如果担心 FPS，发布前请使用 /phaser-analyze 对整个项目进行审计。

脚本

运行项目验证器：

bash scripts/validate-project.sh

验证器会检查：Phaser 版本、tsconfig 字段、场景文件是否存在，以及是否使用已弃用的 v3 API。