从外嵌网页到 Phaser 2D 原生舞台：键盘小鹿 Host/Runtime 契约隔离、系统 IME 穿透与 WebGL 恢复

一、 为什么必须推翻 iframe 外嵌模式？——三大体验死穴

在键盘小鹿早期的技术探索中，也曾尝试过通过 iframe 快速接入现成的 Web 游戏，但在真实用户测试中迅速暴露出不可调和的底层矛盾：

• P1 & P2 & P3 & P4 -> NativePhaserArchitecture
• 1. 致命的焦点丢失（Focus Loss）： iframe 与宿主页面属于完全独立的浏览上下文（Browsing Context）。当孩子在打字游戏中练习时，如果家长点击了顶部的“音量调节”或“暂停”按钮，键盘焦点立刻被宿主页面抢走；孩子继续敲击键盘，由于焦点不在 iframe 内部，所有按键全部失效，飞机被敌机击中，引发孩子极度挫败。
• 2. WebGL 与系统输入法（IME）的天然鸿沟： 这是所有 Web 游戏做汉字打字训练时的世界级难题：HTML5 Canvas 是一个单纯绘制像素的画布，它自身没有任何文本光标与输入法锚点。当孩子在《汉字飞机》游戏中需要打拼音输入中文时，操作系统的微软拼音或搜狗输入法根本不知道把候选词框画在哪里，经常漂移到屏幕最左上角，甚至直接被浏览器拦截，导致孩子根本无法在游戏中打出汉字。
• 3. WebGL Context Lost 导致黑屏“变砖”： 在 Windows 笔记本电脑中，当用户合上屏幕、系统休眠或切换集显/独显时，DirectX/OpenGL 驱动会强制回收显存资源，触发浏览器的 webglcontextlost 事件。传统的 iframe 小游戏没有任何容灾逻辑，Canvas 瞬间变为死黑一片，孩子辛苦积累的关卡分数当场化为乌有。

二、 键盘小鹿 Host/Runtime 契约隔离架构设计

键盘小鹿将游戏引擎（Phaser 3 Runtime）与应用外壳（Vue 3 Host）深度同构集成，建立了一套严格的双向契约通道：

三、 核心突破方案与工业级代码

// src/features/games/runtime/ImeProxyManager.ts 核心实现
export class ImeProxyManager {
  private proxyInput: HTMLInputElement

  constructor(container: HTMLElement) {
    this.proxyInput = document.createElement('input')
    this.proxyInput.type = 'text'
    this.proxyInput.autocomplete = 'off'
    this.proxyInput.spellcheck = false
    
    // 设置极致透明与极小尺寸，视觉不可见但保持操作系统焦点
    Object.assign(this.proxyInput.style, {
      position: 'absolute',
      width: '2px',
      height: '24px',
      opacity: '0.01',
      pointerEvents: 'none',
      zIndex: '10',
      border: 'none',
      background: 'transparent',
      outline: 'none'
    })

    container.appendChild(this.proxyInput)
  }

  // 动态同步游戏物体的逻辑坐标到物理 DOM 视口
  public updateAnchorPosition(gameX: number, gameY: number, dpr = window.devicePixelRatio) {
    // 换算 Canvas 实际显示缩放比
    this.proxyInput.style.transform = `translate(${gameX}px, ${gameY}px)`
    // 始终保持焦点，使系统输入法随时就绪
    this.proxyInput.focus({ preventScroll: true })
  }

  // 监听输入法合成与上屏
  public bindInputListener(onCommitText: (text: string) => void) {
    let isComposing = false

    this.proxyInput.addEventListener('compositionstart', () => { isComposing = true })
    this.proxyInput.addEventListener('compositionend', (e) => {
      isComposing = false
      const committed = e.data || this.proxyInput.value
      if (committed) {
        onCommitText(committed)
        this.proxyInput.value = ''
      }
    })

    this.proxyInput.addEventListener('input', (e) => {
      if (!isComposing) {
        const value = this.proxyInput.value
        if (value) {
          onCommitText(value)
          this.proxyInput.value = ''
        }
      }
    })
  }
}

• 1. 系统 IME 透明穿透与动态视口锚定： 为了让 Windows/Mac 的拼音输入法候选框能够“精准悬停在被锁定的敌机/汉字气球下方”，键盘小鹿在 Canvas 容器上方叠加了一个绝对定位的 1px 极简透明代理输入框（Proxy Input）：
• 2. WebGL Context Lost 自动恢复与资源热重建： 针对切屏与休眠引起的 Canvas 黑屏，我们在 Phaser 场景内部挂载了底层的 WebGL 驱动守护器：

四、 工业级排查复盘：高分屏（Retina / HiDPI）坐标缩放偏移

在多款不同分辨率笔记本（如 1920×1080 缩放 125%、2560×1600 缩放 200%）测试时，我们遭遇了严重的坐标漂移：

• 1. 现象复现： 在《汉字飞机》中，小鹿战机发射子弹射向天空中的气球，拼音输入法候选框明明应该在气球正下方，结果在 4K 笔记本上漂移到了屏幕右下角 500 像素之外，用户体验极其诡异。
• 2. 根因追溯： Phaser 3 内部采用固定分辨率（如 1600×900）的虚拟设计坐标系（Game Coordinates），而浏览器的 DOM 输入框定位依赖物理视口像素（CSS Pixels）。当系统的 window.devicePixelRatio 大于 1 时，若直接将 sprite.x、sprite.y 赋值给 DOM 样式，坐标会被双重放大或缩放。
• 3. 第一性原理精准对齐： 我们在契约桥接器中设计了双向投影映射矩阵（Matrix Projector）： $X_{DOM} = Canvas.left + (X_{Phaser} \times \frac{Canvas.clientWidth}{Game.width}) Y_{DOM} = Canvas.top + (Y_{Phaser} \times \frac{Canvas.clientHeight}{Game.height})$ 无论用户的 Windows 缩放是 100%、125%、150% 还是 200%，拼音输入法的候选词框始终严丝合缝、如同吸铁石般牢牢吸附在飞行物体的正下方！

五、 方案重构前后核心指标对比