结论：优先用 picqer/php-barcode-generator 快速跑通 ean_13 或 code_128，再补原理；它纯 gd、兼容 php 7.4–8.3、无命名空间冲突，避开了环境、类型校验和输出处理三大翻车点。
picqer/php-barcode-generator 跑通一个 EAN_13 或 CODE_128，再回头补参数和边界——90% 的失败不是因为不会写，而是卡在环境、类型校验或输出处理上。
为什么 picqer/php-barcode-generator 是当前最稳起点
它不依赖 Imagick，纯 GD 就能跑；PHP 7.4–8.3 全版本兼容；Composer 安装后开箱即用，没有命名空间冲突或 __autoload 报错。你见过多少老库在 PHP 8.2 下直接 Fatal error: Uncaught Error: Call to undefined function split()？这个库没这问题。
常见翻车点：
- 误装
tecnickcom/tcpdf后只为了画个条码——它得塞进 PDF 流里，单独导 PNG 很绕，还容易因字体缺失崩在Could not include font - 硬啃
dwyl/php-barcode这类无命名空间的老库——PHP 8.1+ 会报Deprecated: preg_replace(): Passing null to parameter #3 - 自己手写 Code128 编码逻辑——起始符、校验位、子集切换（A/B/C）全得手动算，一个
\x00就让整条码变空白
generate() 的三个参数和一个默认陷阱
generate() 返回的是原始图像二进制数据，不是路径，也不是 HTML 标签。直接 echo $data 会输出乱码，必须配 header 或写文件。
调用顺序是：generate($content, $type, $width, $height)
-
$content：字符串，不能为null或全空格；EAN_13类型下必须是严格 13 位纯数字，少一位或多一位都抛InvalidArgumentException -
$type：必须用常量，如BarcodeGeneratorPNG::TYPE_EAN_13，别传'EAN13'字符串——静默失败，没报错但图是空的 -
$width是每个条纹的像素宽度（module width），不是总宽。设成1太细易丢线，3是生产环境常用值；设成10不会变清晰，反而糊成黑块 -
$height是条纹高度（单位 px），不是图片总高。建议 ≥50，低于 30 时多数扫码枪扫不出
中文场景下最隐蔽的三处断点
这个库本身不渲染底部可读文字，只画条纹。但很多人以为“生成条码 = 带数字的图”，结果贴到网页上发现没数字、或数字是方框乱码——其实是你自己要补文字层，而这里最容易崩：
- 用
imagefttext()渲染中文前，必须确保系统有可用中文字体（如/usr/share/fonts/dejavu/DejaVuSans.ttf），且路径正确；Alpine Linux 默认没装fontconfig，imagettfbbox()会返回负值，文字位置计算全错 - UTF-8 字符串不能直接传给
imagefttext()，得先转 ISO-8859-1：mb_convert_encoding($text, 'ISO-8859-1', 'UTF-8') - 背景色默认透明，如果页面背景非白，条码模块可能被盖住——初始化时加第 5 个参数：
['bg_color' => [255, 255, 255, 0]]（不透明白底）
SVG 和 PNG 到底怎么选
不是“哪个高级选哪个”，是看用途：
- 要打印标签、做 PDF 插入、或需无限缩放——选
BarcodeGeneratorSVG，纯字符串输出，无 GD 依赖，连服务器都没装 GD 也能跑 - 要嵌入网页 img 标签、做实时预览、或集成进已有 GD 图像流程——选
BarcodeGeneratorPNG，但注意它默认背景透明，前端 CSS 背景色不匹配时会穿底 - 别碰
BarcodeGeneratorJPEG：压缩失真会让扫码枪识别率暴跌，尤其条纹边缘发虚
真正难的从来不是“怎么生成”，而是“生成后怎么嵌进业务流里不崩”。比如电商批量打标，得把 generate() 结果写进文件，再用 imagecopyresampled() 叠到商品图右下角——这时候模块宽度、缩放倍数、坐标偏移全得对齐，差 1px 都可能让扫码枪失焦。这些细节，文档不会写，但线上故障单里天天见。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
