eSIM-Tools二维码生成原理：本地算法+服务端双备份的容错机制是如何实现的-开发者社区

eSIM-Tools二维码生成原理：本地算法+服务端双备份的容错机制是如何实现的

【免费下载链接】eSIM-Tools专为已有 Giffgaff 和 Simyo 号码的用户设计的现代化 eSIM 管理工具集，支持将物理 SIM 卡转换为 eSIM、设备更换和二维码生成。(A modern set of eSIM management tools designed specifically for users who already have Giffgaff and Simyo numbers, offering support for converting physical SIM cards to eSIMs, device replacements, and QR code generation.)项目地址: https://gitcode.com/gh_mirrors/es/eSIM-Tools

eSIM-Tools 是一款面向 Giffgaff 与 Simyo 用户的现代 eSIM 管理工具，支持物理 SIM 转 eSIM、设备更换和二维码生成。它的二维码生成采用"浏览器本地算法优先 + 服务端 Edge Function 备份"的双通道容错设计，即使本地渲染异常也能自动切换服务端生成，保证 eSIM 安装二维码几乎不会出现"空白失败"。

一、为什么 eSIM 二维码生成需要容错设计

二维码是把 eSIM 激活码（LPA 字符串）转给手机扫描的最后一环。传统做法是从 CDN 动态加载二维码库，但在真实网络环境中这条路极不可靠：

CDN 故障或被拦截：部分网络环境下 CDN 请求 100% 失败；
广告拦截器：常见拦截插件会直接阻断第三方脚本；
CSP 策略限制：严格的 Content-Security-Policy 会拒绝外部资源。

一旦二维码加载失败，用户即使已经拿到激活码也无法扫码安装。eSIM-Tools 的解法是：把二维码算法"本地打包"，同时准备一个服务端备份通道，两者共用同一套生成规则。

二、本地生成层：零网络请求的浏览器算法

核心逻辑位于 qrcode-generator.js。项目将qrcode-generator@1.4.4库完整内联到 qrcode-lib.js 中作为 ES Module 打包，生成二维码时不需要任何网络请求，从根源上避开了 CDN 依赖。

本地生成遵循一套严格的"参数校验 + 自动适配"流程：

校验项	规则	目的
二维码内容	字符串，长度 1–2048 字符	防止空值和超大 payload
输出尺寸	整数，200–600 px	避免生成过大图片拖慢页面
纠错等级	固定 M 级（中等纠错）	平衡容错率与码点密度

生成时先由库自动检测最优版本（typeNumber = 0），再根据模块数动态计算像素格大小：cellSize = 目标尺寸 / (模块数 + 8格留白)，最后输出两张 data URL——一张 300px 的预览图，一张 400px 的悬停放大图，无需任何后端交互即可展示、放大、下载。

三、服务端备份层：Edge Function 直接生成

当本地生成抛错时，前端自动调用/bff/qrcode-generate端点，由 bff-proxy.js 中的 Edge Function在服务端直接完成二维码生成：

无冷启动延迟：QR 生成在 Edge Function 内联处理（纯 CPU 操作，通常小于 10ms），而非转发到需要冷启动的普通 Function；
同等校验标准：服务端复用与前端完全一致的校验常量（尺寸 200–600、内容 ≤2048 字符），并额外拦截__proto__、constructor等原型污染键；
CORS 白名单：仅允许配置的域名调用，不依赖 ACCESS_KEY 认证（QR 内容来自前端，不含服务端敏感数据）；
10 秒超时控制：前端通过AbortController兜底，超时即放弃该通道。

本地开发环境同样可用：server.js 模拟了 Edge 端点的内联处理，行为与线上保持一致。

四、三层降级流程：从自动到手动

完整容错链路是"本地 → 服务端 → 手动提示"三层降级，入口函数为 generateQRCodeWithFallback：

第一层：本地生成——内联库直接渲染，最快路径；
第二层：服务端降级——本地失败后自动 POST 到 Edge Function 重新生成；
第三层：LPA 手动安装提示——两条通道都失败时（如完全离线），抛出携带localError+backendError的错误对象，界面引导用户查看 LPA 激活码字符串手动安装。

每一次生成与降级尝试都会通过trackQRCodeEvent上报事件（来源 local/backend/failed、耗时、错误信息），同时推送 Sentry 警告与前端 Analytics 队列，为线上故障率提供数据支撑。该流程在 qrcode-generator.test.js 中有完整的单测覆盖：本地成功、本地失败走后端、双失败抛最终错误。

五、一致性保障：双端库代码同步校验

本地与 Edge 两份二维码库（src/js/modules/qrcode-lib.js 与 netlify/edge-functions/qrcode-lib.js）若版本漂移，会导致降级前后输出不一致。项目用 sync-qrcode-lib.js 脚本比对两份文件的 minified 库代码，一旦不一致即让 CI 检查失败，从流程上杜绝版本漂移。