游戏引擎 / 系统课时
调试手机横竖屏和触控冲突
调试手机横竖屏和触控冲突
桌面浏览器运行正常的 Phaser 游戏,在手机上可能出现画面过小、旋转后按钮错位、拖动时页面滚动或触摸无响应。本课使用 Chrome 移动设备模拟器和真机,建立可复现的测试页面,定位视口、屏幕方向与浏览器默认手势之间的冲突,并完成移动端验收。
学习目标
- 使用 Chrome DevTools 模拟手机横竖屏,检查视口尺寸和游戏画布的缩放结果。
- 配置 Phaser 4.2.1 的触控输入与 CSS
touch-action,识别页面滚动、缩放和指针事件冲突。 - 在 Android 与 iOS 真机上验证触控坐标、屏幕旋转、浏览器工具栏及安全区域的行为。
在移动设备模拟器中复现问题
Chrome DevTools 的设备模式可以模拟移动视口、设备像素比和触控输入,适合快速定位布局问题。但它不能完整模拟真实手机的多指手势、系统边缘操作和浏览器工具栏行为,因此最终仍需真机验收。
按以下步骤建立测试环境:
- 使用桌面 Chrome 打开游戏页面,按
F12打开开发者工具。 - 按
Ctrl+Shift+M(macOS 为Cmd+Shift+M)启用设备工具栏。 - 在设备尺寸下拉框中选择
Responsive,手动输入390 × 844,模拟手机竖屏。 - 点击设备工具栏中的旋转图标,切换到
844 × 390横屏。 - 在设备工具栏的设备类型设置中确认使用
Mobile,使鼠标操作模拟触控输入。 - 打开
Console和Elements,分别检查 JavaScript 日志与 Canvas 元素的实际尺寸。
本课以设计逻辑分辨率 960 × 540、宽高比 16:9 的横向游戏为例。使用 Phaser.Scale.FIT 时,画布始终保持设计宽高比。
假设父容器恰好是 844 × 390,没有额外内边距,实际显示画布约为 693 × 390,左右分别留白约 75 像素。若父容器为 390 × 844,画布则约为 390 × 219,上下留下较大空白。
这些留白是 FIT 保持比例的正常结果,并非渲染错误。不过,竖屏下整幅横向游戏会明显缩小,因此需要评估触控按钮是否仍然容易操作。正式项目可以提供独立竖屏布局,或在竖屏时显示横屏提示。
建立可观测的触控测试页面
为了区分画布缩放问题和触控事件问题,先制作一个不依赖图片素材的最小测试页面。页面包含一个青绿色圆点:点击时圆点移动到触控位置,按住拖动时持续跟随,并在控制台记录屏幕方向和画布尺寸变化。
以下示例适用于 Phaser 4.2.1,使用 Vite 的 Vanilla JavaScript 模板。需要本机已安装 Node.js 和 npm。
在终端执行:
npm create vite@latest phaser-mobile-check -- --template vanilla
cd phaser-mobile-check
npm install
npm install phaser@4.2.1预期结果:生成包含 index.html、package.json 和 src/main.js 的项目,且依赖中安装 Phaser 4.2.1。安装命令应正常结束,不出现 npm ERR!。
将项目根目录的 index.html 替换为以下内容:
<!doctype html>
<html lang='zh-CN'>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1, viewport-fit=cover'>
<title>Phaser 移动端触控检查</title>
<style>
html, body { margin: 0; width: 100%; height: 100%; }
body {
box-sizing: border-box;
height: 100vh;
height: 100dvh;
overflow: hidden;
padding: env(safe-area-inset-top) env(safe-area-inset-right)
env(safe-area-inset-bottom) env(safe-area-inset-left);
background: #102236;
}
#game { width: 100%; height: 100%; }
/* 只禁止游戏画布内的浏览器默认触摸手势 */
#game canvas { display: block; touch-action: none; }
</style>
</head>
<body>
<div id='game'></div>
<script type='module' src='/src/main.js'></script>
</body>
</html>这里有三个直接影响手机表现的设置:
width=device-width, initial-scale=1:让布局视口跟随设备的 CSS 像素宽度,避免浏览器按桌面网页宽度缩放整个页面。100dvh:让容器高度跟随动态视口,适应移动浏览器工具栏显示与收起时的可见区域变化;前面的100vh作为旧环境的回退值。env(safe-area-inset-*):为支持安全区域的浏览器预留边距,避免游戏画布进入刘海、圆角或底部系统指示条区域。
touch-action: none 仅应用于游戏 Canvas,避免拖动游戏时触发页面滚动或浏览器缩放。示例页面是全屏游戏,因此还设置了 overflow: hidden。如果游戏嵌入可滚动网页,不应直接把这些限制扩大到整个页面。
然后将 src/main.js 替换为:
import Phaser from 'phaser';
class MobileDebugScene extends Phaser.Scene {
constructor() {
super('MobileDebugScene');
}
create() {
const status = this.add.text(24, 24, '点按或拖动屏幕', {
fontFamily: 'Arial, sans-serif',
fontSize: '28px',
color: '#ffffff'
});
const marker = this.add.circle(480, 270, 36, 0x18b89b);
// 使用 Phaser 已换算的游戏逻辑坐标,不再乘设备像素比
const showPoint = (name, pointer) => {
marker.setPosition(pointer.x, pointer.y);
status.setText(`${name}: ${Math.round(pointer.x)}, ${Math.round(pointer.y)}`);
};
this.input.on('pointerdown', pointer => {
showPoint('down', pointer);
console.log('down', pointer.id);
});
this.input.on('pointermove', pointer => {
if (pointer.isDown) showPoint('move', pointer);
});
this.input.on('pointerup', pointer => {
showPoint('up', pointer);
console.log('up', pointer.id);
});
this.input.on('pointerupoutside', pointer => {
status.setText(`outside: ${pointer.id}`);
});
// 记录逻辑画布尺寸与实际显示尺寸,便于定位缩放问题
this.scale.on('resize', (gameSize, baseSize, displaySize) => {
console.log('resize',
`${gameSize.width}x${gameSize.height}`,
`${displaySize.width}x${displaySize.height}`);
});
this.scale.on('orientationchange', orientation => {
console.log('orientationchange', orientation);
});
}
}
new Phaser.Game({
type: Phaser.AUTO,
parent: 'game',
backgroundColor: '#132a40',
scale: {
mode: Phaser.Scale.FIT,
autoCenter: Phaser.Scale.CENTER_BOTH,
width: 960,
height: 540
},
input: {
activePointers: 2,
touch: { capture: true }
},
scene: MobileDebugScene
});input.touch.capture 让 Phaser 的 Touch Manager 尝试阻止触摸事件的浏览器默认行为;CSS touch-action 则提前声明哪些手势允许由浏览器处理。二者作用层次不同,可以配合使用。activePointers: 2 预留两个触摸指针,便于后续双指测试。
启动开发服务器:
npm run dev -- --host 0.0.0.0预期输出格式如下,版本号、启动时间、局域网地址和端口以终端实际显示为准:
VITE v<VERSION> ready in <TIME> ms
Local: http://localhost:<PORT>/
Network: http://<LAN_IP>:<PORT>/在桌面浏览器访问 Local 地址,用鼠标点击和拖动游戏区域。
预期结果:页面出现深蓝色游戏画布和青绿色圆点。点击时状态文字变为 down: x, y,拖动时变为 move: x, y,圆点跟随指针移动;松开后显示 up: x, y。其中 x、y 为本次操作得到的实际逻辑坐标。
在移动设备模拟器中切换横竖屏,控制台应记录相应的 resize 信息。部分浏览器还会触发 orientationchange。事件是否触发以及输出顺序可能因浏览器而不同,不能仅凭缺少方向事件就认定缩放失败。
区分视口变化、方向变化和坐标错误
移动端调试时需要区分三个尺寸:浏览器布局视口、Phaser 游戏逻辑尺寸,以及 Canvas 的实际显示尺寸。
| 检查对象 | 本例观察值 | 含义 |
|---|---|---|
| 浏览器视口 | 如 844 × 390 |
手机页面可用于布局的 CSS 像素区域 |
| 游戏逻辑尺寸 | 960 × 540 |
游戏内部对象使用的坐标空间 |
| Canvas 显示尺寸 | 约 693 × 390 |
FIT 后实际显示的画布尺寸 |
上表显示尺寸仅对应父容器恰好为 844 × 390 且没有安全区域内边距的情况。实际设备上应以 displaySize 和 Elements 面板中的 Canvas 尺寸为准。
屏幕方向也不能直接通过游戏设计尺寸判断。this.scale.isGameLandscape 表示游戏本身是横向设计,而 this.scale.isLandscape 才表示 Scale Manager 检测到的设备方向。浏览器是否提供方向信息具有兼容性差异,因此布局判断还应结合实际视口宽高。
如果横屏后触控位置偏移,先检查是否对 pointer.x、pointer.y 额外执行了 devicePixelRatio 倍乘,或手动减去了画布留白。Phaser 的 Input Manager 已经负责将触摸输入映射为游戏坐标,在普通 FIT 场景中不应重复转换。
当页面通过 CSS transform 移动画布,或者父容器发生特殊布局变化时,应检查 Canvas 的实际边界。不要只修改 Canvas 的 CSS 宽高而绕过 Scale Manager;否则视觉尺寸与输入坐标可能不同步。
定位浏览器默认手势与游戏触控冲突
手机触摸操作首先由浏览器接收。浏览器需要判断手势用于页面滚动、缩放,还是交给游戏处理。如果浏览器开始接管平移或缩放手势,游戏的拖动序列可能中断,原生 Pointer Events 路径中也可能发生 pointercancel。

