# QrCode_gen **Repository Path**: kettle_download/qr-code_gen ## Basic Information - **Project Name**: QrCode_gen - **Description**: 二维码批量生成 - **Primary Language**: JavaScript - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-02-09 - **Last Updated**: 2026-09-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # QrCodeGen - 二维码 / 条形码批量生成与解码工具 QrCodeGen Logo 基于 Electron 的桌面工具:从 Excel 或手动输入批量生成二维码、DataMatrix 和一维条形码,也能把图片里的码批量解回来。 ## 功能特性 ### 生成 - **Excel 批量生成**:从 Excel 读取数据生成码图,可一次上传多个文件并自动合并 - **手动输入模式**:不依赖 Excel,逐条添加内容生成 - **自定义 Logo**:二维码中心叠加 Logo,仅二维码码制支持 - **多种码制**:二维码、DataMatrix、7 种一维条形码,见下面的码制表 - **灵活配置**:尺寸、边距、下方文字大小、前景/背景/文字颜色,单位可在 px 与 mm 之间切换 - **智能命名**:可用下方文字作为文件名,重复名称自动加后缀 - **实时预览 + 批量下载**:生成过程实时预览,完成后一键下载 ZIP - **打印支持**:打印页使用 `@page size: A4` 排版 - **单个保存**:预览区可单独下载某一张,Electron 下走原生保存对话框 ### 解码 顶部三个页签:码生成 / 二维码/条形码解码 / DataMatrix解码。 - **二维码 + 条形码解码**:二维码先走 jsQR,失败后回落到 qrcode-reader(ZXing 的 JS 端口);条形码走 Quagga 通道 - **DataMatrix 解码**:独立页签,基于 zxing-cpp 的 WASM 实现 - **批量导入**:支持拖拽、多选文件、选择整个文件夹 - **并行解码**:二维码与 DataMatrix 各用独立 Worker 池并行;条形码通道因 Quagga 是主线程单例,一次只跑一张 - **单图多码**:一张图识别出多个码时逐条列出结果 - **重新解码**:详情页可对单张图手动重试,覆盖旧结果 - **一键复制**:解码结果可复制到剪贴板 ### 其他 - **多语言**:简体中文 / English 切换,`zh-TW`、`zh-HK`、`en-GB` 等自动回退 - **三套主题**:现代 / 经典 / 酷黑 - **本地服务器**:内置静态 HTTP 服务器,默认端口 12580,被占用时自动改用随机端口。整个应用会发布到局域网,可以在其他电脑或手机浏览器里打开;也可以 `node server.js` 独立运行 - **离线使用**:所有运行时库(含 WASM)随包本地加载,不联网也能完整使用 - **跨平台**:Windows、macOS、Linux(deb / rpm / AppImage / Flatpak) - **商店就绪**:支持 Microsoft Store(MSIX)与 Flathub 发布流程 ### 支持的码制 | 码制 | 生成 | 解码 | |------|------|------| | QR Code(二维码) | √ | √ | | DataMatrix | √ | √(独立页签) | | CODE128 | √ | √ | | EAN-13 / EAN-8 | √ | √ | | UPC-A / UPC-E | √ | √ | | CODE39 | √ | √ | | ITF-14 | √ | √ | DataMatrix 支持的规格:方形 10×10 至 144×144 共 24 档,以及 ISO/IEC 16022 定义的 4 种矩形(18×8、32×8、26×12、36×16)。默认自动选择规格,可手动指定,另有强制正方形、GS1 模式、反色、静默区四个开关。36×12 这类非 ISO 的矩形规格没有开放到界面,因为普通扫码枪不一定识别。 ## 快速开始 ### 环境要求 - **Node.js** >= 20.0.0(`package.json` 的 `engines` 约束) - **Electron** 29.x(`devDependencies`,`.npmrc` 中 `target = 29.4.6`) - **npm**:随 Node 20 附带的版本即可 - 跨平台打 Linux 包时需要 **Docker**,脚本会自动检测并尝试安装 ### 安装与运行 ```bash # 克隆仓库 git clone https://gitee.com/kettle_download/qr-code_gen.git cd qr-code_gen # 安装依赖 npm install # 启动桌面应用 npm start ``` 说明: - `npm start` / `dev` / `electron` / `electron:dev` 都是同一个 `electron .`。 - 本仓库 `.npmrc` 把 npm 缓存重定向到项目内的 `.npm/`(已在 `.gitignore` 中),原生模块按 Electron 头文件编译,所以不要在仓库外复用这个缓存目录。 - `package-lock.json` 随仓库提交。CI 里 `actions/setup-node` 配了 `cache: npm`,找不到 lock 文件会直接失败,别再把它加回 `.gitignore`。 - 应用使用 Electron 单实例锁,重复启动只会唤起已有窗口。 ### DataMatrix 离线依赖 DataMatrix 的编解码依赖两个随仓库分发的文件: - `lib/zxing-wasm.js`:zxing-wasm 的 IIFE 构建产物,由 `index.html` 以全局 `ZXingWASM` 加载 - `lib/zxing_full.wasm`:WASM 二进制,运行时以本地字节流注入。默认的 CDN `locateFile` 在离线环境下不可用 npm 依赖 `zxing-wasm` 只是用来提供这两个文件,打包时被 `build.files` 排除,实际出货的是 `lib/` 下的副本。同步命令: ```bash npm run sync:zxing # 从 node_modules/zxing-wasm 重新生成 lib/ 下两个文件 ``` 如果 `lib/` 下这两个文件缺失(浅克隆,或从未提交),DataMatrix 页签与 DataMatrix 码制会初始化失败,此时执行 `npm install && npm run sync:zxing`。 ## 打包发布 完整说明见 [BUILD.md](BUILD.md),Flatpak 与商店流程见文末「相关文档」。 ### 打包命令 ```bash # 打包当前平台 npm run dist # electron-builder,完整安装包 npm run pack # electron-builder --dir,只出解包目录,便于调试 # 打包特定平台 npm run build:mac # macOS,dmg + zip npm run build:win # Windows,msix + nsis exe + zip npm run build:linux # Linux,AppImage + deb + rpm npm run build:all # 三个平台 # 指定架构,:x86 / :x64 打 Intel,:arm64 打 Apple Silicon npm run build:mac:arm64 npm run build:mac:x64 npm run build:win:x86 npm run build:win:arm64 npm run build:linux:x86 npm run build:linux:arm64 npm run build:all:x86 npm run build:all:arm64 # macOS 单独打某种格式(dmg 与 zip 都是默认目标,拆开打能省一半时间) npm run build:mac:dmg:arm64 npm run build:mac:zip:arm64 npm run build:mac:dmg:x64 npm run build:mac:zip:x64 # 单独打 Linux 格式 npm run build:deb # 仅 deb,另有 :x64 / :arm64 npm run build:rpm # 仅 rpm,需本地 rpmbuild;跨平台请用下面的 Docker 模式 # MSIX / 商店包 npm run build:msix # 另有 :x64 / :arm64 npm run build:store # msix + --publish never ``` ### Docker 跨平台打包 在 macOS / Windows / 任意 Linux 上用容器打 Linux 包,不需要本地安装 dpkg-deb、rpmbuild 这些工具链。脚本会自动检测 Docker,未安装时按平台尝试安装(使用国内镜像源加速)。 ```bash # deb npm run build:linux:docker # 默认 deb,当前架构 npm run build:linux:docker:deb:x64 npm run build:linux:docker:deb:arm64 npm run build:linux:docker:deb:all # x64 + arm64 # AppImage npm run build:linux:docker:appimage npm run build:linux:docker:appimage:x64 npm run build:linux:docker:appimage:arm64 npm run build:linux:docker:appimage:all # rpm 用独立脚本:ubuntu:22.04 容器内通过 Ruby fpm 打包, # 以规避 electron-builder 自带 x86 fpm 在 arm64 容器下的兼容问题 npm run build:linux:docker:rpm npm run build:linux:docker:rpm:x64 npm run build:linux:docker:rpm:arm64 npm run build:linux:docker:rpm:all ``` 也可以直接调用脚本: ```bash ./build-docker-linux.sh deb # 打包 deb ./build-docker-linux.sh deb all # 同时打包 x64 + arm64 ./build-docker-linux.sh appimage # 打包 AppImage ./build-docker-linux.sh rpm # 转发到 build-docker-rpm.sh ./build-docker-linux.sh --help # 查看帮助 ./build-docker-rpm.sh # 打包 rpm,当前架构 ./build-docker-rpm.sh all # rpm x64 + arm64 ``` 容器打包要求 Docker 守护进程处于运行状态。若报 `docker daemon 未运行`,先启动 Docker Desktop;macOS 上系统盘接近写满时,Docker Desktop 会直接拒绝启动 VM。 ### 打包输出 安装包生成在 `electron-dist/`(已在 `.gitignore` 中)。文件名由 electron-builder 默认规则生成,包含产品名、版本号与架构,实测例:`electron-dist/qrcodegen_1.0.7_amd64.deb`。 | 平台 | 格式 | 说明 | |------|------|------| | macOS | `.dmg` | 标准安装包 | | macOS | `.zip` | 便携版 | | Windows | `Setup .exe` | NSIS 安装程序,可选安装目录、创建桌面/开始菜单快捷方式 | | Windows | `.zip` | 便携版 | | Windows | `.msix` | 商店包 | | Linux | `.AppImage` | 通用格式,无需安装 | | Linux | `.deb` | Debian / Ubuntu | | Linux | `.rpm` | Fedora / CentOS / RHEL | | Linux | `.flatpak` | Flathub 格式,产物在 `flatpak/build-output/QrCodeGen.flatpak` | ### macOS ```bash # 环境要求:macOS(Electron 29 支持的版本)、Node.js 20+ # codesign 随 Xcode Command Line Tools 分发,打包最后一步要用到 npm install npm run build:mac:arm64 # Apple Silicon npm run build:mac:x64 # Intel ``` 产物实测名(1.0.7):`electron-dist/QrCodeGen-1.0.7-arm64.dmg`(96 MB)与 `electron-dist/QrCodeGen-1.0.7-arm64-mac.zip`(93 MB)。 几点必须知道的: - mac 包只能在 macOS 上打。Docker、Linux 与 Windows 主机都出不来,需要 macOS SDK 且受 Apple 许可约束;`.github/workflows/linux-build.yml` 里也只有 deb / AppImage / rpm 三个 job,没有 mac job。反过来,在一台 Apple Silicon 上打 x64 包(或反之)是支持的,`--x64` / `--arm64` 只是换 Electron 压缩包。 - 首次打某个架构要联网下载 `electron-v29.4.6-darwin-.zip`(95 MB,实测 41 秒),之后走 `~/Library/Caches/electron/` 缓存。 - 在 arm64 上 electron-builder 会用 APFS 建 dmg(日志提示 `HFS+ is unavailable`),对应 macOS 10.12+。 - 只要 `dmg` 或 `zip` 一种产物用 `build:mac:dmg:arm64` / `build:mac:zip:arm64`,比一次打两种快。 签名:钥匙串里没有 Developer ID 时,electron-builder 会打印 `skipped macOS application code signing` 并完全跳过签名,此时 bundle 只有 Electron 自带的 linker ad-hoc 签名,`codesign --verify --deep --strict` 会报 `code has no resources but signature indicates they must be present`。`build/afterPack.js`(注册在 `build.afterPack`)会在打包末尾补一次 bundle 级 ad-hoc 签名,让 `Identifier` 变成 `com.qrcodegen.app`、资源与 Info.plist 进入签名覆盖范围,校验通过。配了真实证书后 electron-builder 的正式签名会覆盖这一步。 ad-hoc 签名不等于公证。未公证的包从浏览器下载后首次打开仍会被 Gatekeeper 拦住,需要右键「打开」,或 `xattr -cr QrCodeGen.app`。要正式分发就在 `package.json` 的 `build.mac` 中配置 `identity`、`notarize`、`hardenedRuntime` 与 `entitlements`。 ### Windows ```bash # 环境要求:Windows 10/11、Node.js 20+,Windows SDK 仅在需要签名时才要 npm install npm run build:win # msix + nsis + zip npm run build:msix # 仅商店包 ``` `build.appx` 中的 `publisher` 是占位值 `CN=Your-Publisher-ID`,正式上架前要替换成证书主体,见 [STORE_SUBMISSION.md](STORE_SUBMISSION.md)。 ### Linux ```bash # 环境要求:Node.js 20+;直接在 Linux 主机打包还需要对应工具链 # 主机直打,需 dpkg-deb / rpmbuild npm run build:linux # AppImage + deb + rpm npm run build:deb # 仅 deb npm run build:rpm # 仅 rpm # Docker 打包,不需要本地工具链 npm run build:linux:docker:deb npm run build:linux:docker:appimage npm run build:linux:docker:rpm ``` ### Flatpak ```bash # 一键打包,自动检查依赖、准备运行时 npm run build:flatpak npm run build:flatpak:install # 构建后自动安装到当前用户 npm run build:flatpak:test # 构建并试运行 # 手动构建 sudo apt-get install flatpak flatpak-builder # Debian/Ubuntu sudo dnf install flatpak flatpak-builder # Fedora flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo flatpak install flathub org.freedesktop.Platform//23.08 org.freedesktop.Sdk//23.08 flatpak install flathub org.freedesktop.Sdk.Extension.node20//23.08 flatpak install flathub org.electronjs.Electron2.BaseApp//23.08 cd flatpak flatpak-builder --repo=repo --force-clean build-dir io.qrcodegen.app.yml flatpak build-bundle repo QrCodeGen.flatpak io.qrcodegen.app ``` Flatpak 的应用 ID 是 `io.qrcodegen.app`(清单 `flatpak/io.qrcodegen.app.yml`),与 electron-builder 的 `build.appId`(`com.qrcodegen.app`)不同,两者不能混用。 ### 推送到双远端 ```bash npm run push:all # 同时推送到 Gitee 与 GitHub 的当前分支 npm run push:all -- -m "msg" # 先提交全部变更再推送 ``` ## 使用指南 ### Excel 模式 1. 点击「下载Excel模板」,Electron 下弹出原生保存对话框,浏览器模式下载为 `qrcode_template.xlsx`;模板源文件即 `templates/template_1.xlsx` 2. 按模板填写数据,第一行为标题行:A 列是码内容(必填,空行会被跳过),B 列是下方文字(可选) 3. 上传 Excel,可同时上传多个文件,自动合并并只保留一份表头 4. 可选:上传 Logo 图片,只有二维码码制生效 5. 调整生成选项(码制、尺寸、边距、颜色等) 6. 点击「开始生成」 7. 完成后下载 ZIP 压缩包,或使用「打印」 Excel 模板格式: | 二维码内容 | 二维码下方文字 | |-----------|---------------| | https://example.com | 示例网站 | | https://github.com | GitHub | | BEGIN:VCARD... | 名片 | ### 手动输入模式 1. 点击「手动输入方式」切换数据源。不切换时默认使用 Excel 数据源,「开始生成」按钮保持禁用 2. 输入码内容与下方文字 3. 点击「添加」或按回车加入列表,可重复添加多条,输入历史会记住 4. 可选:上传 Logo 图片 5. 调整生成选项后点击「开始生成」 ### 解码 1. 在「二维码/条形码解码」页签中拖拽图片、点击选择文件,或点击「选择文件夹」批量导入,接受任意 `image/*` 2. 二维码与条形码是两条独立队列:二维码通常先出结果,条形码逐张排队、到达较晚。某条形码未跑完前该图显示「解码中」,不会提前判定为未识别 3. 一张图识别出多个码时全部列出,可复制单条结果 4. 未识别或想重试时,在详情中点「重新解码」 5. DataMatrix 图片要切到「DataMatrix解码」页签处理 ### 生成选项说明 | 选项 | 说明 | 默认值 | 范围 | |------|------|--------|------| | 码制类型 | 二维码 / DataMatrix / 7 种条形码 | 二维码 | 9 个选项,选择会被记住 | | DataMatrix 规格 | 自动或手动指定方形/矩形规格 | 自动 | 方形 10×10…144×144,ISO 矩形 4 档 | | 强制正方形 / GS1 / 反色 / 静默区 | DataMatrix 专用开关 | 静默区开,其余关 | 无 | | 码图尺寸 | 生成的图片大小 | 300 px | 100–1000,步进 50,可切 mm | | Logo 大小 | Logo 占码图比例 | 20 % | 10–40 %,仅二维码 | | 文字大小 | 下方文字字号 | 16 px | 10–30,步进 1,可切 mm | | 边距 | 码图四周留白 | 15 px | 0–100,步进 1,可切 mm | | 前景色 / 背景色 / 文字颜色 | 取色器或十六进制输入 | `#000000` / `#ffffff` / `#000000` | 带最近使用历史,并持久化 | | 使用下方文字作为文件名 | 用下方文字命名文件,重复名称自动加后缀 | 开启 | 无 | ## 技术栈 - **框架**:Electron 29.x,主进程 `main.js`,渲染进程为纯 ES Module,没有打包器 - **构建**:electron-builder 24.x - **npm 依赖**:`xlsx`、`qrcode`、`qrcodejs`、`jszip`、`zxing-wasm@3.1.3` 运行时实际加载的是 `lib/` 下的本地副本,在 `index.html` 中以 `