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，脚本会自动检测并尝试安装

安装与运行

# 克隆仓库
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/ 下的副本。同步命令：

npm run sync:zxing    # 从 node_modules/zxing-wasm 重新生成 lib/ 下两个文件

如果 lib/ 下这两个文件缺失（浅克隆，或从未提交），DataMatrix 页签与 DataMatrix 码制会初始化失败，此时执行 npm install && npm run sync:zxing。

打包发布

完整说明见 BUILD.md，Flatpak 与商店流程见文末「相关文档」。

打包命令

# 打包当前平台
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，未安装时按平台尝试安装（使用国内镜像源加速）。

# 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

也可以直接调用脚本：

./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

# 环境要求：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-<arch>.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

# 环境要求：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。

Linux

# 环境要求：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

# 一键打包，自动检查依赖、准备运行时
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）不同，两者不能混用。

推送到双远端

npm run push:all              # 同时推送到 Gitee 与 GitHub 的当前分支
npm run push:all -- -m "msg"  # 先提交全部变更再推送

使用指南

Excel 模式

点击「下载Excel模板」，Electron 下弹出原生保存对话框，浏览器模式下载为 qrcode_template.xlsx；模板源文件即 templates/template_1.xlsx
按模板填写数据，第一行为标题行：A 列是码内容（必填，空行会被跳过），B 列是下方文字（可选）
上传 Excel，可同时上传多个文件，自动合并并只保留一份表头
可选：上传 Logo 图片，只有二维码码制生效
调整生成选项（码制、尺寸、边距、颜色等）
点击「开始生成」
完成后下载 ZIP 压缩包，或使用「打印」

Excel 模板格式：

二维码内容	二维码下方文字
https://example.com	示例网站
https://github.com	GitHub
BEGIN:VCARD...	名片

手动输入模式

点击「手动输入方式」切换数据源。不切换时默认使用 Excel 数据源，「开始生成」按钮保持禁用
输入码内容与下方文字
点击「添加」或按回车加入列表，可重复添加多条，输入历史会记住
可选：上传 Logo 图片
调整生成选项后点击「开始生成」

解码

