Composer安装endroid/qr-code失败主因是PHP版本不匹配：PHP 7.4项目需指定^3.9，8.0+可用v4但需适配WriterInterface；输出乱码因缺失Content-Type响应头；中文乱码因字体缺失，v4必须显式传入中文字体；logo叠加需控制尺寸≤20%且背景透明。
composer 安装 endroid/qr-code 失败或版本冲突
很多人卡在第一步：执行 composer require endroid/qr-code 报错，常见原因是 PHP 版本不匹配或已存在旧版依赖。这个库 v4 要求 PHP ≥ 8.0，v3 支持 PHP 7.4，但默认安装会拉最新版。
- PHP 7.4 项目请显式指定版本：
composer require endroid/qr-code:^3.9 - PHP 8.0+ 可用 v4，但注意 v4 移除了
QrCode::render()直出字符串的方法，改用WriterInterface - 如果项目已有
symfony/http-foundation或symfony/mime，别硬删——v4 依赖它们，强行绕过会导致Unable to find writer
QrCode::create() 后直接输出乱码或空白页
这是最常被忽略的响应头问题。QR 码本质是图片二进制流，浏览器没收到正确 Content-Type 就当文本渲染，自然乱码。
- 必须手动设置 header：
header('Content-Type: image/png');（PNG 格式下） - 确保输出前无任何空格、BOM、
echo或 warning 输出，否则 header 发送失败 - 调试时加一句
if (headers_sent($file, $line)) { die("Headers already sent in $file:$line"); } - v4 中推荐用
PngWriter+->writeString()，比老版->render()更可控
中文内容生成二维码显示方块或乱码
不是库不支持中文，而是默认字体缺失。v3 默认用 DejaVuSans，v4 默认无字体，全靠你传入 FontBuilder。
- v3：确认
vendor/endroid/qr-code/assets/fonts/DejaVuSans.ttf存在；若被删，重装或手动补上 - v4：必须显式加载中文字体，例如：
(new FontBuilder(__DIR__.'/simhei.ttf'))->build() - 字体文件路径要绝对路径，相对路径在 CLI 和 Web 下行为不一致
- 避免用 Windows 自带的
simsum.ttc（是 TTC 复合格式），优先选simhei.ttf或NotoSansCJKsc-Regular.otf
生成带 logo 的二维码但边缘模糊或识别率下降
logo 图片叠加不是简单“贴上去”，尺寸、透明度、位置都会影响扫码成功率。
立即学习“PHP免费学习笔记（深入）”；
- logo 宽高建议 ≤ 二维码总宽的 20%，太大直接破坏定位图案（三个角上的大方块）
- 用
LogoBuilder（v4）或setLogoPath()（v3）时，确保 logo 是正方形且背景透明（PNG） - 不要用
imagecopymerge手动合成——它会丢 alpha 通道，导致 logo 边缘发灰 - 生成后务必用多个扫码 App 实测（微信、支付宝、iOS 原生相机），有些算法对中心区域干扰特别敏感
