H5多媒体采集与地理定位：摄像头、权限与坐标偏移

做 H5 这些年，真正让我头疼的从来不是写页面、调布局，而是两个看起来"照着文档抄就能跑"的 API：一个叫getUserMedia，一个叫getCurrentPosition。前者管多媒体采集，后者管地理定位，文档上都是几行示例代码，可真放到线上，iOS 白屏、安卓没声音、权限弹不出来、定位永远转圈、坐标丢到地图上偏出几百米——这些坑几乎每个做 H5 多媒体和地理定位的人都踩过一遍。我这几年在活动页、打卡小程序内嵌页、门店巡检系统里反复用到这两套能力，攒下了不少"文档里不会写"的经验：比如为什么toDataURL会卡死主线程、为什么facingMode在桌面端完全失效、为什么明明授权了定位拿到的却是上一次的旧坐标。

这篇内容围绕 H5 多媒体采集与地理定位这两条主线展开，从技术路线选型、摄像头采集的完整链路、定位失败的四类真实原因，到把它们拼成一个"带地理标签的照片采集"完整案例，最后再说说被嵌进 App 和微信里才会遇到的那些怪问题。适合已经能写页面、想把这些能力真正落地到线上业务的同学，也适合正在被某个"玄学 bug"卡住的同行对照排查。下面的每一段都尽量给到可直接抄的代码和参数，以及我实测下来的数据。

1. H5 多媒体的四条技术路线，选错了后面全是坑

很多人一接到"页面上要能拍照/录像/放视频"的需求，第一反应就是搜一段getUserMedia的示例贴进去。结果发现需求其实就是"播放一个已经录好的宣传片"，白白引入了一堆权限问题。H5 里处理多媒体，至少有四条完全不同的路线，它们的输入源、输出形态和限制都不一样，选路线比写代码重要得多。

1.1<video>/<audio>标签：只管播放，别指望它采集

<video src="xxx.mp4" controls>这种写法解决的是"播放已有媒体"的问题，本身不具备任何采集能力。它的核心难点不在标签，而在编码格式和自动播放策略。格式上，mp4（H.264 + AAC）是兼容性最稳的组合，安卓和 iOS 原生都吃；webm（VP8/VP9）在桌面 Chrome 上好用，但 iOS Safari 长期支持不佳，我实测 iOS 16 之后部分机型才开始支持 VP8 解码，所以做通用业务别赌webm。

自动播放是另一个高频坑。Chrome 的政策是：没有用户手势触发的带声音播放会被拦截，控制台报NotAllowedError: play() failed because the user didn't interact with the document first。绕过办法只有两个——要么静音（muted属性）后自动播放，要么等一个真实的点击/触摸事件再调play()。我一般会写一个"点击开启声音"的浮层，既不违反策略，用户感知也自然。另外play()返回的是 Promise，一定要.catch()，否则被拦截时会抛出未捕获异常，整个页面的错误监控会被刷屏。

提示：iOS 上<video>进入全屏是由系统接管的，你没法自定义控制条。要做自定义播放器（比如带弹幕、带进度预览），得用playsinline+webkit-playsinline让它内联播放，再自己画控制条。

1.2getUserMedia+MediaStream：拿到的是"流"，不是"文件"

navigator.mediaDevices.getUserMedia({ video: true, audio: true })返回的是一个MediaStream对象，里面装着若干条MediaStreamTrack（一条视频轨、一条音频轨）。这里有个新手最容易搞混的点：流是实时的，它没有"长度"也没有"文件"的概念。你不能把MediaStream直接塞进FormData上传，也不能给它算大小。

流可以直接赋给<video>的srcObject做本地预览，这也是"边拍边看"的实现方式。它的硬性前提是安全上下文：必须是https://或者localhost，用http://打开时navigator.mediaDevices直接是undefined，连报错都很隐晦——很多同学在局域网 IP 上用http://192.168.x.x调试，然后疑惑为什么代码"没反应"，问题就出在这。

流还必须手动释放。getUserMedia成功之后，摄像头指示灯会一直亮，直到你调用track.stop()。如果用户拍完照直接切路由，你没停流，手机上会出现"指示灯长亮 + 发热 + 耗电"三连，这个体验问题在真机上非常明显，模拟器上根本看不出来。

1.3Canvas+MediaRecorder：把流变成能上传的东西

