koishi-plugin-haulmp-tools 1.0.2 → 1.0.3

package/lib/command/locate.js

@@ -62,6 +62,29 @@ let mapPage = null
 let mapPageReady = false
 let mapPageInit = null
 let mapPageLock = Promise.resolve()
+// 环境不支持 WebGL2 时（无头 Linux 常见）不再反复尝试：命中后冷却一段时间再试
+let mapUnsupportedAt = 0
+const MAP_RETRY_MS = 30 * 60 * 1000
+
+// 等页面就绪；期间若出现 WebGL 初始化错误则立即失败（不必干等 30 秒）
+function waitMapReady(page, readErr) {
+  return new Promise((resolve, reject) => {
+    let done = false
+    const finish = (fn, v) => {
+      if (done) return
+      done = true
+      clearInterval(timer)
+      fn(v)
+    }
+    const timer = setInterval(() => {
+      const e = readErr()
+      if (e) finish(reject, new Error(`WebGL2 不可用（${String(e).slice(0, 60)}），该环境无法渲染地图`))
+    }, 250)
+    page.waitForFunction(() => window.__ready === true && typeof window.getTileUrl === 'function', { timeout: 30000 })
+      .then(() => finish(resolve))
+      .catch((e) => finish(reject, e))
+  })
+}
 
 function withTimeout(promise, ms, onTimeout) {
   let timer
@@ -151,6 +174,7 @@ async function doGetMapPage(ctx) {
     puppeteer = ctx.get('puppeteer')
   } catch (e) { /* ignore */ }
   if (!puppeteer) return null
+  if (mapUnsupportedAt && Date.now() - mapUnsupportedAt < MAP_RETRY_MS) return null
   const port = await startStaticServer(ctx)
   if (!port) return null
   if (mapPage && mapPageReady) {
@@ -174,23 +198,33 @@ async function doGetMapPage(ctx) {
   const t0 = Date.now()
   mapPageReady = false
   mapPage = await puppeteer.page()
+  let pageErr = null
+  const readErr = () => pageErr
+  mapPage.on('pageerror', (err) => {
+    const msg = err && err.message ? err.message : String(err)
+    if (/webgl|gpuinitialization/i.test(msg)) pageErr = msg
+    ctx.logger('haulmp').warn('地图页面脚本错误: %s', msg)
+  })
   try {
-    mapPage.on('pageerror', (err) => {
-      ctx.logger('haulmp').warn('地图页面脚本错误: %s', err && err.message ? err.message : String(err))
-    })
     await mapPage.setViewport({ width: 720, height: 500, deviceScaleFactor: 2 })
     await mapPage.goto(`http://127.0.0.1:${port}/`, { waitUntil: 'domcontentloaded', timeout: 30000 })
     // __ready（底图 load 事件）与 getTileUrl（模块执行完成）都满足才算就绪
-    await mapPage.waitForFunction(() => window.__ready === true && typeof window.getTileUrl === 'function', { timeout: 30000 })
+    await waitMapReady(mapPage, readErr)
     mapPageReady = true
+    mapUnsupportedAt = 0
     ctx.logger('haulmp').info('地图页面构建完成 %dms', Date.now() - t0)
     preloadEurope(mapPage).catch(() => {})
     return mapPage
   } catch (e) {
-    ctx.logger('haulmp').warn('地图页面初始化失败: %s', e.message)
     try { mapPage.close().catch(() => {}) } catch (err) { /* ignore */ }
     mapPage = null
     mapPageReady = false
+    if (/WebGL2 不可用/.test(e.message)) {
+      mapUnsupportedAt = Date.now()
+      ctx.logger('haulmp').warn('地图渲染不可用：当前浏览器缺少 WebGL2（无头 Linux 常见）。定位指令将退回文字结果；如需地图请在 puppeteer 服务配置 args 中加入：--use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader（去掉 --disable-gpu），已暂停 30 分钟内重试')
+    } else {
+      ctx.logger('haulmp').warn('地图页面初始化失败: %s', e.message)
+    }
     return null
   }
 }
@@ -217,10 +251,104 @@ async function mapShot(ctx, info, p, nearby) {
   return run
 }
 
+// ---- Canvas 2D 兜底页（不依赖 WebGL，任何无头环境都能出图）----
+let fbPage = null
+let fbReady = false
+let fbLock = Promise.resolve()
+
+async function getFallbackPage(ctx) {
+  const run = fbLock.then(() => doGetFallbackPage(ctx), () => doGetFallbackPage(ctx))
+  fbLock = run.then(() => {}, () => {})
+  return run
+}
+
+async function doGetFallbackPage(ctx) {
+  let puppeteer = null
+  try {
+    puppeteer = ctx.get('puppeteer')
+  } catch (e) { /* ignore */ }
+  if (!puppeteer) return null
+  const port = await startStaticServer(ctx)
+  if (!port) return null
+  if (fbPage && fbReady) {
+    try {
+      if (!fbPage.isClosed()) {
+        ctx.logger('haulmp').info('使用已就绪兜底页面')
+        return fbPage
+      }
+    } catch (e) { /* ignore */ }
+    fbPage = null
+    fbReady = false
+  }
+  if (fbPage) {
+    try { fbPage.close().catch(() => {}) } catch (e) { /* ignore */ }
+    fbPage = null
+    fbReady = false
+  }
+  ctx.logger('haulmp').info('重建兜底页面…')
+  const t0 = Date.now()
+  fbPage = await puppeteer.page()
+  try {
+    fbPage.on('pageerror', (err) => {
+      ctx.logger('haulmp').warn('兜底页面脚本错误: %s', err && err.message ? err.message : String(err))
+    })
+    await fbPage.setViewport({ width: 760, height: 560, deviceScaleFactor: 2 })
+    await fbPage.goto(`http://127.0.0.1:${port}/fallback.html`, { waitUntil: 'domcontentloaded', timeout: 20000 })
+    await fbPage.waitForFunction(() => window.__ready === true && typeof window.drawView === 'function', { timeout: 15000 })
+    fbReady = true
+    ctx.logger('haulmp').info('兜底页面构建完成 %dms', Date.now() - t0)
+    return fbPage
+  } catch (e) {
+    ctx.logger('haulmp').warn('兜底页面初始化失败: %s', e.message)
+    try { fbPage.close().catch(() => {}) } catch (err) { /* ignore */ }
+    fbPage = null
+    fbReady = false
+    return null
+  }
+}
+
+async function fallbackShot(ctx, info, nearby) {
+  try {
+    const page = await getFallbackPage(ctx)
+    if (!page) return null
+    const reset = () => {
+      try { page.close().catch(() => {}) } catch (e) { /* ignore */ }
+      fbPage = null
+      fbReady = false
+    }
+    await withTimeout(
+      page.evaluate((data) => window.drawView(data), {
+        info,
+        nearby: nearby.map((n) => ({ lng: n.lon, lat: n.lat, name: n.name, km: n.km })),
+        self: { lng: info.lng, lat: info.lat, bearing: info.bearing },
+      }),
+      10000,
+      reset,
+    )
+    const el = await page.$('#shot')
+    const buf = await withTimeout(
+      el ? el.screenshot({ encoding: 'binary', type: 'png' }) : page.screenshot({ encoding: 'binary', type: 'png' }),
+      10000,
+      reset,
+    )
+    ctx.logger('haulmp').info('兜底方位图渲染完成')
+    return buf
+  } catch (e) {
+    ctx.logger('haulmp').warn('兜底方位图渲染失败: %s', e.message)
+    if (fbPage) {
+      try { fbPage.close().catch(() => {}) } catch (err) { /* ignore */ }
+      fbPage = null
+      fbReady = false
+    }
+    return null
+  }
+}
+
 async function doMapShot(ctx, info, p, nearby) {
   try {
     const page = await getMapPage(ctx)
-    if (!page) return null
+    // 该环境不支持 WebGL2（无 GPU 的无头服务器）→ 退回 Canvas 方位图，仍能出图
+    if (!page) return await fallbackShot(ctx, info, nearby)
     const [lng, lat] = gameToLngLat(p.x, p.z)
     const resetPage = () => {
       try { page.close().catch(() => {}) } catch (e) { /* ignore */ }
@@ -371,6 +499,13 @@ function apply(ctx, config) {
         city: cityDisplay,
         dist: near.km.toFixed(0),
         id: p.id,
+        // 供 Canvas 兜底页使用的数值字段
+        lng,
+        lat,
+        bearing: bearingDeg,
+        bearingText,
+        speed: p.speed,
+        model,
       }
 
       let card = null
@@ -393,4 +528,4 @@ function apply(ctx, config) {
     })
 }
 
-module.exports = { apply, gameToLngLat, nearestCity, nearbyPlayers, loadPlaces, matchPlayer, headingBearing, mapShot, syncTileVersion }
+module.exports = { apply, gameToLngLat, nearestCity, nearbyPlayers, loadPlaces, matchPlayer, headingBearing, mapShot, fallbackShot, syncTileVersion }

package/lib/command/menu.js

@@ -53,7 +53,7 @@ function menuCard() {
 </style></head><body><div id="card">${CARD_DECO}
 <div class="head"><span class="title">HaulMP 功能菜单</span><span class="brand">MENU</span></div>
 <div class="mgrid">${sections}</div>
-<div class="foot"><span>HaulMP · 指令末尾 H / h 通用</span><span>发送「菜单」查看本菜单</span></div>
+<div class="foot"><span>HaulMP · 指令末尾 H / h 通用</span><span>发送「菜单H」查看本菜单</span></div>
 </div></body></html>`
 }
 
@@ -64,13 +64,14 @@ function menuText() {
     for (const [cmd, desc] of items) lines.push(` · ${cmd} — ${desc}`)
   }
   lines.push('━━━━━━━━━━━━')
-  lines.push('（指令末尾 H/h 通用，菜单无需加 H）')
+  lines.push('（指令末尾 H/h 通用；看本菜单请发送「菜单H」）')
   return lines.join('\n')
 }
 
 function apply(ctx, config) {
-  ctx.command('菜单h', 'HaulMP 功能菜单')
-    .alias('menuh')
+  // 只注册带 H 的写法（菜单H / 菜单h / menuh），不注册裸「菜单」——避免与其它插件的同名指令冲突
+  ctx.command('菜单H', 'HaulMP 功能菜单')
+    .alias('menuh', '菜单h')
     .action(async ({ session }) => {
       if (!session) return
       if (!isText(config, 'menu')) {

package/lib/index.js

@@ -48,7 +48,7 @@ const Config = Schema.object({
     status: cardMode('服务器状态'),
     companyBind: cardMode('车队绑定'),
     companyBoard: cardMode('今日里程'),
-    menu: cardMode('菜单'),
+    menu: cardMode('菜单H'),
     changelog: cardMode('客户端更新推送'),
     announce: cardMode('车队公告推送'),
     locate: cardMode('实时定位'),

package/lib/resource/map/fallback.html

@@ -0,0 +1,241 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>HaulMP 定位（Canvas 兜底）</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    background-color: #eef2fc;
+    background-image:
+      radial-gradient(48% 42% at 8% 2%, rgba(129,140,248,.62), transparent 64%),
+      radial-gradient(44% 40% at 94% 6%, rgba(56,189,248,.52), transparent 62%),
+      radial-gradient(50% 46% at 90% 94%, rgba(52,211,153,.48), transparent 64%),
+      radial-gradient(46% 40% at 6% 98%, rgba(251,191,36,.44), transparent 62%),
+      radial-gradient(40% 36% at 50% 50%, rgba(244,114,182,.30), transparent 66%);
+    font-family: "Segoe UI","Droid Sans Fallback","Noto Sans CJK SC","Microsoft YaHei",sans-serif;
+  }
+  #shot {
+    --t1: #16203a; --t2: #48587a; --t3: #7b8aa5;
+    --glass: rgba(255,255,255,.62); --glass-2: rgba(255,255,255,.52);
+    --stroke: rgba(255,255,255,.95); --edge: rgba(124,144,196,.22);
+    --shadow: 0 12px 30px -16px rgba(58,76,140,.36), inset 0 1px 0 rgba(255,255,255,.95);
+    width: 720px; padding: 22px; color: var(--t2);
+  }
+  .card {
+    border-radius: 26px; padding: 20px;
+    background: linear-gradient(150deg, rgba(255,255,255,.60), rgba(248,251,255,.38) 48%, rgba(255,255,255,.54));
+    border: 1px solid var(--stroke);
+    box-shadow: 0 26px 64px -24px rgba(58,76,140,.50), inset 0 1px 0 rgba(255,255,255,.98);
+    backdrop-filter: saturate(190%) blur(26px); -webkit-backdrop-filter: saturate(190%) blur(26px);
+    position: relative; overflow: hidden;
+  }
+  .glow { position: absolute; top: 0; left: 0; right: 0; height: 4px;
+    background: linear-gradient(90deg, transparent, #4f46e5 26%, #0ea5e9 74%, transparent); opacity: .9; }
+  .head { display: flex; align-items: center; gap: 14px; padding-bottom: 14px; border-bottom: 1px solid var(--edge); }
+  .ava { width: 58px; height: 58px; border-radius: 18px; flex: none; display: flex; align-items: center; justify-content: center;
+    font-size: 24px; font-weight: 700; color: #3730a3; border: 1px solid var(--stroke);
+    background: linear-gradient(150deg, rgba(99,102,241,.30), rgba(14,165,233,.24)); box-shadow: var(--shadow); }
+  .who { flex: 1; min-width: 0; }
+  .name { font-size: 21px; font-weight: 700; color: var(--t1); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .sub { font-size: 13px; color: var(--t3); margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .loc { text-align: right; flex: none; }
+  .city { font-size: 17px; font-weight: 700; color: #3730a3; }
+  .dist { font-size: 12px; color: var(--t3); margin-top: 3px; }
+  .chips { display: flex; gap: 8px; margin-top: 14px; }
+  .chip { font-size: 12.5px; color: #3730a3; background: var(--glass-2); border: 1px solid var(--stroke);
+    border-radius: 999px; padding: 4px 12px; box-shadow: var(--shadow); white-space: nowrap; }
+  .chip b { color: var(--t1); }
+  .plotwrap { margin-top: 14px; border-radius: 20px; border: 1px solid var(--stroke); background: var(--glass-2);
+    box-shadow: var(--shadow); overflow: hidden; }
+  canvas { display: block; }
+  .foot { margin-top: 14px; padding-top: 12px; border-top: 1px solid var(--edge);
+    display: flex; justify-content: space-between; font-size: 11.5px; color: var(--t3); }
+</style>
+</head>
+<body>
+<div id="shot">
+  <div class="card">
+    <div class="glow"></div>
+    <div class="head">
+      <div class="ava" id="ava">?</div>
+      <div class="who">
+        <div class="name" id="name">-</div>
+        <div class="sub" id="sub"></div>
+      </div>
+      <div class="loc">
+        <div class="city" id="city">-</div>
+        <div class="dist" id="dist"></div>
+      </div>
+    </div>
+    <div class="chips" id="chips"></div>
+    <div class="plotwrap"><canvas id="plot" width="1336" height="600" style="width:668px;height:300px"></canvas></div>
+    <div class="foot"><span id="near">周边 0 人</span><span id="fid">HaulMP</span></div>
+  </div>
+</div>
+<script>
+  window.__ready = true
+
+  var RANGE = 30           // 图幅半径（km）
+  var PAD = 34             // 画布内边距
+  var W = 668, H = 300
+
+  function drawRadar(data) {
+    var cv = document.getElementById('plot')
+    var ctx = cv.getContext('2d')
+    var S = 2
+    ctx.setTransform(S, 0, 0, S, 0, 0)
+    ctx.clearRect(0, 0, W, H)
+
+    var cx = W / 2, cy = H / 2
+    var R = Math.min(W, H) / 2 - PAD
+    var scale = R / RANGE
+
+    // 量程环
+    ctx.save()
+    for (var i = 1; i <= 3; i++) {
+      var r = R * i / 3
+      ctx.beginPath()
+      ctx.arc(cx, cy, r, 0, Math.PI * 2)
+      ctx.setLineDash(i === 3 ? [] : [4, 5])
+      ctx.lineWidth = 1
+      ctx.strokeStyle = i === 3 ? 'rgba(124,144,196,.45)' : 'rgba(124,144,196,.28)'
+      ctx.stroke()
+      ctx.setLineDash([])
+      ctx.font = '11px "Microsoft YaHei",sans-serif'
+      ctx.fillStyle = 'rgba(123,138,165,.95)'
+      ctx.textAlign = 'left'
+      ctx.fillText((RANGE * i / 3) + ' km', cx + r + 5, cy - 4)
+    }
+    // 十字轴
+    ctx.beginPath()
+    ctx.moveTo(cx - R, cy); ctx.lineTo(cx + R, cy)
+    ctx.moveTo(cx, cy - R); ctx.lineTo(cx, cy + R)
+    ctx.strokeStyle = 'rgba(124,144,196,.30)'
+    ctx.lineWidth = 1
+    ctx.stroke()
+    // 方位
+    ctx.font = '11px "Microsoft YaHei",sans-serif'
+    ctx.fillStyle = 'rgba(72,88,122,.9)'
+    ctx.textAlign = 'center'
+    ctx.fillText('北', cx, cy - R - 10)
+    ctx.fillText('南', cx, cy + R + 15)
+    ctx.textAlign = 'right'; ctx.fillText('西', cx - R - 5, cy + 4)
+    ctx.textAlign = 'left'; ctx.fillText('东', cx + R + 5, cy + 4)
+    ctx.restore()
+
+    // 相对坐标（等距圆柱近似，km）
+    var sx = data.self.lng != null ? data.self.lng : data.self.lon
+    var sy = data.self.lat
+    var kx = 111.32 * Math.cos(sy * Math.PI / 180)
+    var ky = 111.32
+    function pt(lon, lat) {
+      return [cx + (lon - sx) * kx * scale, cy - (lat - sy) * ky * scale]
+    }
+
+    // 附近玩家
+    var nearby = data.nearby || []
+    for (var j = 0; j < nearby.length; j++) {
+      var n = nearby[j]
+      var q = pt(n.lng, n.lat)
+      ctx.beginPath()
+      ctx.arc(q[0], q[1], 5, 0, Math.PI * 2)
+      ctx.fillStyle = '#0ea5e9'
+      ctx.fill()
+      ctx.lineWidth = 2
+      ctx.strokeStyle = 'rgba(255,255,255,.95)'
+      ctx.stroke()
+
+      var label = n.name + (n.km != null ? ' · ' + Number(n.km).toFixed(1) + ' km' : '')
+      ctx.font = '11px "Microsoft YaHei",sans-serif'
+      var tw = ctx.measureText(label).width
+      var lx = q[0] + 9, ly = q[1] - 20
+      if (lx + tw + 12 > W - 6) lx = q[0] - tw - 21
+      if (ly < 4) ly = q[1] + 8
+      ctx.fillStyle = 'rgba(255,255,255,.88)'
+      ctx.strokeStyle = 'rgba(124,144,196,.30)'
+      ctx.lineWidth = 1
+      roundRect(ctx, lx, ly, tw + 12, 19, 9)
+      ctx.fill(); ctx.stroke()
+      ctx.fillStyle = '#48587a'
+      ctx.textAlign = 'left'
+      ctx.fillText(label, lx + 6, ly + 13.5)
+    }
+
+    // 自己（中心标记 + 朝向箭头）
+    ctx.save()
+    ctx.translate(cx, cy)
+    var bearing = Number(data.self.bearing)
+    if (isFinite(bearing)) {
+      ctx.save()
+      ctx.rotate(bearing * Math.PI / 180)
+      ctx.beginPath()
+      ctx.moveTo(0, -30)
+      ctx.lineTo(-9, -11)
+      ctx.lineTo(9, -11)
+      ctx.closePath()
+      ctx.fillStyle = 'rgba(79,70,229,.85)'
+      ctx.fill()
+      ctx.restore()
+    }
+    ctx.beginPath()
+    ctx.arc(0, 0, 26, 0, Math.PI * 2)
+    ctx.fillStyle = 'rgba(79,70,229,.14)'
+    ctx.fill()
+    ctx.beginPath()
+    ctx.arc(0, 0, 8, 0, Math.PI * 2)
+    ctx.fillStyle = '#4f46e5'
+    ctx.fill()
+    ctx.lineWidth = 2.5
+    ctx.strokeStyle = 'rgba(255,255,255,.95)'
+    ctx.stroke()
+    ctx.restore()
+
+    if (!nearby.length) {
+      ctx.font = '13px "Microsoft YaHei",sans-serif'
+      ctx.fillStyle = 'rgba(123,138,165,.95)'
+      ctx.textAlign = 'center'
+      ctx.fillText('30 km 内暂时没有其他玩家', cx, cy + R - 14)
+    }
+  }
+
+  function roundRect(ctx, x, y, w, h, r) {
+    ctx.beginPath()
+    ctx.moveTo(x + r, y)
+    ctx.lineTo(x + w - r, y)
+    ctx.quadraticCurveTo(x + w, y, x + w, y + r)
+    ctx.lineTo(x + w, y + h - r)
+    ctx.quadraticCurveTo(x + w, y + h, x + w - r, y + h)
+    ctx.lineTo(x + r, y + h)
+    ctx.quadraticCurveTo(x, y + h, x, y + h - r)
+    ctx.lineTo(x, y + r)
+    ctx.quadraticCurveTo(x, y, x + r, y)
+    ctx.closePath()
+  }
+
+  window.drawView = function (data) {
+    var info = data.info || {}
+    document.getElementById('ava').textContent = info.initial || '?'
+    document.getElementById('name').textContent = info.name || '-'
+    document.getElementById('sub').textContent = info.sub || ''
+    document.getElementById('city').textContent = info.city || '-'
+    document.getElementById('dist').textContent = '距市中心 ' + (info.dist != null ? info.dist : '—') + ' km'
+
+    var chips = []
+    if (info.speed != null) chips.push('速度 <b>' + info.speed + ' km/h</b>')
+    if (info.bearingText) chips.push('朝向 <b>' + info.bearingText + '</b>')
+    chips.push('车型 <b>' + (info.model || '未知') + '</b>')
+    document.getElementById('chips').innerHTML = chips.map(function (c) {
+      return '<span class="chip">' + c + '</span>'
+    }).join('')
+
+    var n = (data.nearby || []).length
+    document.getElementById('near').textContent = '周边 ' + n + ' 人（' + RANGE + ' km 内）'
+    document.getElementById('fid').textContent = 'ID ' + (info.id != null ? info.id : '—') + ' · HaulMP · 方位图模式'
+
+    drawRadar(data)
+    return true
+  }
+</script>
+</body>
+</html>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-haulmp-tools",
   "description": "欧卡HaulMP联机平台信息查询",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "contributors": [
     "opwop <slhp1013@qq.com>"
   ],

package/readme.md

@@ -25,7 +25,7 @@
 | 车队 | `绑定车队H <车队ID或链接>` | 绑定本群车队（仅队长可绑定） |
 | 车队 | `解绑车队H` | 解除本群车队绑定（绑定人或队长） |
 | 车队 | `今日里程H` | 本群车队当天里程排行（每日自动建立基准） |
-| 其他 | `菜单` | 功能菜单 |
+| 其他 | `菜单H` | 功能菜单（只注册带 H 的写法，避免与其它插件的「菜单」指令冲突） |
 
 自动推送（无需指令）：
 
@@ -78,6 +78,42 @@ src/
 - 数据库服务（`database`）
 - `puppeteer` 服务（卡片图片渲染；未启用时自动退回文字输出）
 
+## 部署注意：定位地图需要 WebGL2
+
+`定位H` 的地图由 maplibre 渲染，**需要浏览器支持 WebGL2**。无头 Linux 服务器默认没有 GPU，
+浏览器会以「WebGL2 is required to display this map / GPUInitializationError」失败，
+此时定位指令会自动退回文字结果（地图页面 30 分钟内不再重试）。
+
+需要地图出图，请在 **puppeteer 服务的配置**里加上软件渲染参数：
+
+```yaml
+puppeteer:
+  args:
+    - --no-sandbox
+    - --disable-setuid-sandbox
+    - --disable-dev-shm-usage
+    - --use-gl=angle
+    - --use-angle=swiftshader
+    - --enable-unsafe-swiftshader
+    - --ignore-gpu-blocklist
+```
+
+- 新版 Chrome 已不接受 `--use-gl=swiftshader`，必须用 `--use-gl=angle --use-angle=swiftshader`。
+- `--enable-unsafe-swiftshader` 不能省：Chrome 默认禁止用 SwiftShader 提供 WebGL，缺了它拿到的仍是空 canvas。
+- **不要**加 `--disable-gpu`，那会彻底关掉 WebGL。
+- `headless` 需保持 `true`（新版无头模式）；远程浏览器模式（`remote: true`）要把参数加在**远端浏览器的启动命令**上。
+
+### 没有 WebGL 也能出图：Canvas 方位图模式
+
+若服务器确实无法开启软件渲染（WebGL/WebGL2 都拿不到），`定位H` **会自动退回纯 Canvas 2D 的方位图**
+（不依赖任何 GL，任何无头环境都能画）：
+
+- 中心是玩家本人（带朝向箭头），周围 30 km 内的其他玩家按真实相对方位与距离落点并标注名字/距离；
+- 环形量程 10 / 20 / 30 km、十字方位轴、玻璃质感信息栏（速度 / 朝向 / 车型 / 所在城市 / ID）；
+- 与真实地图的差别：**没有路网**，只有相对方位关系（页面右下角标注「方位图模式」）。
+
+一旦 WebGL 可用（例如按上面配好启动参数），会自动改回真实地图，无需改任何配置。
+
 ## License
 
 [MIT](./LICENSE)