首选 picqer/php-barcode-generator 库，需确保引入 vendor/autoload.php 且启用 GD 扩展；类未找到是自动加载失效，输出空白多因 GD 缺失；推荐 thickness=2、scale=2 组合避免锯齿。
直接用 Picqer\Barcode\BarcodeGeneratorPNG 生成条形码没问题，但多数人卡在「输出空白」或「报 Class not found」——根本原因是没确认自动加载是否生效，且忽略了 GD 扩展依赖。
Composer 安装后类找不到？检查 autoload 是否触发
运行 composer install 或 composer require picqer/php-barcode-generator 后，必须确保项目已包含 vendor/autoload.php。漏掉这句，new BarcodeGeneratorPNG() 必然报错。
- 常见错误现象：
Fatal error: Uncaught Error: Class 'Picqer\Barcode\BarcodeGeneratorPNG' not found - 检查点：确认
require 'vendor/autoload.php';在脚本最顶部（不是 include_once，不是条件引入） - 验证方式：临时加一行
var_dump(class_exists('Picqer\Barcode\BarcodeGeneratorPNG'));，输出bool(true)才算到位
生成 PNG 图片却返回空白？优先排查 GD 扩展
BarcodeGeneratorPNG 强依赖 PHP 的 GD 库，而 CLI 模式和 Web 模式可能启用不同配置——Web 服务器（如 Nginx + PHP-FPM）常默认禁用 GD。
- 使用场景：本地开发环境能跑，上线后白屏，大概率是服务器没开 GD
- 快速验证：
php -m | grep gd（CLI）；或写个phpinfo();页面搜gd - 若缺失：Ubuntu 上执行
sudo apt install php-gd，然后重启 PHP-FPM 或 Apache - 替代方案：改用
BarcodeGeneratorHTML或BarcodeGeneratorSVG，它们不依赖 GD
中文文档里没提的参数陷阱：$scale 和 $thickness 组合易出锯齿
generate() 方法第 3、4 个参数分别是 $scale（缩放倍数）和 $thickness（条宽像素），但两者不是线性叠加关系——$thickness 是原始单位宽度，$scale 会把它放大，若原始 $thickness = 1 再设 $scale = 4，实际线条只有 4 像素宽，极易被抗锯齿模糊掉。
- 推荐组合：
$thickness = 2起步，$scale = 2或3，避免用1做厚度 - 调试技巧：先固定
$scale = 1，调通$thickness，再逐步加大$scale - 注意兼容性：某些扫码设备对线条连续性敏感，
$thickness 在低分辨率屏幕下可能识别失败
真正麻烦的从来不是“怎么生成”，而是“为什么生成了却扫不出”——这时候别急着换库，先看 GD 是否就位、$thickness 是否太细、HTTP 响应头有没有误加 text/html 导致浏览器当文本渲染 PNG。
