# 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 - 二维码 / 条形码批量生成与解码工具
基于 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` 中以 `