游戏引擎 / 系统课时
用 Vite 生成生产环境资源
用 Vite 生成生产环境资源
本课把 Phaser 4 项目从开发状态变成可部署的静态文件:执行 Vite 生产构建,检查子路径部署对脚本与图片地址的影响,再用预览服务器验收 dist。完成后应能识别并修复上线常见的空白画布与资源 404。
学习目标
- 运行生产构建,并识别
dist中需要部署的文件。 - 正确设置 Vite 的
base,让 Phaser 动态加载的资源使用相同前缀。 - 用预览与浏览器开发者工具验证构建产物。
确认部署路径与构建配置
先在项目根目录确认存在 package.json、index.html,并已安装依赖。package.json 的 scripts 应包含 build 对应 vite build、preview 对应 vite preview;若缺失,只补这两项,不要覆盖其他脚本。
假设最终地址为 https://example.com/game/,就必须把 base 设置成 /game/。根域名直接访问的站点使用默认的 /。下面是只有基础选项时可用的完整 vite.config.js;若项目已经有插件、别名或其他配置,仅向原配置对象添加 base。
import { defineConfig } from 'vite';
export default defineConfig({
// 与正式部署的 URL 前缀保持一致,保留尾部斜杠
base: '/game/',
});该设置会让 Vite 在构建时修正入口 HTML、JS 导入的资源和 CSS 中受管理的资源地址;但不能指望它自动改写 Phaser 加载器中的任意字符串路径。改完配置后必须重新构建才会生效。
生成并检查 dist
在包含 package.json 的目录执行构建,再检查入口文件是否生成。这里假定项目已定义上述 build 脚本,且使用 Vite 默认输出目录 dist。
npm run build
node -e "const fs = require('node:fs'); console.log(fs.existsSync('dist/index.html') ? 'dist/index.html OK' : 'dist/index.html MISSING')"预期结果(省略版本、体积与耗时不固定的 Vite 构建日志):
dist/index.html OK还要打开 dist/index.html,确认入口脚本引用指向 /game/assets/ 下的打包文件;dist/assets/ 中通常能找到带哈希后缀的 JS 文件,具体名字由构建决定。放在 public/ 下的图片和音频会原样复制到 dist/ 对应位置,不自动添加文件名哈希。
修正 Phaser 资源请求
例如资源原本位于 public/assets/hero.png,构建后将位于 dist/assets/hero.png。部署到 /game/ 后,浏览器应请求 /game/assets/hero.png,而非 /assets/hero.png。Vite 不会替 Phaser 自动修正 this.load.image() 里的根路径字符串。

片段示例:以下方法放在已有的 Phaser.Scene 子类中,要求上述图片实际存在,并且该场景没有额外设置互相冲突的加载路径。
preload() {
// public 下的文件需由运行时显式附加 base 前缀
this.load.setBaseURL(import.meta.env.BASE_URL);
this.load.image('hero', 'assets/hero.png');
}重新构建后,请在浏览器 Network 面板确认 hero.png 请求地址为 /game/assets/hero.png,返回 200。setBaseURL() 会影响之后加入加载队列的相对路径;若原代码已对单个资源使用完整 /game/... URL,就不要再重复拼接前缀。对于放在 src/ 中并由 JS 静态导入的资源,优先让 Vite 接管 URL 生成。
预览产物并排除上线故障
构建成功后运行本地预览。--strictPort 保证 4173 被占用时直接报错,避免误测其他端口;该命令会持续运行,检查结束按 Ctrl+C 停止。
npm run preview -- --host 127.0.0.1 --port 4173 --strictPort预期访问地址(端口已由命令固定):
http://127.0.0.1:4173/game/在该地址打开游戏,按 F12 进入开发者工具的 Network 面板,勾选 Disable cache 后刷新。先确认 HTML、JS、图片、音频请求没有 404,再检查 Console 是否出现脚本加载或 Phaser 资源解码错误;最后实际测试开始游戏、场景切换、拾取与重新加载页面。
| 现象 | 优先检查及修复 |
|---|---|
/assets/hero.png 返回 404 |
Phaser 使用了站点根路径;按 BASE_URL 补上 /game/ |
/game/game/assets/hero.png 返回 404 |
setBaseURL() 与资源 URL 重复添加前缀;只保留一处 |
| JS 请求返回 HTML 或 MIME 类型报错 | 静态服务器的 /game/ 映射错误;应把 dist 的内容部署到该 URL 前缀下 |
预览通过后,交付的是 dist 内的构建产物,不是 src 和开发服务器。vite preview 只用于本地验收;正式上线仍需由静态托管服务按相同的 /game/ 路径提供文件,并在上线地址复测资源请求。