html5-qrcode错误码速查：从PERMISSION_DENIED到NOT_SUPPORTED
项目地址: https://gitcode.com/gh_mirrors/ht/html5-qrcode 前言：QR码扫描开发的痛点与解决方案
你是否在开发QR码扫描功能时遇到过PERMISSION_DENIED却不知如何引导用户授权？是否因NOT_SUPPORTED错误而陷入浏览器兼容性的困境？本文系统整理了html5-qrcode库的所有错误码，提供错误成因分析、解决方案及实战代码示例，帮助开发者快速定位并解决95%的扫描异常问题。
读完本文你将获得：
- 12种核心错误码的详细诊断指南
- 浏览器权限请求的最佳实践代码
- 跨设备兼容性处理方案
- 错误监控与用户反馈机制实现
错误码体系总览
html5-qrcode的错误处理机制基于分层设计，覆盖从设备访问到解码逻辑的全流程：
核心错误码详解
1. PERMISSION_DENIED（权限拒绝）
错误场景：用户拒绝摄像头访问请求时触发
错误码常量：Html5QrcodeError.PERMISSION_DENIED
解决方案：实现权限请求引导流程
// 权限请求与错误处理最佳实践
const html5Qrcode = new Html5Qrcode("reader");
async function startScanner() {
try {
const permissionGranted = await Html5Qrcode.getCameras();
if (permissionGranted.length === 0) {
throw new Error("CAMERA_NOT_FOUND");
}
await html5Qrcode.start(
{ facingMode: "environment" },
{
fps: 10,
qrbox: { width: 250, height: 250 }
},
(decodedText) => {},
(errorMessage) => {
if (errorMessage.includes("PERMISSION_DENIED")) {
showPermissionGuide(); // 显示权限引导UI
}
}
);
} catch (err) {
handleScannerError(err);
}
}
// 权限引导UI实现
function showPermissionGuide() {
const guideHtml = `
<div class="permission-guide">
<h3>需要摄像头权限</h3>
<p>请在浏览器设置中允许摄像头访问，以便进行QR码扫描</p>
<button onclick="openPermissionSettings()">打开设置</button>
</div>
`;
document.body.insertAdjacentHTML('beforeend', guideHtml);
}
浏览器差异：
- Chrome: 首次拒绝后需手动在地址栏🔒图标中重置权限
- Safari: 仅在HTTPS环境下可请求摄像头权限
- Firefox: 支持
navigator.permissions.query预检查
2. NOT_SUPPORTED（不支持）
错误场景：浏览器不支持MediaDevices API或Canvas API时触发
错误码常量：Html5QrcodeError.NOT_SUPPORTED
兼容性矩阵：
| 浏览器 | 最低支持版本 | 限制条件 |
|---|---|---|
| Chrome | 51+ | 需HTTPS环境 |
| Firefox | 38+ | 部分移动设备需要用户交互触发 |
| Safari | 11+ | iOS需11.2+版本 |
| Edge | 15+ | 与Chrome行为一致 |
| IE | 不支持 | 无替代方案 |
降级处理实现：
// 浏览器兼容性检测与降级方案
function checkBrowserSupport() {
const supportStatus = {
mediaDevices: !!navigator.mediaDevices?.getUserMedia,
canvas: !!window.CanvasRenderingContext2D,
url: !!window.URL?.createObjectURL
};
if (!supportStatus.mediaDevices) {
return {
supported: false,
error: "NOT_SUPPORTED_MEDIA_DEVICES",
fallback: "FILE_BASED_SCAN"
};
}
return { supported: true };
}
// 文件上传降级方案
function initFileBasedScan() {
const fileInput = document.createElement("input");
fileInput.type = "file";
fileInput.accept = "image/*";
fileInput.onchange = (e) => {
const file = e.target.files[0];
html5Qrcode.scanFile(file, true)
.then(decodedText => {
handleDecodedResult(decodedText);
})
.catch(err => {
showError(`文件扫描失败: ${err.message}`);
});
};
document.getElementById("reader").appendChild(fileInput);
}
3. CAMERA_NOT_FOUND（未找到摄像头）
错误场景：设备无可用摄像头或所有摄像头均被占用
错误码常量：Html5QrcodeError.CAMERA_NOT_FOUND
排查流程：
实战代码：
// 高级摄像头检测逻辑
async function detectCamerasWithFallback() {
try {
const cameras = await Html5Qrcode.getCameras();
if (cameras.length === 0) {
// 尝试直接请求摄像头流（部分设备需要显式请求）
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
stream.getTracks().forEach(track => track.stop());
return [{ id: "default", label: "默认摄像头" }];
}
return cameras;
} catch (err) {
if (err.name === "NotFoundError") {
return [];
}
throw err;
}
}
媒体流错误码详解
4. STREAM_INIT_FAILED（流初始化失败）
错误场景：摄像头访问请求被操作系统阻止
常见原因：
- 设备摄像头正被其他应用占用
- 浏览器安全策略限制（如隐身模式）
- 硬件驱动问题
解决方案：实现多尝试机制
// 带重试机制的流初始化
async function initializeStreamWithRetry(config, maxRetries = 3) {
let retries = 0;
while (retries < maxRetries) {
try {
return await navigator.mediaDevices.getUserMedia(config);
} catch (err) {
retries++;
if (retries >= maxRetries) throw err;
// 指数退避重试
const delay = Math.pow(2, retries) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
// 最后一次尝试使用简化配置
if (retries === maxRetries - 1) {
config = { video: true }; // 移除高级配置
}
}
}
}
5. STREAM_CONFIG_ERROR（流配置错误）
错误场景：请求的摄像头参数超出设备能力
典型错误参数：
- 分辨率设置过高（如4K在低端设备）
- 帧率设置超过摄像头硬件限制
- 无效的facingMode（如移动设备请求"user"但无前置摄像头）
自适应配置实现：
// 摄像头能力检测与自适应配置
async function getOptimalCameraConfig() {
const cameras = await Html5Qrcode.getCameras();
if (cameras.length === 0) throw new Error("CAMERA_NOT_FOUND");
// 优先使用后置摄像头
const preferredCamera = cameras.find(cam =>
cam.label.toLowerCase().includes("back") ||
cam.label.toLowerCase().includes("environment")
) || cameras[0];
// 请求基础流以检测能力
const tempStream = await navigator.mediaDevices.getUserMedia({
video: { deviceId: preferredCamera.id }
});
const track = tempStream.getVideoTracks()[0];
const capabilities = track.getCapabilities();
// 根据设备能力调整配置
const optimalConfig = {
deviceId: preferredCamera.id,
width: { ideal: Math.min(capabilities.width.max, 1280) },
height: { ideal: Math.min(capabilities.height.max, 720) },
frameRate: { ideal: Math.min(capabilities.frameRate.max || 30, 15) }
};
track.stop();
return optimalConfig;
}
解码层错误码详解
6. DECODE_FAILED（解码失败）
错误场景：摄像头捕获的图像无法识别为QR码
错误码常量：Html5QrcodeError.DECODE_FAILED
优化方案：
// 解码成功率优化配置
const optimalDecoderConfig = {
fps: 10, // 降低帧率提高单帧处理质量
qrbox: { width: 250, height: 250 }, // 限制扫描区域
aspectRatio: 1.0, // 保持正方形视口
disableFlip: true, // 禁用图像翻转
inversionMode: "both", // 同时检测黑白/白黑QR码
supportedFormats: [
Html5QrcodeSupportedFormats.QR_CODE,
Html5QrcodeSupportedFormats.AZTEC
]
};
// 解码失败用户引导
function handleDecodeFailure(error) {
const errorCount = trackErrorOccurrence("DECODE_FAILED");
if (errorCount > 5) {
showGuidanceTips([
"请将QR码对准扫描框",
"确保光线充足",
"避免摄像头抖动",
"检查QR码是否完整"
]);
// 尝试调整扫描参数
html5Qrcode.updateConfig({
qrbox: { width: 300, height: 300 }, // 扩大扫描区域
brightness: getAutoBrightnessAdjustment()
});
}
}
7. INVALID_IMAGE_FORMAT（无效图像格式）
错误场景：文件扫描时传入非图像类型或损坏文件
错误码常量：Html5QrcodeError.INVALID_IMAGE_FORMAT
文件验证实现：
// 图像文件预验证
function validateImageFile(file) {
// 1. MIME类型检查
if (!file.type.startsWith("image/")) {
return { valid: false, error: "INVALID_IMAGE_FORMAT" };
}
// 2. 文件大小限制
const maxSizeMB = 5;
if (file.size > maxSizeMB * 1024 * 1024) {
return { valid: false, error: "FILE_TOO_LARGE" };
}
// 3. 扩展名检查
const validExtensions = [".jpg", ".jpeg", ".png", ".gif", ".webp"];
const fileExtension = file.name.split(".").pop().toLowerCase();
if (!validExtensions.includes(`.${fileExtension}`)) {
return { valid: false, error: "INVALID_EXTENSION" };
}
return { valid: true };
}
// 文件扫描流程
async function scanImageFile(file) {
const validation = validateImageFile(file);
if (!validation.valid) {
showUserError(validation.error);
return;
}
try {
// 创建图像对象验证完整性
const img = new Image();
img.src = URL.createObjectURL(file);
await new Promise((resolve, reject) => {
img.onload = resolve;
img.onerror = () => reject(new Error("INVALID_IMAGE_FORMAT"));
});
// 执行扫描
const result = await html5Qrcode.scanFile(file, true);
URL.revokeObjectURL(img.src);
return result;
} catch (err) {
handleScanError(err);
}
}
应用层错误码详解
8. SCAN_ALREADY_ACTIVE（扫描已激活）
错误场景：重复调用start()方法而未停止现有扫描
错误码常量：Html5QrcodeError.SCAN_ALREADY_ACTIVE
状态管理实现：
// 扫描器状态管理
class ScannerManager {
constructor(containerId) {
this.html5Qrcode = new Html5Qrcode(containerId);
this.isScanning = false;
this.scanHistory = [];
}
async start(config) {
if (this.isScanning) {
throw new Error("SCAN_ALREADY_ACTIVE");
}
try {
this.isScanning = true;
this.startTime = Date.now();
await this.html5Qrcode.start(
config.cameraId || { facingMode: "environment" },
config.scanConfig || optimalDecoderConfig,
(result) => this.handleSuccess(result),
(error) => this.handleError(error)
);
} catch (err) {
this.isScanning = false;
throw err;
}
}
async stop() {
if (!this.isScanning) return;
try {
await this.html5Qrcode.stop();
this.scanHistory.push({
startTime: this.startTime,
endTime: Date.now(),
duration: Date.now() - this.startTime
});
} finally {
this.isScanning = false;
}
}
// 确保扫描器正确销毁
async destroy() {
await this.stop();
this.html5Qrcode.clear();
}
}
9. INVALID_CONFIGURATION（无效配置）
错误场景：初始化扫描器时提供无效配置参数
错误码常量：Html5QrcodeError.INVALID_CONFIGURATION
配置验证实现：
// 配置验证器
function validateScannerConfig(config) {
const errors = [];
// 验证QR框尺寸
if (config.qrbox) {
if (typeof config.qrbox !== "object" || !config.qrbox.width || !config.qrbox.height) {
errors.push("qrbox必须是包含width和height的对象");
} else if (config.qrbox.width < 100 || config.qrbox.height < 100) {
errors.push("qrbox尺寸不能小于100px");
}
}
// 验证帧率
if (config.fps && (config.fps < 1 || config.fps > 30)) {
errors.push("fps必须在1-30范围内");
}
// 验证回调函数
if (typeof config.successCallback !== "function") {
errors.push("必须提供successCallback函数");
}
if (errors.length > 0) {
throw new Error(`INVALID_CONFIGURATION: ${errors.join("; ")}`);
}
return true;
}
// 安全的配置合并
function mergeConfig(userConfig) {
const defaultConfig = {
fps: 10,
qrbox: { width: 250, height: 250 },
aspectRatio: 1.0,
disableFlip: false
};
return { ...defaultConfig, ...userConfig };
}
错误监控与用户反馈机制
完整错误处理流程
错误上报与监控实现
// 错误监控系统集成
function initErrorMonitoring() {
// 全局错误收集
window.addEventListener("error", (event) => {
if (event.error.message.includes("Html5QrcodeError")) {
reportErrorToService({
type: "GLOBAL_ERROR",
message: event.error.message,
stack: event.error.stack,
timestamp: new Date().toISOString(),
context: getScannerContext()
});
}
});
// 性能指标收集
new PerformanceObserver((list) => {
const entries = list.getEntriesByName("qr-scan-duration");
entries.forEach(entry => {
reportPerformanceMetric({
metric: "scan_duration",
value: entry.duration,
sampleCount: entry.detail.sampleCount,
successRate: entry.detail.successRate
});
});
}).observe({ entryTypes: ["measure"] });
}
// 用户反馈收集
function initUserFeedback() {
const feedbackButton = document.createElement("button");
feedbackButton.className = "feedback-btn";
feedbackButton.innerHTML = "扫描遇到问题?";
feedbackButton.onclick = () => {
const feedbackText = prompt("请描述您遇到的问题:");
if (feedbackText) {
reportUserFeedback({
feedback: feedbackText,
errorContext: lastScanError,
deviceInfo: getDeviceInfo()
});
showToast("感谢您的反馈!");
}
};
document.getElementById("reader").appendChild(feedbackButton);
}
兼容性处理最佳实践
移动端特殊情况处理
// 移动设备适配代码
function adaptToMobileDevice() {
const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
if (!isMobile) return;
// 1. 屏幕旋转处理
window.addEventListener("orientationchange", () => {
if (scannerManager.isScanning) {
scannerManager.stop().then(() => {
// 调整UI方向后重启扫描
setTimeout(() => scannerManager.start(savedConfig), 500);
});
}
});
// 2. 触摸聚焦处理
document.getElementById("reader").addEventListener("touchstart", () => {
if (!scannerManager.isScanning) {
scannerManager.start(savedConfig);
}
});
// 3. 低电量模式检测
if (navigator.getBattery) {
navigator.getBattery().then(battery => {
if (battery.level < 0.2 && battery.charging === false) {
// 降低扫描性能以节省电量
savedConfig.scanConfig.fps = 5;
savedConfig.scanConfig.qrbox = { width: 200, height: 200 };
}
});
}
}
完整错误参考表
| 错误码 | 错误类型 | 可能原因 | 解决方案 |
|---|---|---|---|
| PERMISSION_DENIED | 权限错误 | 用户拒绝摄像头访问 | 显示权限引导UI，提供设置跳转链接 |
| NOT_SUPPORTED | 兼容性错误 | 浏览器不支持MediaDevices API | 降级为文件扫描模式，提示浏览器升级 |
| CAMERA_NOT_FOUND | 设备错误 | 无可用摄像头或被占用 | 检查设备连接，提示关闭占用应用 |
| STREAM_INIT_FAILED | 媒体流错误 | 摄像头被系统阻止 | 实现重试机制，最多3次尝试 |
| STREAM_CONFIG_ERROR | 配置错误 | 请求参数超出设备能力 | 动态调整分辨率和帧率 |
| DECODE_FAILED | 解码错误 | 图像质量差或无QR码 | 优化扫描配置，提供用户引导 |
| INVALID_IMAGE_FORMAT | 文件错误 | 非图像文件或损坏文件 | 实现文件预验证，提供清晰错误提示 |
| SCAN_ALREADY_ACTIVE | 状态错误 | 重复调用start() | 维护扫描状态，添加前置检查 |
| INVALID_CONFIGURATION | 配置错误 | 参数格式不正确 | 实现配置验证，提供默认值 |
| FILE_TOO_LARGE | 文件错误 | 图像文件超过大小限制 | 限制文件大小，提供压缩建议 |
| INVALID_EXTENSION | 文件错误 | 不支持的文件扩展名 | 限制可选文件类型，显示支持列表 |
| TIMEOUT | 超时错误 | 长时间未检测到QR码 | 实现超时机制，提示用户调整 |
总结与展望
html5-qrcode库提供了全面的错误处理机制，通过本文介绍的错误码解析和解决方案，开发者可以构建健壮的QR码扫描功能。关键要点：
- 分层处理：针对设备层、媒体流层、解码层和应用层错误分别处理
- 用户引导：将技术错误转化为用户可理解的操作指引
- 兼容性设计：实现优雅降级和替代方案
- 性能监控：建立错误上报和性能跟踪机制
随着WebXR技术的发展，未来QR码扫描可能会与AR技术结合，提供更直观的用户体验。开发者应持续关注API演进，及时更新错误处理策略。
最后，建议收藏本文作为开发速查手册，关注项目GitHub仓库获取最新错误码信息和解决方案。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
