本文详解在 Chrome 等现代浏览器中使用 navigator.wakeLock 时，为何调用 wakeLock.release() 报错“is not a function”，并提供完整、健壮的请求与释放流程，涵盖 Promise 处理、错误防护及兼容性检查。
本文详解在 chrome 等现代浏览器中使用 `navigator.wakelock` 时，为何调用 `wakelock.release()` 报错“is not a function”，并提供完整、健壮的请求与释放流程，涵盖 promise 处理、错误防护及兼容性检查。
Web Wake Lock API 允许网页在用户离开页面或设备进入空闲状态时，保持屏幕常亮（如视频播放、演示文稿、数据采集等场景）。但其设计遵循异步原则：navigator.wakeLock.request('screen') 返回的是一个 Promise，而非直接的 WakeLock 实例。因此，若未正确 await 或链式处理该 Promise，就尝试调用 .release()，便会报错 wakeLock.release is not a function——因为此时 wakeLock 变量实际保存的是一个 Promise 对象，而 Promise 并无 release 方法。
✅ 正确做法是：确保 wakeLock 变量始终引用已解析的 WakeLock 实例（即 Promise resolve 后的对象），再调用其 release() 方法。
以下是推荐的生产级实现：
// 1. 兼容性检查（必需）
if (!('wakeLock' in navigator)) {
console.warn('Wake Lock API not supported.');
return;
}
let wakeLock = null;
// 2. 请求唤醒锁（返回 Promise，需 await）
async function requestWakeLock() {
try {
wakeLock = await navigator.wakeLock.request('screen');
console.log('Wake lock acquired.');
// 可选：监听释放事件（例如被系统强制释放）
wakeLock.addEventListener('release', () => {
console.log('Wake lock was released.');
wakeLock = null;
});
return wakeLock;
} catch (err) {
console.error('Failed to acquire wake lock:', err.name, err.message);
wakeLock = null;
}
}
// 3. 安全释放唤醒锁
async function releaseWakeLock() {
if (!wakeLock) return;
try {
await wakeLock.release(); // release() 返回 Promise，建议 await
console.log('Wake lock released.');
wakeLock = null;
} catch (err) {
console.warn('Failed to release wake lock:', err.name, err.message);
// 释放失败通常不影响后续逻辑，可忽略或记录
}
}
// ✅ 使用示例：
// 请求锁（建议在用户交互后触发，如按钮点击）
document.getElementById('lockBtn').addEventListener('click', () => {
requestWakeLock();
});
// 释放锁（例如页面隐藏、用户点击“停止”按钮）
document.getElementById('unlockBtn').addEventListener('click', () => {
releaseWakeLock();
});
// 可选：页面可见性变化时自动管理（提升体验）
document.addEventListener('visibilitychange', () => {
if (document.hidden && wakeLock) {
releaseWakeLock();
}
});
⚠️ 关键注意事项：
- 不要直接对 Promise 调用 .release()：set_wakelock() 若未 await 就赋值给变量，得到的是 Promise，而非 WakeLock 实例；
- release() 是异步方法：它返回 Promise，应 await 或 .then() 处理，避免竞态问题；
- 必须进行运行时检测：navigator.wakeLock 仅在安全上下文（HTTPS 或 localhost）且支持该 API 的浏览器中存在；
- 遵循用户意图与权限原则：Wake Lock 应在明确用户操作（如点击）后请求，并在任务结束或页面不可见时及时释放，避免耗电与干扰用户体验；
- 错误处理不可省略：系统可能因电源策略、OS 限制或用户手动关闭而拒绝请求或提前释放锁，务必捕获 NotAllowedError、PermissionDeniedError 等异常。
通过以上结构化封装，你不仅能规避 release is not a function 错误，还能构建稳定、可维护、符合 Web 标准的唤醒锁管理逻辑。