想把流变成文件，有两条子路线。第一种是截图：把<video>当前帧画到<canvas>上，再导出成图片。这是"拍照"最常用的做法。第二种是录制：用MediaRecorder把流编码成一段一段的Blob，最后拼成一个完整文件，这是"录像"的做法。

MediaRecorder的兼容性要特别注意mimeType。桌面 Chrome 支持video/webm;codecs=vp8，Safari 从 14.1 开始支持video/mp4，但支持列表因版本而异。稳妥的写法是用MediaRecorder.isTypeSupported()逐个探测，代码如下：

function pickMimeType() { const candidates = [ 'video/mp4;codecs=h264', 'video/webm;codecs=vp8', 'video/webm', ]; for (const type of candidates) { if (window.MediaRecorder && MediaRecorder.isTypeSupported(type)) { return type; } } return ''; // 交给浏览器自己决定 } const mimeType = pickMimeType(); const recorder = new MediaRecorder(stream, mimeType ? { mimeType } : undefined); const chunks = []; recorder.ondataavailable = (e) => { if (e.data && e.data.size > 0) chunks.push(e.data); }; recorder.onstop = () => { const blob = new Blob(chunks, { type: mimeType || 'video/webm' }); // blob 就可以上传了 }; recorder.start(1000); // 每 1 秒切一个分片，避免长视频把内存吃满

recorder.start(1000)这个参数很关键。不传的话所有数据会在stop()时一次性产出，录 3 分钟可能占用上百 MB 内存；传了时间片之后是流式产出，内存平稳得多。

1.4 还有一条被低估的路线：<input type="file" capture>

很多场景其实根本不需要getUserMedia。如果你只是想要"用户拍一张照片然后上传"，最省事的写法是：

<input type="file" accept="image/*" capture="environment">

这行代码在移动端会直接唤起系统相机，拍完返回一个File对象，连权限、流、Canvas 都不用管。它的代价是交互完全不可控——没有自定义取景框、没有实时滤镜、不能连拍。所以我的选型原则是：

一句话总结：要自定义交互就走getUserMedia，只要结果就走input capture，只要播放就用<video>。选错路线，后面写多少兼容代码都是在给自己找麻烦。

2. 摄像头采集的完整链路：从权限弹窗到可上传的 Blob

路线定了，真正开始写采集代码，细节比想象中多。我把它拆成四步：前置检查、约束配置、采帧压缩、资源释放。每一步都有各自的坑，下面按顺序说。

2.1 前置检查：在调 API 之前先把不可能的情况排掉

不要上来就调getUserMedia，先做三项检查，能省掉一大半的"莫名其妙的失败"：

async function preflight() { if (!window.isSecureContext) { throw new Error('当前页面不是安全上下文，请使用 HTTPS 访问'); } if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) { throw new Error('当前浏览器不支持媒体采集'); } // 权限查询不是所有浏览器都支持，要做存在性判断 if (navigator.permissions && navigator.permissions.query) { try { const status = await navigator.permissions.query({ name: 'camera' }); if (status.state === 'denied') { throw new Error('摄像头权限已被拒绝，请到浏览器设置中开启'); } } catch (e) { // Safari 早期版本对 name: 'camera' 会抛错，忽略即可 } } }

这里有个非常重要的认知：权限被拒绝之后，你没法用代码再次弹窗。浏览器只允许用户在设置里手动恢复，或者清空站点数据。所以一旦检测到denied，正确做法是给用户一段明确的图文指引（"点击地址栏左侧的锁形图标 → 站点设置 → 摄像头 → 允许"），而不是反复重试调用。我见过有页面在denied后循环调用getUserMedia，结果只是不断触发错误回调，什么也改变不了。

另外enumerateDevices()有个反直觉的行为：在用户授权之前，返回的设备列表里label是空字符串。所以做"选择摄像头"下拉框时，必须等第一次授权成功后再去枚举，否则你拿到一堆空名字，用户根本分不清哪个是前置哪个是后置。

2.2 约束配置：ideal和exact差一个字，结果天差地别

getUserMedia的约束对象是最容易写错的地方。先看一段常见写法：

const stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: { ideal: 'environment' }, width: { ideal: 1280 }, height: { ideal: 720 }, }, audio: false, });

