生成高质量二维码需确保gd扩展启用、中文内容urlencode、margin≥10、纠错等级设为high、响应头正确；否则易出现乱码、扫码失败或图像破损。
生成高质量二维码图片的关键不在“装没装上”，而在于环境是否就绪、参数是否合理、输出是否干净——endroid/qr-code 装完就能跑通 demo，但真要扫得稳、看得清、传得准，下面这几处必须手动过一遍。
PHP 图像扩展没启用，writeFile() 会静默失败或输出乱码
该库默认依赖 gd，没启用时不会报错，而是回退到纯文本模式，导致生成的 .png 文件实际是乱码字符串（开头可能是 %PDF 或一堆不可见字符），浏览器打不开、扫码器读不出。
- 运行
php -m | grep -i gd，有输出才表示已加载；没输出就得装：sudo apt install php-gd（Ubuntu/Debian）或检查php.ini中是否取消了extension=gd的注释（Windows 下不是php_gd2.dll） - 用 Docker？确保
Dockerfile包含docker-php-ext-install gd，且在composer install之后执行 - 不想用 GD？可强制指定
ImagickWriter，但前提是系统已装 ImageMagick，且 PHP 启用了imagick扩展
中文内容不 urlencode()，扫码后显示为 %E4%BD%A0%E5%A5%BD
endroid/qr-code 底层使用 QR 标准的 Byte 模式，默认按 Latin-1 解析，直接传 UTF-8 字符串会导致编码错位。扫码器能识别，但解出来的常是 URL 编码后的字符串，而非原始中文。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 务必对中文内容做
urlencode($chinese)，再传给QrCode构造函数 - 扫码端能否还原成中文，取决于扫码器是否自动 decode —— 大多数现代 App（微信、支付宝）支持，老旧设备或定制固件可能只显示编码串
- 别试图改源码加
setEncoding('UTF-8')：QR 标准本身无内置字符集标识，靠上层编码处理才是合规做法
setSize() 和 setMargin() 配合不好，扫码识别率断崖下跌
setSize(300) 只控制输出图像像素尺寸，不代表内容一定能清晰容纳。纠错等级低 + 边距为 0 + 小尺寸 logo，三者叠加极易让边缘信息被裁切或模糊，扫码器第一眼就失败。
-
setMargin()绝不能设为 0；建议 ≥10（单位是模块数，非像素），否则大多数扫码器拒绝识别 - 内容较长（如带参数的 URL）或容错要求高，应配合
setErrorCorrectionLevel(ErrorCorrectionLevel::High) - 加 logo 时，
setLogoSize(60)是指 logo 图像缩放到 60×60 像素；若原图分辨率低或比例失真，会进一步降低可读性；建议 logo 宽高比 1:1，且原始尺寸 ≥120×120
直接 echo $qrCode->writeString() 导致图片损坏？检查响应头和输出缓冲
常见现象：浏览器显示“破损的图像”图标，但文件用十六进制查看器打开能看到 PNG 签名（‰PNG）。问题几乎总是出在 HTTP 响应头缺失或前后有额外输出。
- 必须在
echo前调用header('Content-Type: image/png')，且确保前面没有任何空格、BOM、var_dump()或print_r() - 框架项目（如 Laravel、Symfony）中，别手动
header()，改用响应对象：return response($qrCode->writeString())->header('Content-Type', 'image/png') -
writeString()返回 raw PNG 二进制数据；writeFile()写磁盘，适合做 CDN 缓存或异步生成
真正决定二维码质量的，从来不是「用了哪个库」，而是你有没有亲手验证 GD 是否启用、中文是否 encode、margin 是否留足、响应头是否干净——这些点不逐个确认，光看文档跑通示例，上线后扫不出就是分分钟的事。
