forge_admin/forge-h5-ui/HTTPS_SETUP.md

H5 扫码功能 HTTPS 配置指南

问题原因

html5-qrcode 库要求必须在 HTTPS 或 localhost 环境下才能访问摄像头。

你当前的环境是局域网 IP（192.168.10.7），不是 HTTPS，所以浏览器拒绝访问摄像头。

解决方案：使用 ngrok 提供 HTTPS 隧道

步骤1：下载并安装 ngrok

1. 访问 https://ngrok.com/download
2. 下载 Windows 版本（ngrok-v3-stable-windows-amd64.zip）
3. 解压到任意目录，例如 D:\tools\ngrok
4. （可选）将 ngrok.exe 所在目录添加到系统 PATH

步骤2：注册 ngrok 账号（免费）

1. 访问 https://dashboard.ngrok.com/signup
2. 使用邮箱注册
3. 获取你的 authtoken（在 Dashboard → Your Authtoken）

步骤3：配置 ngrok

# 打开命令行，进入 ngrok 目录
cd D:\tools\ngrok

# 配置 authtoken（替换为你的 token）
ngrok config add-authtoken YOUR_AUTHTOKEN_HERE

步骤4：启动 H5 开发服务器

cd D:\java_project\forge-admin\forge-h5-ui
pnpm dev:h5

假设前端运行在 3001 端口（查看控制台输出确认实际端口）。

步骤5：启动 ngrok 隧道

# 方法1：直接启动（推荐）
ngrok http 3001

# 方法2：指定域名（如果你有付费计划）
ngrok http --domain=your-domain.ngrok-free.app 3001

启动成功后，你会看到类似这样的输出：

Forwarding    https://abc123def456.ngrok-free.app -> http://localhost:3001

步骤6：使用 HTTPS URL 访问

在手机浏览器中访问 ngrok 提供的 HTTPS URL，例如：

https://abc123def456.ngrok-free.app

注意：

• 不要使用原来的 http://192.168.10.7:3001
• 必须使用 ngrok 生成的 https://xxx.ngrok-free.app

步骤7：测试扫码功能

1. 打开 HTTPS URL
2. 点击"扫描二维码"按钮
3. 浏览器会请求摄像头权限，点击"允许"
4. 应该能正常打开相机进行扫码了！

常见问题

Q1: ngrok 免费版有限制吗？

A: 是的，免费版有以下限制：

• 每次重启 ngrok，URL 会变化
• 每月有带宽限制（通常够用）
• 连接数有限制

如果需要固定域名，可以升级到付费计划。

Q2: 为什么花生壳不行？

A: 花生壳免费版不支持 HTTPS 映射，而 html5-qrcode 必须要求 HTTPS。

Q3: 有没有其他替代方案？

A: 有的，可以使用以下工具：

• Cloudflare Tunnel（免费，推荐）：https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/
• localtunnel（免费）：npm install -g localtunnel && lt --port 3001
• serveo（免费，无需安装）：ssh -R 80:localhost:3001 serveo.net

Q4: 支付宝沙盒扫码还是空白页怎么办？

A: 支付宝内置 WebView 强制要求 HTTPS，即使使用 ngrok 也可能有问题。建议：

1. 使用普通手机浏览器（Chrome/Safari）测试
2. 或者部署到正式的 HTTPS 服务器（如阿里云、腾讯云）

验证是否成功

打开浏览器控制台（F12），如果看到以下日志，说明摄像头已正常启动：

[QR Scanner] Camera started successfully

如果看到错误信息，请检查：

1. 是否使用了 HTTPS URL
2. 是否允许了摄像头权限
3. 是否有其他应用占用了摄像头