关键在ideal和exact的取舍。ideal表示"尽量满足，满足不了就用最接近的"，不会报错；exact表示"必须满足，满足不了直接抛OverconstrainedError"。我强烈建议只在极少数必须精确的场景用exact，比如活体检测要求固定分辨率做像素比对。日常业务一律用ideal，否则用户换一台老设备就白屏，你连日志都难定位。

facingMode也有个反直觉的点：桌面端会直接忽略它。你在笔记本上请求environment，拿到的还是那颗前置摄像头。所以做多摄像头切换时，不能只依赖facingMode，更可靠的做法是先enumerateDevices()拿到deviceId列表，再用deviceId: { exact: id }精确指定。

分辨率的坑同样值得说。你请求 1280×720，浏览器不一定给你这个值——它可能给 640×480，也可能给 1920×1080。拿到流之后一定要读实际的track.getSettings()，而不是假设你请求什么就得到什么：

const track = stream.getVideoTracks()[0]; const settings = track.getSettings(); console.log(settings.width, settings.height, settings.frameRate);

我吃过一次亏：页面按 1280×720 的假设去算预览区宽高比，结果在一台安卓机上实际拿到 640×480（4:3），画面被拉变形。后来改成用settings动态算宽高比，问题就没了。

2.3 采帧、压缩与方向修正

采帧本身很简单，把<video>画到<canvas>即可。但有几个细节决定了成片质量：

