Ubuntu 22.04 宝塔面板升级 PHP 8.2 失败排查实录：No package 'libjpeg' found 终极解决指南

在日常的服务器运维中，通过宝塔面板（aaPanel/BT-Panel）对 PHP 进行小版本安全升级是非常高频的操作。然而，在使用编译安装/更新模式时，往往会因为底层操作系统软件源或面板脚本的依赖遗漏，导致编译中断，甚至引发线上 PHP-FPM 服务意外停机的惊险状况。

本文将基于一次真实的生产环境运维案例——在 Ubuntu 22.04 LTS 系统下将 PHP 8.2.34 编译升级至 PHP 8.2.35 失败的完整日志，手把手带你复盘如何从上千行的解压与检查日志中精准定位核心报错、如何在第一时间恢复被脚本意外关闭的线上服务，以及如何彻底解决 libjpeg 依赖缺失问题。

一、 故障背景与现象还原

• 操作系统：Ubuntu 22.04 LTS (x86_64-pc-linux-gnu)
• 面板环境：宝塔 Linux 面板
• 操作内容：将已安装的 PHP 8.2（当前版本 8.2.34）通过面板更新至 8.2.35
• 故障现象：面板执行更新任务后，历经下载源码包、解压、预检查，最后突然抛出 ERROR: php-8.2.35 update failed.，同时面板提示“检测到为非常用系统安装”，升级宣告失败。

在排查这类编译失败问题时，很多新手容易被日志末尾的“套话”误导，甚至动了重装系统的念头。其实，只要我们顺着日志的时间线往下捋，就能轻松揪出幕后真凶。

二、 庖丁解牛：如何从万行日志中定位核心报错？

宝塔编译升级 PHP 的日志通常包含数千行（其中大部分是 tar 解压源码包的输出）。我们把日志拆解为四个阶段来分析：

1. 脚本下载与系统依赖预检阶段

日志开头显示，宝塔下载了安装脚本 php.sh，并调用 apt 检查了一系列编译所需的开发库：

libmcrypt-dev is already the newest version (2.5.8-7).
libsodium-dev is already the newest version (1.0.18-1ubuntu0.22.04.1).
...
g++ is already the newest version (4:11.2.0-1ubuntu1).
gcc is already the newest version (4:11.2.0-1ubuntu1).
libfreetype6-dev is already the newest version (2.11.1+dfsg-1ubuntu0.4).
libpng-dev is already the newest version (1.6.37-3ubuntu0.7).
libwebp-dev is already the newest version (1.2.2-2ubuntu0.22.04.2).

伏笔注意：请留意这里！脚本检查并确认安装了处理字体的 libfreetype6-dev、处理 PNG 的 libpng-dev 以及处理 WebP 的 libwebp-dev，但却唯独漏掉了处理 JPEG 图像的 libjpeg-dev。

2. 那些容易让人虚惊一场的“伪报错”

在下载完 php-8.2.35.tar.gz 并解压后，日志中出现了几行看似报错的信息：

cat: /www/server/panel/install/php/config.pl: No such file or directory
cat: /etc/redhat-release: No such file or directory
configure: WARNING: unrecognized options: --with-iconv-dir, --with-libxml-dir, --enable-inline-optimization, --with-xmlrpc

• config.pl 不存在：这是宝塔用于读取自定义编译参数的文件，没有自定义过则不存在，完全不影响流程。
• /etc/redhat-release 不存在：脚本在判断当前系统是否为 CentOS/RHEL 系，在 Ubuntu 系统下找不到该文件属于正常探测行为。
• unrecognized options 警告：从 PHP 7.4 / 8.0 开始，PHP 官方调整了许多 ./configure 参数（例如 --with-xmlrpc 移至 PECL，--with-libxml-dir 改为使用 pkg-config），宝塔为了兼容旧版沿用了旧参数，这里只是 WARNING（警告），并不会中断编译。

3. 致命一击：GD 扩展配置阶段的 pkg-config 报错

