简介这是一款基于PHP实现的二维码在线生成工具本地版面向需要为网站快速添加二维码生成功能的开发者与站长尤其适合PHP初学者和中小型项目部署使用。程序通过当前时间与随机数组合生成PNG图片路径有效避免文件重名生成的图片存放于根目录单张大小约1K至4K图片长宽随文字内容多少自动变化实测可正常处理200个汉字。资源包共7个文件包含2个php核心脚本、2个url快捷方式、2个txt说明文档及1个png示例图片压缩包仅25KB上传至PHP网站空间即可运行子目录环境同样支持首页为index.php。目前已有280人学习下载。读者可获得一套可直接部署的二维码生成脚本理解随机文件名防重复、动态尺寸计算等实现思路并借助说明文档快速完成本地或线上环境的搭建与调试。1. 从一张离线二维码说起PHP 本地版生成工具到底解决什么问题很多做 PHP 项目的同行都遇到过这种场景内网系统、客户现场、断网环境业务方突然要求把一段订单号、设备编号或者核销链接转成二维码打印出来。第一反应是打开某个在线二维码网站把内容粘进去、下载图片、再塞回项目里。平时这么干没问题可一旦涉及内网数据、批量生成、或者要求二维码带自定义 Logo 和容错等级在线工具就开始翻车——要么接口限流要么图片带水印要么内容被第三方记录。PHP 二维码在线生成工具本地版 v1.0这个标题讲的正是把「在线生成」这套体验搬到自己的 PHP 环境里用本地代码直接产出二维码图片不依赖外部服务。它适合三类人一是做后台管理系统的 PHP 开发者需要在订单、票务、资产标签里嵌二维码二是运维或实施人员要在客户内网批量生成带参数的二维码三是想给现有 PHP 项目加一个「扫码即用」入口的独立开发者。核心诉求就一句话内容不出本地生成过程可控参数能调批量能跑。下面按「先跑通最小例子 → 再拆参数和批量 → 最后讲踩坑和进阶」的顺序展开中间会用到 PHP 生态里最常见的二维码库也会给出可直接抄的命令和代码。2. 选型与最小可跑PHP 本地生成二维码用什么库、怎么装2.1 为什么优先选 endroid/qr-code 而不是自己造轮子PHP 里生成二维码的库不算少常见的有endroid/qr-code、phpqrcode、bacon/bacon-qr-code等。如果只是临时输出一张图phpqrcode单文件引入就能用但它的维护节奏慢PHP 8 下有些写法会报废弃警告。endroid/qr-code基于bacon/bacon-qr-code做封装支持 PNG、SVG、WebP、EPS 多种输出能直接设置 Logo、前景色、背景色、边距和纠错等级而且用 Composer 管理升级路径清晰。对于「本地版工具」这个定位我一般会选它因为后续要加 Logo、批量、缓存时不用换库。选型时重点看三个维度输出格式是否覆盖你的场景网页展示用 PNG打印用 SVG 或 EPS、是否支持纠错等级调整内容长或要加 Logo 时必须调高、是否依赖 GD 或 Imagick 扩展。endroid/qr-code默认走 GD服务器上gd扩展基本都有部署阻力小。如果你的环境连 GD 都没有那就得先补扩展否则任何库都跑不起来。2.2 用 Composer 装库并跑通第一张二维码先确认 PHP 版本和扩展。命令行执行php -v看版本建议 7.4 以上再执行php -m | grep -i gd确认 GD 已启用。没有的话Ubuntu 下sudo apt install php-gdCentOS 下sudo yum install php-gd装完重启 PHP-FPM。接着在项目目录初始化并安装# 进入你的项目根目录 cd /var/www/qr-local # 如果没有 composer.json先初始化一路回车即可 composer init --no-interaction # 安装 endroid/qr-code这里不写死版本号让 Composer 选当前稳定版 composer require endroid/qr-code安装完成后写一个最小生成脚本make_qr.php?php // 引入 Composer 自动加载 require __DIR__ . /vendor/autoload.php; use Endroid\QrCode\QrCode; use Endroid\QrCode\Writer\PngWriter; // 1. 创建二维码对象内容可以是任意字符串 $qrCode new QrCode(https://example.com/order/10086); // 2. 选择 PNG 写出器 $writer new PngWriter(); // 3. 生成结果对象 $result $writer-write($qrCode); // 4. 直接输出到浏览器或保存到文件 header(Content-Type: . $result-getMimeType()); echo $result-getString(); // 如果要保存文件用下面这行替代上面的 header echo // $result-saveToFile(__DIR__ . /qrcode.png);这段代码的逻辑很直白QrCode负责承载内容和参数PngWriter负责把内容渲染成 PNG 二进制write()返回一个结果对象既能直接输出也能落盘。参数方面构造函数第一个参数是必填的内容字符串PngWriter目前不需要额外配置。跑php make_qr.php如果终端输出乱码是正常的因为它是二进制图片流用浏览器访问这个脚本就能看到二维码。想保存文件就把saveToFile那行打开注释掉输出那两行。提示如果浏览器访问报「headers already sent」检查 PHP 文件开头是否有 BOM 或多余空行?php之前不能有任何输出。2.3 把生成逻辑封装成可复用函数最小例子跑通后别急着在每个页面里复制粘贴。封装一个函数把内容、尺寸、纠错等级、Logo 路径作为参数传进去后续批量或接口调用都从这里走?php require __DIR__ . /vendor/autoload.php; use Endroid\QrCode\QrCode; use Endroid\QrCode\Encoding\Encoding; use Endroid\QrCode\ErrorCorrectionLevel; use Endroid\QrCode\RoundBlockSizeMode; use Endroid\QrCode\Writer\PngWriter; /** * 生成二维码并保存 * * param string $content 二维码内容 * param string $savePath 保存路径 * param int $size 图片边长像素 * param string $level 纠错等级 L/M/Q/H * return string 实际保存路径 */ function makeQr(string $content, string $savePath, int $size 300, string $level M): string { // 纠错等级映射H 最高容错约 30%适合加 Logo $levels [ L ErrorCorrectionLevel::Low, M ErrorCorrectionLevel::Medium, Q ErrorCorrectionLevel::Quartile, H ErrorCorrectionLevel::High, ]; $qrCode new QrCode( data: $content, encoding: new Encoding(UTF-8), errorCorrectionLevel: $levels[$level] ?? ErrorCorrectionLevel::Medium, size: $size, margin: 10, roundBlockSizeMode: RoundBlockSizeMode::Margin, ); $writer new PngWriter(); $result $writer-write($qrCode); $result-saveToFile($savePath); return $savePath; } // 调用示例 makeQr(ORDER-2024-0001, __DIR__ . /qr_0001.png, 400, H);这里几个参数值得展开size是最终图片边长不是模块数设太小会导致扫码识别率下降打印场景建议不低于 300margin是二维码四周留白标准要求至少 4 个模块宽设 10 像素在 300 尺寸下比较稳妥errorCorrectionLevel从 L 到 H 容错能力递增但同样内容下等级越高、模块越密图片尺寸不变时反而可能更难扫所以不是无脑选 H。roundBlockSizeMode控制模块取整方式Margin表示在边距上取整能减少边缘锯齿。3. 参数调优与批量落地尺寸、纠错、Logo 和 Excel 批量处理3.1 尺寸、纠错等级、边距三个参数怎么配二维码能不能被扫出来八成取决于这三个参数。尺寸方面网页展示 200 到 300 像素够用打印标签建议 300 到 500 像素户外或远距离扫码要按「扫码距离 ÷ 10」估算边长单位毫米。纠错等级方面纯文本内容用 M 即可要叠加 Logo 或二维码可能被遮挡、磨损选 Q 或 H。边距方面低于 4 个模块宽会导致识别设备找不到定位图案这是最常见的「自己手机能扫、别人扫不出」的原因。参数常用值适用场景调大后的代价size300 / 400 / 500网页 / 标签 / 打印文件变大加载变慢errorCorrectionLevelM / Q / H纯文本 / 加 Logo / 易损环境模块变密小尺寸下更难扫margin10 / 20常规 / 打印留白图片有效区域变小我一般会先按场景定尺寸再根据是否加 Logo 定纠错等级最后把边距固定为 10 到 20。改完参数一定用两台不同品牌手机各扫一次别只用自己的手机测。3.2 叠加 Logo 的正确姿势与透明背景处理加 Logo 是「本地版」相对在线工具最实用的能力之一。做法是先生成二维码再用 GD 把 Logo 合成到中心。注意 Logo 不能超过二维码面积的 20%否则纠错等级再高也可能扫不出。下面是一个合成示例?php require __DIR__ . /vendor/autoload.php; use Endroid\QrCode\QrCode; use Endroid\QrCode\ErrorCorrectionLevel; use Endroid\QrCode\Logo\Logo; use Endroid\QrCode\Writer\PngWriter; $qrCode new QrCode( data: https://example.com/pay/8899, errorCorrectionLevel: ErrorCorrectionLevel::High, // 加 Logo 必须用 H size: 400, margin: 15, ); // Logo 对象路径、显示宽度、是否留白 $logo new Logo( path: __DIR__ . /logo.png, resizeToWidth: 80, // 约为二维码宽度的 20% punchoutBackground: true, // 在 Logo 周围挖出白色区域提升识别率 ); $writer new PngWriter(); $result $writer-write($qrCode, $logo); $result-saveToFile(__DIR__ . /qr_with_logo.png);resizeToWidth控制 Logo 宽度400 像素二维码配 80 像素 Logo 比较安全punchoutBackground会在 Logo 周围留出一圈背景色避免 Logo 直接压在模块上造成干扰。如果 Logo 本身是透明 PNG合成后可能出现半透明边缘建议先在图像工具里给 Logo 加一圈白底再使用。3.3 用 PHP 读 Excel 批量生成二维码批量场景常见于资产标签、票务核销、设备编号。Excel 批量处理在 PHP 里一般用phpoffice/phpspreadsheet读表再循环调用前面的makeQr。先装库composer require phpoffice/phpspreadsheet然后写批量脚本?php require __DIR__ . /vendor/autoload.php; use PhpOffice\PhpSpreadsheet\IOFactory; // 读取 Excel假设第一列是编号第二列是内容 $spreadsheet IOFactory::load(__DIR__ . /codes.xlsx); $sheet $spreadsheet-getActiveSheet(); $rows $sheet-toArray(); $outputDir __DIR__ . /output; if (!is_dir($outputDir)) { mkdir($outputDir, 0755, true); } foreach ($rows as $index $row) { // 跳过表头 if ($index 0) { continue; } $code trim((string)($row[0] ?? )); $content trim((string)($row[1] ?? )); if ($code || $content ) { continue; // 空行跳过避免生成空二维码 } // 文件名做安全过滤防止路径穿越 $safeName preg_replace(/[^A-Za-z0-9_\-]/, _, $code); makeQr($content, $outputDir . / . $safeName . .png, 400, M); } echo 生成完成共处理 . (count($rows) - 1) . 行\n;逻辑说明IOFactory::load自动识别 xlsx 格式toArray()把整表转成二维数组第一行通常是表头所以跳过。preg_replace那行是血泪经验——如果编号里有斜杠或中文直接拼路径会生成失败甚至写到意外目录。参数上makeQr的尺寸和纠错等级按你的打印设备调整如果 Excel 行数上万建议分批执行并加set_time_limit(0)否则脚本会超时。注意批量生成时不要每行都重新加载库或重建 Writer把 Writer 提到循环外能明显提速。上面的makeQr每次新建对象行数少无所谓上万行时建议改成传入 Writer 实例。4. 避坑与排查本地版二维码生成最常见的 5 个翻车现场4.1 现象浏览器直接输出图片页面却显示一堆乱码原因通常是脚本在header()之前已经有输出比如文件开头有 BOM、?后面有空行、或者require的某个文件里带了 echo。PHP 一旦发送了任何内容再设 Content-Type 就无效。解决方法是检查所有被引入文件去掉结尾的?用编辑器把文件保存为「无 BOM 的 UTF-8」。排查时可以在header()前加if (headers_sent($file, $line)) { die(已输出: $file:$line); }直接定位到哪一行提前输出了。4.2 现象二维码能生成但手机扫出来是乱码或内容截断原因多半是内容编码和二维码编码不一致。中文内容如果源文件是 GBK而QrCode按 UTF-8 解析就会乱码。解决方法是统一用 UTF-8 保存 PHP 文件并在构造QrCode时显式传encoding: new Encoding(UTF-8)。如果内容来自数据库先确认连接字符集是utf8mb4。另外内容过长也会导致识别失败二维码容量有限超长文本建议先缩短或改用短链。4.3 现象加了 Logo 后部分手机扫不出原因是 Logo 遮挡面积过大或纠错等级不够。解决方法是把纠错等级提到 HLogo 宽度控制在二维码宽度的 20% 以内并开启punchoutBackground。如果仍然扫不出把 Logo 换成更简洁的图形或者把 Logo 放到边角而不是正中心。实测中正中心遮挡对识别影响最大边角遮挡相对宽容。4.4 现象批量生成到一半脚本中断报内存超限原因是PhpSpreadsheet把整个 Excel 读进内存行数多时内存暴涨。解决方法是改用setReadDataOnly(true)只读数据或者用Reader的逐行读取模式。更彻底的做法是把 Excel 先导出成 CSV用fgetcsv逐行读内存占用极低。如果必须用 Excel在脚本开头加ini_set(memory_limit, 512M)只是缓解不是根治。4.5 现象生成的 PNG 在网页上显示模糊原因是尺寸设得太小又被 CSS 放大。二维码是位图放大必然模糊。解决方法是按最终显示尺寸的 2 倍生成比如网页显示 150 像素就生成 300 像素的图再用 CSS 缩到 150。打印场景直接生成 300 到 500 像素或者改用 SVG 输出矢量格式放大不失真。endroid/qr-code换SvgWriter即可代码结构不变。5. 进阶把本地生成做成可缓存、可验证的小服务5.1 用文件缓存避免重复生成同一个内容反复生成二维码是浪费。我一般会按内容哈希做缓存先算md5($content . $size . $level)如果缓存文件存在且未过期直接返回否则生成后写入缓存目录。这样批量任务重跑时几乎瞬间完成。缓存目录要放在 Web 根目录之外避免被直接访问清理策略可以按天数删除或者用touch更新时间做 LRU。参数变化时哈希会变所以尺寸和等级改了不会命中旧缓存这点比只按内容缓存更安全。5.2 生成后自检用解码库反向验证生成完不验证等于把风险留给用户。PHP 里可以用zxing的 PHP 移植或调用系统上的zbarimg做反向解码。简单做法是生成后调用命令行工具# 安装 zbar 工具后解码图片并输出内容 zbarimg --quiet --raw /var/www/qr-local/output/qr_0001.png如果输出内容和输入一致说明这张码可被标准解码器识别。批量场景可以写个循环把解码失败的文件列出来重新生成。这一步在打印前做一次能挡掉大部分「生成成功但扫不出」的问题。没有 zbar 的环境也可以用在线解码做抽样验证但内网场景还是本地工具更稳妥。5.3 一个我常犯的错忽略 PHP 版本与库版本的匹配早期我在 PHP 7.2 的环境里直接composer require endroid/qr-code装到了最新版结果运行时报语法错误因为新版用了 PHP 8 的构造器属性提升。后来养成习惯先看composer.json里的require约束再决定是否加版本号。如果服务器 PHP 版本低就在composer require endroid/qr-code:^4这样限定大版本或者先升级 PHP。这个坑不复杂但排查时容易往代码逻辑上想浪费不少时间。现在我的习惯是任何新库先在一个干净容器里跑通最小例子再往生产环境搬。希望帮到你。本文还有配套的精品资源点击获取