function captureFrame(video, maxWidth = 1280, quality = 0.8) { const vw = video.videoWidth; const vh = video.videoHeight; const scale = Math.min(1, maxWidth / vw); const w = Math.round(vw * scale); const h = Math.round(vh * scale); const canvas = document.createElement('canvas'); canvas.width = w; canvas.height = h; const ctx = canvas.getContext('2d'); // 前置摄像头预览是镜像的，但拍出来的照片不应该镜像，这里要判断 ctx.drawImage(video, 0, 0, w, h); return new Promise((resolve) => { canvas.toBlob((blob) => resolve(blob), 'image/jpeg', quality); }); }

两处值得展开。第一，toBlob优先于toDataURL。toDataURL是同步的，会阻塞主线程，而且返回的 base64 字符串体积比原始二进制大约 33%，一张图就多出几百 KB 的内存占用；toBlob是异步的，直接产出二进制，上传时也更省事。我实测过一张 1280×960 的图，toDataURL在主线程上要卡 60~90ms，连续拍几张就能感觉到明显掉帧，换成toBlob之后基本无感。

第二，镜像问题。用前置摄像头自拍时，预览画面通常是镜像的（像照镜子），但很多业务希望存下来的照片是"正常方向"。是否镜像取决于你的产品需求，但一定要在两个地方保持一致，否则会出现"预览正常、拍出来反了"的诡异现象。处理方法就是在drawImage前加一次ctx.translate(w, 0); ctx.scale(-1, 1);。

再一个容易被忽略的是EXIF 方向。getUserMedia采到的帧一般已经是纠正过的方向，但通过<input type="file" capture>拿到的照片很可能带 EXIF Orientation 标记——iPhone 竖着拍的照片，像素数据其实是横的，靠 EXIF 里的一个字段告诉查看器"转 90 度"。如果你直接把它画到 Canvas 上，就会得到一张躺着的图。完整处理要读取 EXIF 并做相应旋转，代码量不小，实践中要么用现成的图像处理库，要么在服务端统一纠正。我的经验是：如果前端已经用 Canvas 重绘过一遍，EXIF 就丢了，必须自己先读再转，这一步漏掉，安卓部分机型和 iOS 都会出现方向错乱。

压缩质量怎么定？我给一个实测参考：一张手机原图 4032×3024、约 3.2MB，缩到长边 1280、JPEG 质量 0.8，输出约 180KB；质量降到 0.6 约 110KB，肉眼在手机上几乎看不出差别。长边 1280 + 质量 0.75~0.8 是我最常用的组合，兼顾清晰度和流量。

顺带提一句"拖动调节参数"这类需求（热词里的h5 拖动调节参数）。如果产品想让用户自己调压缩质量或亮度，用<input type="range">就够了，记得加input事件做实时预览，但不要在拖动过程中反复toBlob重编码，那会卡到怀疑人生。我的做法是预览阶段用 CSS 滤镜（filter: brightness()）做即时反馈，等用户松手（change事件）再做一次真正的重编码。

2.4 资源释放：不做这一步，用户的手机会发烫

流用完必须停。完整的释放逻辑要覆盖三个时机：拍摄结束、页面切到后台、组件卸载。

function stopStream(stream) { if (!stream) return; stream.getTracks().forEach((track) => track.stop()); } // 页面可见性变化时暂停，回到前台再恢复（看需求） document.addEventListener('visibilitychange', () => { if (document.hidden) { stopStream(currentStream); currentStream = null; } });

iOS 上还有个特殊情况：页面进入后台时，video会冻结，videoWidth可能变成 0，此时如果采帧会得到一张全黑图。所以采帧前一定要判断video.videoWidth > 0和video.readyState >= 2，做好防御。

3. 地理定位：getCurrentPosition的四类失败，每一类原因都不同

地理定位的 API 表面上比采集简单得多，就一个navigator.geolocation.getCurrentPosition(success, error, options)。但它的失败率高得惊人，我第一次做门店打卡功能时，线上成功率只有七成出头，剩下的三成全卡在错误回调里。把错误码搞清楚之后，成功率和体验都能明显改善。

3.1getCurrentPosition和watchPosition：一次定位 vs 持续跟踪

getCurrentPosition是"要一个当前位置"，watchPosition是"持续返回位置变化"。这两个的选择很直白：签到打卡、开屏定位用前者；轨迹记录、导航用后者。

但watchPosition有个必须注意的地方——它返回一个watchId，你不用了一定要clearWatch(watchId)，否则回调会一直执行，后台疯狂耗电。这在 SPA 里尤其容易漏，路由切走了监听还在跑。我一般会在组件卸载或路由离开的钩子里统一清理。

另外watchPosition的回调频率是浏览器自己决定的，你控制不了。它在移动中可能几秒一次，静止时可能几十秒才一次，别指望用它做高频采样。

3.2 坐标系那点事：为什么坐标丢到地图上偏了几百米

这是最容易被忽略、也最让人抓狂的问题。getCurrentPosition返回的经纬度是WGS84坐标系，而国内各家地图服务大多使用自己的一套坐标系（常见的是在 WGS84 基础上做过偏移处理的版本）。这两套坐标不能直接混用，直接叠加会产生几百米的偏差——在城里可能就是"马路对面"和"两个街区之外"的区别。

处理方式有三种，按推荐度排序：

1. 直接用地图厂商自己的定位 SDK。如果页面上本来就要显示地图，用厂商提供的 Web 定位能力，拿到的坐标就是和它的底图匹配的，不需要转换。这是最省心的做法。
2. 调用厂商的坐标转换服务。多数地图开放平台都提供了坐标转换接口，传入 WGS84 返回目标坐标。
3. 使用成熟的坐标转换库。转换算法本身是公开的，社区有现成实现，但精度受算法版本影响，且各地偏移量并非完全均匀，用于展示可以，用于精确的围栏判定要谨慎验证。

我做围栏判定（比如判断用户是否在门店 100 米内）的经验是：别直接把两套坐标混算距离。要么统一到同一坐标系再算，要么干脆用地图厂商的 SDK 去做"点到围栏"的判断。曾经有个项目因为坐标没统一，围栏半径设成 300 米还是有一半人判定失败，排查了半天才发现是坐标系问题。

3.3 精度参数与超时策略：enableHighAccuracy不是越高越好

options里三个参数值得展开说：

• enableHighAccuracy：设为true时，浏览器会优先尝试 GPS 等高精度来源。代价是首次定位更慢、更耗电，在室内可能直接超时。
• timeout：等待定位结果的最长毫秒数，默认是Infinity，也就是"一直等"。这个默认值绝对不能用，用户会看到永远转圈的加载动画。我一般设 8000~10000ms。
• maximumAge：接受多久之内的缓存结果。设 0 表示强制取新位置，设一个较大值（如 60000）则允许返回一分钟内的缓存。

我的常用配置是这样：

navigator.geolocation.getCurrentPosition( (pos) => { const { latitude, longitude, accuracy } = pos.coords; // accuracy 是精度半径（米），一定要用上 console.log(latitude, longitude, `精度约 ${accuracy} 米`); }, (err) => { switch (err.code) { case 1: console.warn('用户拒绝了定位权限'); break; case 2: console.warn('位置不可用，可能是信号问题'); break; case 3: console.warn('定位超时'); break; } }, { enableHighAccuracy: true, timeout: 10000, maximumAge: 0 } );

这里有个很有用的字段容易被忽略：coords.accuracy，它表示定位结果的精度半径，单位是米。室内靠 WiFi 定位时这个值可能是 50~500，室外开着 GPS 可能是 5~20。做围栏判定时，如果 accuracy 大于围栏半径，这次定位结果就没有参考价值，应该提示用户走到开阔处重试，而不是硬判。这个细节能挡掉一大批"明明人在店里却判失败"的客诉。

还有一个坑是"旧坐标"。安卓部分浏览器在maximumAge设置不当，或者系统刚重启定位服务时，会直接返回上一次的位置。表现是"用户人都到新地方了，定位还是旧地址"。用一个时间戳字段（pos.timestamp）对比当前时间，超过阈值就提示用户刷新，能规避这个情况。

3.4 降级方案：拿不到精确位置时该怎么办

定位失败不该直接给用户一个红叉。我的降级链路是这样的：

注意 IP 定位只能精确到城市级别，而且它是在服务端做的，前端拿不到。所以前端要做的其实是"给用户一个能选点或输入地址的入口"，把定位当成锦上添花，而不是唯一路径。

还有一个现实问题：HTTP 页面下navigator.geolocation是直接报错的，错误码 1，表现和"用户拒绝"一模一样。所以排查"为什么所有人都定位失败"时，第一个要确认的就是页面是不是 HTTPS。

4. 一个完整案例：带地理标签的照片采集页

把多媒体和定位拼起来，就是一个很典型的业务形态——巡检、打卡、报修这类场景，用户拍一张现场照片，自动带上拍摄地点的坐标。我把这个案例的完整设计过一遍，包括状态机、核心代码和实测数据。

4.1 先画状态机，再写代码

这类页面最容易写乱的地方是状态管理：摄像头在申请、定位在转圈、图片在压缩、上传在重试，状态互相交叉，稍不注意就出现"权限弹窗还没关，页面已经开始采帧了"这种竞态。我习惯先把状态列清楚：

idle → requestingPermission（申请摄像头权限） → previewing（预览中，可拍摄） → capturing（采帧） → compressing（压缩编码） → locating（获取定位，可与压缩并行） → uploading（上传） → done / failed

关键设计是把定位和压缩并行。定位可能要等 5~10 秒，压缩通常只要 100~300ms，两者没有依赖关系，串行的话用户要多等好几秒。我的做法是点击拍摄时同时发起定位请求，等图片压缩完再看定位是否返回，超时就先上传图片、坐标标记为"待补"，后续再补传。

4.2 核心代码：采集、压缩、打标签、上传

先看整体流程的骨架：

async function handleCapture() { setState('capturing'); const locPromise = getLocationSafe(); // 不阻塞，先发出去 const blob = await captureFrame(videoEl, 1280, 0.8); setState('compressing'); const geo = await locPromise; // 等定位，内部自带超时降级 setState('uploading'); const form = new FormData(); form.append('photo', blob, `photo_${Date.now()}.jpg`); form.append('lat', geo.lat ?? ''); form.append('lng', geo.lng ?? ''); form.append('accuracy', geo.accuracy ?? ''); form.append('capturedAt', String(Date.now())); await uploadWithRetry('/api/upload', form, 3); setState('done'); }

定位的封装要自带降级和超时，不能让业务层去处理错误码：

function getLocationSafe() { return new Promise((resolve) => { if (!navigator.geolocation || !window.isSecureContext) { return resolve({}); } const timer = setTimeout(() => resolve({}), 9000); // 兜底超时 navigator.geolocation.getCurrentPosition( (pos) => { clearTimeout(timer); resolve({ lat: pos.coords.latitude, lng: pos.coords.longitude, accuracy: Math.round(pos.coords.accuracy), }); }, () => { clearTimeout(timer); resolve({}); // 失败也返回空对象，不阻塞上传 }, { enableHighAccuracy: true, timeout: 8000, maximumAge: 0 } ); }); }

注意getLocationSafe在失败时 resolve 的是空对象，而不是 reject。定位失败不应该阻断上传——照片本身的业务价值远大于坐标，把坐标当成可选字段，用户体验会好很多。

上传重试也要注意策略。我的做法是指数退避 + 次数上限：

async function uploadWithRetry(url, form, retries) { for (let i = 0; i <= retries; i++) { try { const res = await fetch(url, { method: 'POST', body: form }); if (res.ok) return res.json(); if (res.status >= 400 && res.status < 500) { throw new Error(`客户端错误 ${res.status}，不重试`); } } catch (e) { if (i === retries) throw e; } await new Promise((r) => setTimeout(r, Math.pow(2, i) * 500)); } }

这里有个细节：4xx 错误不要重试，因为请求本身就是错的（参数缺失、鉴权失败），重试一百次也没用，只会浪费用户流量。只有网络错误和 5xx 才值得重试。

4.3 上传接口的安全边界

前端校验永远不可信。这一点我想单独强调，因为很多团队的"加固"都停留在前端：用 JS 判断文件大小、判断文件类型、限制上传频率，看起来很周全，但只要有人绕过页面直接调接口，这些统统失效。

服务端至少要做四件事：

• 核对Content-Type和文件头魔数，不能只信请求里的type字段。
• 限制单文件和总请求体大小，在网关层就拦掉超大请求，别等到进了应用层才发现。
• 限制上传频率，同一用户/IP 每分钟的次数要有上限。
• 鉴权信息不要放在 URL 里。放在 query 上的 token 会进浏览器历史、进各级日志、进 Referer 头，很容易泄露。用请求头或者表单字段。

还有一条：不要在前端代码里写任何服务端的密钥。H5 的代码是完全公开的，打包压缩也只是增加阅读成本，不构成任何保护。所有敏感操作必须走你自己的服务端中转，让服务端去做签名和校验。

4.4 实测数据与几个观察

我把这套方案在一台中端安卓机和一台 iPhone 上跑了一遍，记录一些有参考价值的数字：

两个比较深的体会：一是定位的耗时远超预期，把它放在关键路径上会让用户等得不耐烦，所以并行化 + 超时降级几乎是必需的；二是室内定位精度差得离谱，门店类场景如果强依赖坐标判定，一定要结合 WiFi、扫码或者其他辅助手段，单靠定位做不了精确核验。

5. H5 被嵌进 App 和微信之后，问题才真正开始

前面说的都是"在浏览器里打开"的情况。但现实是，绝大多数 H5 是跑在 App 的 WebView 或者微信里的，这时候你会发现同一份代码，在浏览器里好好的，在 WebView 里就出各种问题。这一节讲的都是只有内嵌环境才会遇到的坑。

5.1 摄像头权限是宿主的，不是你页面的

这是最反直觉的一点。在移动端 WebView 里，页面调getUserMedia时弹出的"是否允许"对话框，不是浏览器的，而是宿主 App 的。也就是说，能不能用摄像头，取决于宿主 App 有没有在原生层处理权限请求。

• 安卓 WebView：需要在宿主侧重写WebChromeClient.onPermissionRequest()，在里面调用系统的权限申请，再把结果回调给request.grant()或request.deny()。如果宿主没做这一步，页面里getUserMedia会直接挂起或失败，你在 H5 里怎么调都没用。
• iOS WKWebView：需要在Info.plist里声明相机和麦克风的使用说明，同时在原生层实现WKUIDelegate的相关回调来授予权限。缺任何一项，页面都拿不到设备。

所以一旦发现"内嵌页面的拍照功能完全用不了"，别急着改前端，先确认宿主 App 有没有做原生侧的支持。这个结论能省下大量无效排查时间。同样的道理，定位权限也是宿主的，iOS 上还要在Info.plist里配好定位用途说明。

5.2 WebView 缓存：为什么改完代码页面没变

"我明明发了新版本，用户看到的还是旧页面"——这个问题的根源在 WebView 的缓存机制。WebView 默认会缓存静态资源，尤其在一些 App 里，缓存的激进程度比浏览器高得多，Cache-Control都可能被忽略。

我的处理办法是给资源加版本指纹：

• HTML 入口文件设置Cache-Control: no-cache，每次都要向服务端确认。
• JS / CSS 文件名带上构建哈希，比如app.3f8a2c.js。内容变了文件名就变，天然绕过缓存。
• 如果做不到文件名哈希，退而求其次在 URL 后加版本号：app.js?v=20240601，发布时更新这个号。

还有一种情况是本地存储残留。如果版本升级改了数据结构，而localStorage里还是旧格式，页面就可能报错或者显示错乱。稳妥的做法是在应用启动时校验一个版本号字段，不匹配就清空相关存储并重新初始化。

至于"用户手动清缓存"，这个入口在 WebView 里通常是没有的。所以必须是你的代码保证缓存可控，不能指望用户在 App 设置里找到清理按钮。有些 App 提供了"清除缓存"的功能，但它往往只清文件缓存，localStorage和IndexedDB未必会一起清，这个细节不同 App 差异很大，做兼容时要测试确认。

5.3 从 H5 跳回 App：scheme 唤起和它的失败场景

内嵌页里经常有"打开 App 查看更多"的需求，实现方式是自定义 scheme：location.href = 'myapp://page/detail?id=123'。这里的坑集中在失败检测上——如果用户没装 App，这次跳转不会报错，只会静默失败，页面看起来像是"卡住了"。

标准的兜底套路是这样的：

function openApp(scheme, fallbackUrl) { const start = Date.now(); const timer = setTimeout(() => { // 800ms 后如果页面还在，说明大概率没唤起成功 if (Date.now() - start < 2200) { location.href = fallbackUrl; // 跳到下载页或网页版 } }, 800); location.href = scheme; }

判断逻辑是：如果 App 成功唤起，页面会切到后台，visibilitychange或定时器会被挂起，所以"页面还在"意味着唤起失败。这个方案不完美，但足够覆盖大多数情况。

更要命的是在别人的 App 里（尤其是微信）自定义 scheme 往往被拦截。这种情况下唯一可靠的路径是走一个中间页（有的平台叫"跳转引导页"），由它触发唤起或者引导用户在浏览器打开。在微信内直接唤起自己的 App 基本行不通，需要提前设计好降级路径，别等到上线才发现。

5.4 图片压缩该放前端还是后端

"H5 有没有前端压缩图片的方式"这个问题我被问过很多次，答案是有的，就是上一节说的 Canvas 重绘，但要不要在前端压，得看情况权衡。

我的选择原则是：上限阈值放前端，质量底线放后端。前端把超过 4MB 的图压到 1MB 以内再传，避免用户浪费流量、避免上传超时；后端收到后再做一次统一处理，保证最终质量可控。这样两边的优势都拿到了。

还有一点要注意：前端的压缩结果不可信。用户可以伪造请求上传任意文件，所以后端必须重新校验文件类型和大小，不能因为"前端已经压过了"就跳过检查。这一点在上一节的安全边界里已经说过，但在压缩场景下更容易被忽略。

6. 排查对照表：把大段猜测变成逐项核对

多媒体和定位的问题有个共同特点：错误信息都很模糊，getUserMedia失败往往只有一个NotAllowedError，定位失败只有三个错误码。这时候靠猜是低效的，我整理了一张对照表，出问题时从上往下核对，基本能定位到八成的情况。

这张表我自己用了很久，实际操作时还有一个技巧：先在浏览器里复现，再进 WebView 验证。如果浏览器里正常、WebView 里异常，那问题百分之百在宿主环境（权限、缓存、内核版本），不用再折腾前端代码；如果两边都异常，那就是代码层面的问题，按表逐项排查。这个二分法能省掉大量时间。

还有一个排查习惯值得养成：在页面上放一个隐藏的调试面板（连续点击版本号五次之类的触发方式），实时显示isSecureContext、mediaDevices是否存在、permissions状态、videoWidth/readyState、定位错误码和 accuracy。真机上出了问题，让用户截个图就能定位，比让他描述现象准确得多。这套东西我几乎每个采集类项目都会预埋，后期维护成本能降一大截。

最后分享一个我在实际项目里踩出来的体会：多媒体和定位这两块能力，真正难的不是"跑通"，而是"跑稳"。跑通只需要一个下午，跑稳需要把权限、超时、降级、释放、缓存、坐标系这些边角全部考虑进去。我现在的习惯是，在写完主流程之后，专门留出时间把异常路径走一遍——拒绝权限、无网络、切后台、切设备、弱信号，这几条路径走顺了，线上问题会少很多。至于坐标精度和压缩质量的默认值，我的建议是别拍脑袋定，拿真机在真实场景里测几组数据再定，这和看文档猜出来的数字往往差很远。