在「二维码/条形码解码」页签中拖拽图片、点击选择文件，或点击「选择文件夹」批量导入，接受任意 image/*
二维码与条形码是两条独立队列：二维码通常先出结果，条形码逐张排队、到达较晚。某条形码未跑完前该图显示「解码中」，不会提前判定为未识别
一张图识别出多个码时全部列出，可复制单条结果
未识别或想重试时，在详情中点「重新解码」
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 中以 <script> 引入：

文件	用途
`lib/qrcode.min.js`	二维码生成
`lib/JsBarcode.all.min.js`	一维条形码生成
`lib/jsqr.min.js`	二维码解码，主路径，Worker 内运行
`lib/qrcode-reader.min.js`	二维码解码降级方案，ZXing JS 端口
`lib/quagga.min.js`	一维条形码解码
`lib/xlsx.full.min.js`	Excel 读写
`lib/jszip.min.js`	ZIP 打包
`lib/zxing-wasm.js` + `lib/zxing_full.wasm`	DataMatrix 生成与解码，WASM

项目结构

qr-code_gen/
├── src/                      # 源代码（ES Module）
│   ├── app.js                # 渲染进程入口
│   ├── components/           # UI 组件（生成器、选项面板、上传、预览、工具栏、设置等）
│   ├── pages/                # 页面：GeneratorPage / DecodePage / DataMatrixDecodePage
│   ├── i18n/                 # 国际化：index.js + locales/{zh-CN,en-US}.js
│   ├── icons/                # 内联 SVG 图标
│   ├── router/               # 页签路由
│   ├── styles/               # 主题样式（main.css）
│   └── utils/                # 配置、解码器、Worker 与线程池、剪贴板、主题等
│       ├── config.js         # 全局配置（默认值、码制清单、端口、主题）
│       ├── decodePool.js     # 二维码解码 Worker 池
│       ├── datamatrixPool.js # DataMatrix 解码 Worker 池
│       ├── qrDecoder.js      # 条形码解码（Quagga）
│       └── zxingRuntime.js   # WASM 本地加载与 Worker 端库注入
├── lib/                      # 本地化第三方运行时库（含 WASM）
├── templates/                # Excel 模板
├── build/                    # 构建资源（各尺寸图标、afterPack.js 补签钩子）
├── .github/workflows/        # CI：linux-build.yml（deb/AppImage/rpm）、flathub-build.yml
├── flatpak/                  # Flatpak 清单与打包脚本（io.qrcodegen.app.yml）
├── electron-dist/            # 打包输出（gitignore）
├── main.js                   # Electron 主进程
├── server.js                 # 本地 HTTP 服务器（默认端口 12580）
├── index.html                # 应用入口页面
├── build-docker-linux.sh     # Docker 打 deb / AppImage
├── build-docker-rpm.sh       # Docker 打 rpm（ubuntu:22.04 + Ruby fpm）
├── build-flatpak.sh          # Flatpak 一键打包
├── generate-icon.js          # 从 qr_normal.png 上采样生成 icon.png（512×512）
├── push-all.sh               # 同时推送 Gitee / GitHub
└── package.json              # 项目配置与 electron-builder 打包配置

国际化

目前支持简体中文（zh-CN，默认）和 English（en-US）。

语言文件位于 src/i18n/locales/，语言列表、默认语言与浏览器语言回退映射在 src/i18n/index.js（languages / translations / 区域映射表）。界面文案通过 t('a.b.c') 取值，切换语言后组件的 updateText() 会就地刷新，不需要重载页面。

添加新语言：

在 src/i18n/locales/ 新建语言文件，导出一个嵌套对象，键名与 zh-CN.js 对齐
在 src/i18n/index.js 的 languages（名称与国旗）与 translations 中注册，并按需补充区域回退映射
顶栏语言下拉菜单会自动列出已注册语言

故障排除

应用启动失败

检查 Node.js 版本是否 >= 20
尝试删除 node_modules 后重新 npm install
应用为单实例，已有窗口时再次启动不会新开窗口

Excel 文件无法上传 / 数据没有被读取

确保格式为 .xlsx 或 .xls，且第一行为标题行
A 列必须有内容，A 列为空的行会被直接跳过
检查文件是否损坏或带密码

Logo 图片不显示

先确认码制是「二维码」，DataMatrix 与条形码不叠加 Logo，该选项会被隐藏
支持 PNG、JPG、GIF，建议小于 5 MB
Logo 占比过大会影响识别，可适当调低

生成失败

检查码内容是否为空、是否含无法编码的字符
一维码的字符集与位数由 JsBarcode 校验，EAN/UPC 需纯数字、ITF-14 为 14 位，报错信息中会带具体原因
DataMatrix 内容超出所选规格容量时会报「内容无法编码为 DataMatrix」，可改用自动规格

条形码 / DataMatrix 一直识别不出来

条形码：确认图片未被严重压缩，可在详情中点「重新解码」再跑一轮
DataMatrix：必须使用「DataMatrix解码」页签，另一个页签不解 DataMatrix
若 DataMatrix 页签报初始化错误，说明 lib/zxing_full.wasm 缺失，执行 npm run sync:zxing

Docker 跨平台打包失败

先确认 Docker 守护进程可用（docker info）；macOS 上磁盘接近写满时 Docker Desktop 的 VM 无法启动
arm64 主机打 rpm 使用 npm run build:linux:docker:rpm，不要直接用 npm run build:rpm

端口 12580 被占用

服务器会自动回退到系统分配的随机端口，并以实际端口对外提供访问，不需要手工处理

GitHub Actions 在 Setup Node.js 步骤就失败

报错 Dependencies lock file is not found ... Supported file patterns: package-lock.json, npm-shrinkwrap.json, yarn.lock，原因是 workflow 里 actions/setup-node 配了 cache: 'npm'，而仓库没有 lock 文件。把 package-lock.json 提交进仓库（并确认 .gitignore 没有忽略它），或去掉那行 cache
三个 job 会在 10 秒内同时失败且日志停在 Setup Node.js，就是这个原因，跟 electron-builder 无关
想在 CI 里出 mac 包需要 macos-* runner，Linux runner 和 Docker 都打不出来

获取帮助

项目主页：https://gitee.com/kettle_download/qr-code_gen
提交 Issue：https://gitee.com/kettle_download/qr-code_gen/issues

许可证

MIT License

致谢

Electron / electron-builder
SheetJS：Excel 读写
node-qrcode：二维码生成
JsBarcode：一维码生成
jsQR：二维码解码
qrcode-reader：二维码解码降级（ZXing JS 端口）
Quagga2：一维码解码
zxing-cpp / zxing-wasm：DataMatrix 编解码
JSZip：批量打包

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.marscode		.marscode
.workbuddy/memory		.workbuddy/memory
build		build
flatpak		flatpak
lib		lib
src		src
templates		templates
test		test
.gitignore		.gitignore
.npmrc		.npmrc
BUILD.md		BUILD.md
FLATHUB_BUILD_GUIDE.md		FLATHUB_BUILD_GUIDE.md
FLATHUB_SUBMISSION.md		FLATHUB_SUBMISSION.md
LICENSE		LICENSE
README.md		README.md
STORE_SUBMISSION.md		STORE_SUBMISSION.md
build-docker-linux.sh		build-docker-linux.sh
build-docker-rpm.sh		build-docker-rpm.sh
build-flatpak.sh		build-flatpak.sh
generate-icon.js		generate-icon.js
icon-source.png		icon-source.png
icon.png		icon.png
icon.png.bak		icon.png.bak
icon.png.bak2		icon.png.bak2
index.html		index.html
index_backup.html		index_backup.html
main.js		main.js
package-lock.json		package-lock.json
package.json		package.json
push-all.sh		push-all.sh
qr_mid.png		qr_mid.png
qr_normal.png		qr_normal.png
qr_small.png		qr_small.png
server.js		server.js

Latest commit

History

Folders and files

Repository files navigation

QrCodeGen - 二维码 / 条形码批量生成与解码工具

功能特性

生成

解码

其他

支持的码制

快速开始

环境要求

安装与运行

DataMatrix 离线依赖

打包发布

打包命令

Docker 跨平台打包

打包输出

macOS

Windows

Linux

Flatpak

推送到双远端

使用指南

Excel 模式

手动输入模式

解码

生成选项说明

技术栈

项目结构

国际化

相关文档

故障排除

获取帮助

许可证

致谢

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages