QRGen/docs/CLI_USAGE.md

QRGen CLI 使用手册

qrgen 是 QRGen 的命令行工具，支持 QR 码的编码（文本 → QR 图）和解码（QR 图 → 文本），输出 PNG/BMP/JPEG/WebP/SVG/终端 ASCII 六种格式。

快速开始

# 终端预览 QR 码
qrgen encode "Hello World"

# 生成 PNG
qrgen encode "https://example.com" -o qr.png

# 生成 SVG
qrgen encode "重要数据" -o qr.svg -l H

# 解码 QR 图片
qrgen decode qr.png

---

基础编码

语法

qrgen encode [OPTIONS] [CONTENT]
qrgen decode [FILE]

选项

选项	说明	默认值
-o, --output <文件>	输出文件路径（.png/.bmp/.jpg/.webp/.svg）	终端 ASCII 输出
-l, --level <级别>	纠错级别：L(7%) M(15%) Q(25%) H(30%)	M
-v, --version <1-40>	手动指定 QR 版本	自动选择
-s, --size <像素>	每个模块的像素大小（图像输出）	4
-m, --margin <模块>	白边宽度（模块数）	4
-f, --format <格式>	图像输出格式：png bmp jpeg webp	从文件扩展名推断
--fg <颜色>	前景色 #RRGGBB 或 #RGB	#000
--bg <颜色>	背景色 #RRGGBB 或 #RGB	#FFF
--logo <文件>	在 QR 码中央叠加 Logo 图片	无
--invert	反色输出（终端 ASCII）	—

示例

# 基础生成
qrgen encode "Hello World" -o hello.png

# 高纠错 + 大尺寸
qrgen encode "重要合同编号: ABC-12345678" -o contract.png -l H -s 8 -m 6

# 彩色 QR 码
qrgen encode "My Brand" -o brand.png --fg "#FF5733" --bg "#FFF8E7"

# 带 Logo
qrgen encode "https://mycompany.com" -o logo.png -l H --logo avatar.png

# JPEG 输出
qrgen encode "JPEG test" -o qr.jpg -f jpeg

# WebP 输出
qrgen encode "WebP test" -o qr.webp -f webp

# 指定版本（强制版本 5）
qrgen encode "Fixed version" -o fixed.png -v 5

---

编码模式

通过 --mode 参数可以使用 7 种编码模式，自动构造标准格式文本，无需手动拼接。

文本模式（默认）

qrgen encode "任意文本内容" -o text.png

等同于：

qrgen encode --mode text "任意文本内容" -o text.png

URL 模式

qrgen encode --mode url --url "https://github.com/LHY0125/QRGen" -o url.png

WiFi 模式

# 基础 WiFi
qrgen encode --mode wifi --ssid MyWiFi --password pass123 -o wifi.png

# 无密码 WiFi
qrgen encode --mode wifi --ssid FreeWiFi --encryption nopass -o free-wifi.png

# 隐藏网络 + WPA2
qrgen encode --mode wifi --ssid HiddenNet --password secret --encryption WPA2 --hidden -o hidden.png

生成的 QR 内容格式：WIFI:T:WPA;S:MyWiFi;P:pass123;;

参数	说明	默认值
--ssid	WiFi 名称	必填
--password	WiFi 密码	空
--encryption	加密方式：WPA WPA2 WEP nopass	WPA
--hidden	隐藏网络标志	false

vCard 模式（电子名片）

# 基础名片
qrgen encode --mode vcard \
  --name "张三" \
  --phone "13800138000" \
  --email "zhangsan@example.com" \
  -o card.png

# 完整名片（10 字段）
qrgen encode --mode vcard \
  --name "张三" \
  --phone "13800138000" \
  --email "zhangsan@example.com" \
  --company "科技有限公司" \
  --title "高级工程师" \
  --address "北京市海淀区" \
  --vcard-url "https://zhangsan.com" \
  --birthday "1995-06-15" \
  --note "爱好: 编程, 摄影" \
  --photo "https://zhangsan.com/avatar.jpg" \
  -o full-card.png

参数	说明
--name	姓名
--phone	电话
--email	邮箱
--company	公司
--title	职位
--address	地址
--vcard-url	个人网址
--birthday	生日 YYYY-MM-DD
--note	备注
--photo	照片 URL

Email 模式

qrgen encode --mode email \
  --to "hello@example.com" \
  --subject "合作洽谈" \
  --body "您好，我对贵公司的产品很感兴趣。" \
  -o email.png

生成的 QR 内容格式：mailto:hello@example.com?subject=...&body=...

电话模式

qrgen encode --mode phone --number "13800138000" -o phone.png

扫描后直接拨号。

短信模式

qrgen encode --mode sms \
  --number "13800138000" \
  --message "你好，方便电话吗？" \
  -o sms.png

---

批量生成

从 JSON 或 CSV 文件批量生成 QR 码。

JSON 格式

[
  {"content": "产品 A", "level": "H"},
  {"content": "产品 B", "level": "M"},
  {"content": "产品 C"}
]

qrgen encode --batch items.json --output-dir ./qr_output/
# 输出: qr_output/qr_0001.png, qr_output/qr_0002.png, ...

CSV 格式

content,level
"产品 A",H
"产品 B",M
"产品 C",M

qrgen encode --batch items.csv --output-dir ./qr_output/ -s 8

批量 WiFi 名片

JSON 中可以用模式专用字段：

[
  {"ssid": "Office-1F", "password": "pass1", "encryption": "WPA2"},
  {"ssid": "Office-2F", "password": "pass2", "encryption": "WPA2"},
  {"ssid": "Guest", "encryption": "nopass"}
]

支持的批量字段：content url ssid password encryption hidden name phone email company address to subject body number message

---

解码

从图片文件解码 QR 码内容。

qrgen decode qr.png
qrgen -d qr.jpg

输出示例：

解码成功:
  文本: https://example.com
  版本: 3
  纠错级别: M
  掩码: 2
  纠正错误: 0 码字

支持格式：PNG、JPEG、WebP、BMP。

解码器会自动对倾斜图片做旋转矫正。

---

纠错级别说明

级别	纠错率	适用场景
L	~7%	屏幕显示、数字传输
M	~15%	日常打印（默认）
Q	~25%	可能被遮挡的场景
H	~30%	Logo 嵌入、户外使用

注意： 纠错越高，相同尺寸下可存储的文本越少。H 级建议与 Logo 嵌入配合使用。

---

文件格式对比

格式	特点	适用场景
PNG	无损压缩，支持透明	通用推荐
SVG	矢量，无限缩放	印刷、网页嵌入
JPEG	有损压缩，文件小	照片场景
WebP	现代格式，文件最小	Web 优化
BMP	无压缩，文件大	嵌入式系统
ASCII	终端字符画	快速预览

---

完整参数列表

Usage: qrgen <COMMAND>

Commands:
  encode  编码：文本 → QR 码
  decode  解码：QR 码图片 → 文本

通用选项:
  --generate-completions <SHELL>  生成 Shell 补全脚本 (bash/zsh/fish/powershell/elvish)
  -h, --help                      显示帮助
  -V, --version                   显示版本

编码子命令 — qrgen encode [OPTIONS] [CONTENT]
  -o, --output <FILE>     输出文件 (.png/.bmp/.jpg/.webp/.svg)
  -l, --level <L/M/Q/H>   纠错级别 [default: M]
  -V, --version <1-40>    手动指定版本 [default: auto]
  -s, --size <PIXELS>     模块像素大小 [default: 4]
  -m, --margin <MODULES>  白边模块数 [default: 4]
  -f, --format <FORMAT>   图像格式: png/bmp/jpeg/webp [default: png]
  --fg <#RRGGBB>          前景色 [default: #000]
  --bg <#RRGGBB>          背景色 [default: #FFF]
  --logo <FILE>           Logo 图片文件
  --mode <MODE>           编码模式: text/url/wifi/vcard/email/phone/sms/batch
  --ssid <NAME>           WiFi 名称
  --password <PWD>        WiFi 密码
  --encryption <TYPE>     加密方式: WPA/WPA2/WEP/nopass [default: WPA]
  --hidden                隐藏网络
  --name <NAME>           姓名 (vCard)
  --phone <NUMBER>        电话 (vCard)
  --email <ADDR>          邮箱 (vCard)
  --company <NAME>        公司 (vCard)
  --title <TITLE>         职位 (vCard)
  --address <ADDR>        地址 (vCard)
  --vcard-url <URL>       个人网址 (vCard)
  --birthday <DATE>       生日 YYYY-MM-DD (vCard)
  --note <TEXT>           备注 (vCard)
  --photo <URL>           照片 URL (vCard)
  --to <ADDR>             收件人 (Email)
  --subject <TEXT>        主题 (Email)
  --body <TEXT>           正文 (Email)
  --number <NUMBER>       电话号码 (Phone/SMS)
  --message <TEXT>        短信内容 (SMS)
  --url <URL>             URL 链接
  --batch <FILE>          批量输入文件 (JSON/CSV)
  --output-dir <DIR>      批量输出目录

解码子命令 — qrgen decode [FILE]
  [FILE]  图片文件路径（传 - 从 stdin 读取）

stdin 管道

# 编码：从管道读入
echo "Hello" | qrgen encode - -o qr.png
cat long_text.txt | qrgen encode - -o qr.png

# 解码：从管道读入
curl -s https://api.example.com/qr.png | qrgen decode -

Shell 补全

# 生成补全脚本
qrgen --generate-completions bash > /usr/share/bash-completion/completions/qrgen
qrgen --generate-completions zsh > /usr/share/zsh/site-functions/_qrgen
qrgen --generate-completions fish > ~/.config/fish/completions/qrgen.fish

退出码

码	含义
0	成功
1	输入错误（内容为空、模式不匹配、解码失败）
2	系统错误（文件不存在、IO 错误）

---

常见问题

Q: 生成的 QR 码扫不出来？

1. 确保静区足够：-m 4 或更大
2. 提高纠错级别：-l H
3. 增大模块尺寸：-s 8 或更高
4. 如果是彩色 QR，确保前景/背景对比度足够

Q: 如何生成超大文本的 QR 码？

降低纠错级别（L 级容量最大），或让系统自动选择版本：

qrgen encode "很长的文本..." -o big.png -l L

Q: Logo 叠加后扫不出来？

1. 使用 H 级纠错（-l H）
2. Logo 尺寸占 QR 区域约 25%，系统会自动缩放
3. 确保 Logo 图片是 PNG 格式

Q: 批量生成时如何指定纠错级别？

JSON 中每个条目可以设置 "level": "H"，也可以在命令行用 -l H 统一设置。

Q: CSV 和 JSON 格式如何选择？

• JSON：支持嵌套字段，推荐用于 WiFi/vCard 等复杂模式
• CSV：简单表格，适合纯文本批量生成