真正导致整个升级崩盘的地方，出现在 ./configure 检查扩展（Configuring extensions）的末尾阶段：

checking for GD support... yes
checking for external libgd... no
checking for libavif... no
checking for libwebp... yes
checking for libjpeg... yes
checking for libXpm... no
checking for FreeType 2... yes
checking whether to enable JIS-mapped Japanese font support in GD... no
checking for fabsf... yes
checking for floorf... yes
checking for zlib... yes
checking for libpng... yes
checking for libwebp >= 0.2.0... yes
checking for libjpeg... no
configure: error: Package requirements (libjpeg) were not met:

No package 'libjpeg' found

Consider adjusting the PKG_CONFIG_PATH environment variable if you
installed software in a non-standard prefix.

真相大白：
在开启 PHP 的 GD 图像处理扩展时，编译配置器通过 pkg-config 依次校验了 zlib、libpng、libwebp，全部顺利通过；但在校验 libjpeg 时，系统中没有安装对应的开发包（缺失 libjpeg.pc 及头文件），./configure 立即抛出 configure: error 并终止退出！

4. 连锁反应：为什么会报 No targets specified and no makefile found？

紧接着上面的报错，日志输出了最后几行：

make: *** No targets specified and no makefile found.  Stop.
Gracefully shutting down php-fpm . done
make: *** No rule to make target 'install'.  Stop.
========================================================
ERROR: php-8.2.35 update failed.

因为 ./configure 中途夭折，根本没有生成 Makefile 编译规则文件。而宝塔的自动化脚本并没有在 ./configure 失败时立即 exit，而是继续往下执行了 make、关闭正在运行的 php-fpm、以及 make install。

三、 紧急止损：第一时间恢复线上 PHP 服务！

仔细看上面日志中的这一行：

Gracefully shutting down php-fpm . done

这是宝塔更新脚本中非常危险的一个逻辑：不管前面编译有没有成功，在执行 make install 替换二进制文件前，脚本都会先把你现有的 PHP-FPM 服务停掉！ 如果随后安装失败退出，你的 PHP-FPM 就会一直处于停止状态，正在使用 PHP 8.2 的网站会直接报 502 Bad Gateway。

因此，在动手修补依赖之前，第一步永远是先恢复线上服务：

1. 启动原有的 PHP 8.2 服务

打开 SSH 终端（或宝塔面板左侧的“终端”），执行以下命令（也可以去 软件商店 -> PHP-8.2 -> 服务 中手动点击启动）：

/etc/init.d/php-fpm-82 start

2. 验证服务状态

执行以下命令检查进程是否已恢复：

ps aux | grep php-fpm-82

如果能看到一个 master process 和多个 php-fpm: pool www 工作进程，说明原有的 PHP 8.2.34 已经恢复正常工作，线上业务危机解除。接下来我们就可以从容地修复升级问题了。

四、 终极解决方案：补齐依赖并完成升级

既然明确了是因为缺少 libjpeg 的开发包及 pkg-config 描述文件，解决起来就非常直接了。以下提供两种方案，按顺序操作即可。

方案一：通过 APT 补齐 libjpeg-dev 依赖（首选方案）

在 Ubuntu 22.04 系统中，libjpeg-dev 是官方源提供的虚拟包，它会自动指向并安装底层的 libjpeg-turbo8-dev（包含头文件、静态/动态链接库以及至关重要的 libjpeg.pc 文件）。

步骤 1：更新软件源并安装开发包

在终端执行：

sudo apt-get update && sudo apt-get install -y libjpeg-dev libjpeg-turbo8-dev

步骤 2：验证 pkg-config 是否能识别 libjpeg

安装完成后，不要急着去点升级，先用 pkg-config 手动验证一下（这正是 PHP ./configure 内部执行的检查逻辑）：

pkg-config --modversion libjpeg
pkg-config --libs libjpeg

• 预期输出：第一条命令会输出具体的版本号（例如 2.1.2），第二条命令会输出 -ljpeg。只要不报错 No package 'libjpeg' found，就说明编译环境已经完全就绪！