可按照以下顺序定位具体问题:
- 点击没有反应:查看 Console 是否出现
down,检查 Canvas 上方是否存在覆盖层,并确认监听器属于当前正在运行的 Scene。 - 拖动时整个网页移动:在 Elements 的 Computed 样式中检查 Canvas 的
touch-action是否实际为none,再检查 Phaser 的input.touch.capture配置。 - 拖动开始后突然停止:检查是否发生浏览器手势接管、手指滑出 Canvas、页面失焦或 Scene 被暂停。
- 触摸位置不准确:比较实际 Canvas 边界、Scale Manager 显示尺寸与逻辑坐标,排除重复坐标缩放。
- 一次触摸触发两次操作:检查是否同时给同一个动作绑定了 DOM
click、原生touchstart和 Phaserpointerdown,避免重复执行。
如果游戏需要手指拖动控制角色,建议由 Phaser 统一处理 Canvas 内的输入。不要额外在 document 上无条件调用 preventDefault(),否则可能破坏页面滚动、输入框操作以及辅助功能。
对于没有自定义拖动需求、仍需要浏览器滚动的区域,可以保留 touch-action: auto 或根据交互需求选择 manipulation 等值。touch-action: none 会限制浏览器的部分缩放操作,正式产品还应考虑可访问性,避免对非游戏内容使用。
pointerupoutside 可以辅助处理手指在 Canvas 外松开的情况,但它并不保证覆盖所有浏览器取消或系统中断事件。持续按住才能移动的虚拟方向键,还应在页面 blur、visibilitychange 或游戏失去焦点时清除按下状态,防止角色持续移动。
使用真机完成横竖屏验收
确保电脑与手机位于可以互相访问的局域网,且本机防火墙允许开发服务器端口访问。在手机浏览器中打开终端显示的 Network 地址,访问时保持电脑上的开发服务器运行。
Chrome 模拟器的尺寸与触控模拟只能作为第一轮检查。第二轮至少使用一台 Android Chrome 和一台 iOS Safari 真机,按下表执行验收。
| 测试场景 | 操作 | 通过标准 |
|---|---|---|
| 竖屏进入 | 保持竖屏首次打开 | 无横向网页溢出;测试页正常显示,正式横屏游戏应提供清楚的方向提示或适配布局 |
| 旋转到横屏 | 旋转设备后点击画布四角附近 | 画面比例正常,触点与游戏对象位置匹配 |
| 连续旋转 | 横屏、竖屏往返 5 次 | 不出现黑屏、异常拉伸、Canvas 重叠或重复创建游戏实例 |
| 单指拖动 | 按住圆点区域持续滑动 3 秒 | 圆点持续跟随,页面不因游戏内拖动而滚动 |
| 多指输入 | 两指同时接触不同位置 | 不触发意外网页缩放;正式游戏的多指控制按设计工作 |
| 浏览器工具栏 | 滚动或改变 Safari、Chrome 工具栏状态 | 可视区域变化后画布保持正常比例,不遮挡重要 UI |
| 安全区域 | 检查刘海、圆角和底部手势条附近 | 关键按钮与提示没有被设备区域遮挡 |
| 中断触控 | 按住时切换应用,再返回游戏 | 正式游戏的持续输入状态已释放,不会自动移动或连续触发 |
其中双指和中断测试应使用真实游戏的控制逻辑验收。本文的最小示例主要用于观察触点和坐标,不包含虚拟摇杆的持续运动状态管理。
最后在目标设备上重复执行点击、拖动、旋转和页面失焦测试。如果问题只发生在某一台真机,应记录设备型号、操作系统、浏览器版本、横竖屏状态、复现步骤和 Console 信息,再修复对应行为,而不是直接修改整个游戏的设计分辨率。
完成验收的标准是:不同方向下画布和 UI 的显示结果符合预期,触控坐标与视觉位置一致,游戏操作不被浏览器默认手势意外打断,并且旋转或失焦后输入状态能够正确恢复。