步骤 3：重新执行 PHP 8.2 编译升级

你可以回到 宝塔面板 -> 软件商店 -> 已安装，找到 PHP-8.2 点击 更新；或者直接在终端中运行宝塔的官方升级命令（终端执行不仅速度感知更明显，还能实时观察日志）：

cd /www/server/panel/install && bash php.sh update 82

步骤 4：验证升级结果

等待编译和安装走完后，在终端执行以下命令查看当前 PHP 版本：

/www/server/php/82/bin/php -v

如果看到如下输出，恭喜你，升级大功告成！

PHP 8.2.35 (cli) (built: ...) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.35, Copyright (c) Zend Technologies

方案二：修复 PKG_CONFIG_PATH 环境变量（备用进阶方案）

如果你在极少数定制版系统或特殊镜像中，明明已经安装了 libjpeg-dev（或者曾经手动编译安装过 libjpeg），但运行编译时依然提示 No package 'libjpeg' found，这通常是因为 pkg-config 的默认搜索路径没有覆盖到 libjpeg.pc 所在的目录。

步骤 1：全局搜索 libjpeg.pc 的真实路径

在终端执行：

find /usr -name "libjpeg.pc" 2>/dev/null

在 Ubuntu 22.04 (x86_64) 下，标准路径通常为：

• /usr/lib/x86_64-linux-gnu/pkgconfig/libjpeg.pc
• 或者自定义编译路径 /usr/local/lib/pkgconfig/libjpeg.pc

步骤 2：临时注入环境变量并执行升级

将该文件所在的父目录添加到 PKG_CONFIG_PATH 环境变量中，然后直接在同一终端会话下运行宝塔升级脚本：

export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH
cd /www/server/panel/install && bash php.sh update 82

此时观察终端输出，当滚屏到 checking for libjpeg... 时，你会看到它顺利变成了 yes，随后生成 Makefile 并进入多核编译阶段。

五、 运维避坑总结与经验分享

通过这次 Ubuntu 22.04 下宝塔升级 PHP 8.2.35 的排障经历，我们可以提炼出以下几条实用的运维经验：

1. 学会抓编译日志的“牛鼻子”
   Linux 下源码编译遵循经典的三步走：./configure（配置检查并生成 Makefile） -> make（编译源码） -> make install（安装文件）。
   当你看到末尾报 make: *** No targets specified and no makefile found. Stop. 时，绝对不是 make 本身出了问题，而是上一步 ./configure 失败了。此时只需在日志中向上搜索关键词 configure: error:，就能在 3 秒内锁定真正的病因。
2. 警惕更新脚本的“停服陷阱”
   宝塔面板的许多更新脚本在进行覆盖安装前会先停止对应服务（如 Nginx、MySQL、PHP-FPM）。如果遇到更新失败，切记先去软件商店或终端确认服务是否处于运行状态，避免因为一次小版本升级失败导致网站长时间中断。

3. 极速安装 vs 编译安装怎么选？

   • 如果服务器没有特殊的源码级定制需求，日常在宝塔面板安装或大版本切换时，优先推荐使用极速安装（直接拉取预编译好的二进制包，耗时仅需几十秒，且不会受限于本地缺失某些 -dev 头文件包）。

   • 只有在进行小版本更新（宝塔面板内的“更新”按钮默认走源码编译更新）或需要特定编译参数时，才需要和 gcc、cmake、pkg-config 打交道。建议在 Ubuntu 服务器初始化时，提前安装好常见的图像与加密开发库全家桶：

     sudo apt-get install -y build-essential pkg-config libxml2-dev libssl-dev \
       libsqlite3-dev zlib1g-dev libcurl4-openssl-dev libpng-dev libwebp-dev \
       libjpeg-dev libfreetype6-dev libonig-dev libzip-dev libsodium-dev

     把这些基础 -dev 包备齐，以后无论编译升级哪个版本的 PHP，基本都能一路绿灯！

版权属于：soarli

本文链接：https://blog.soarli.top/archives/1192.html

转载时须注明出处及本声明。