宝塔PHP GD库添加原生AVIF支持并编译开启imageavif函数详细教程

在上一篇关于网页加载速度深度优化策略的文章中，我们提到了图像是影响网站加载速度和性能的最大杀手，并建议全面弃用PNG/JPG格式的图像，同时推荐使用Webp格式或者AVIF格式的图片，AVIF凭借比WebP更优秀的压缩率（体积往往减少20%-30%），已成为2025年高性能网站的标配。

然而，许多使用宝塔面板的用户发现一个痛点：默认“一键安装”的PHP 8.3，其GD库竟然不支持AVIF！
这是因为宝塔官方的编译脚本为了兼容性，默认未开启--with-avif参数。如果你尝试在PHP中使用imageavif()函数，只会得到“Function not defined”的错误。

一、环境准备与核心原理

1. 环境准备

操作系统：Debian、Ubuntu、CentOS，建议安装最新版。
面板版本：应该不限制，还是建议最新版。
目标PHP版本：PHP 8.3（PHP 8.1+均支持，但8.3性能最佳）。

2. 核心原理

宝塔面板安装PHP的本质是运行一个Shell脚本（php.sh），下载源码并执行./configure进行配置。要开启支持，我们需要：

系统层：安装Linux系统的AVIF编解码库（libavif）。
配置层：拦截安装脚本，手动注入--with-avif编译参数。
编译层：通过命令行强制重编译。

二、完整实战操作流程

第一步：安装系统底层依赖库

PHP的GD库依赖操作系统的动态链接库。如果系统里没有libavif-dev，即使开启了参数也会编译失败。

通过SSH连接服务器，根据你的操作系统执行以下命令：
Debian/Ubuntu 系统：

sudo apt update
sudo apt install libheif-dev libavif-dev libyuv-dev

CentOS 系统：

# 先确保已安装EPEL仓库
sudo yum install epel-release
sudo yum install libheif-devel libavif-devel libyuv-devel

注：如果yum提示找不到libavif-devel包，可能是因为镜像源问题。你可以尝试从源码编译这些库，或更换系统镜像源。

第二步：编译安装Nginx环境

我们需要先按常规流程编译Nginx环境，以便宝塔自动生成编译脚本文件。

登录宝塔面板，进入“软件商店”。
搜索Nginx，选择自己需要的版本。
选择编译安装 Nginx（建议1.24+）。

注意：Nginx环境必须选择编译安装，我已经安装了Nginx，无法演示，以PHP为例：

第三步：编译安装PHP8.1+

PHP必须8.1以上，这里我以PHP8.3为演示。

登录宝塔面板，进入“软件商店”。
搜索PHP，选择PHP8.3。
选择编译安装PHP8.3。

注意：PHP必须选择编译安装。

不管是Nginx环境编译安装还是PHP编译安装，整个安装流程很长，可能需要20~60分钟时间，耐心等待。

第四步：修改PHP编译脚本

这是最核心的一步。我们需要编辑脚本，手动把AVIF参数加进去。

编译脚本：

# 使用vim或nano编辑php.sh
sudo vim /www/server/panel/install/php.sh

# 如果你不熟悉vim，可以使用nano：
sudo nano /www/server/panel/install/php.sh

当然，你也可以直接在宝塔面板按照/www/server/panel/install/php.sh路径找到php.sh文件进行修改。

定位PHP8.3配置模块：
你需要通过搜索"${version}" == "8.3" 字符定位到PHP8.3配置模块。

然后你会看到下图所示，如果你的PHP版本为8.2，则需将文中的‘8.3’替换为‘8.2’。

找到--with-webp参数：
跟上面图片中的一样，搜索 --with-webp 参数，在后面添加 --with-avif 。

修改前的代码：

--with-sodium=/usr/local/libsodium --with-webp ${i_make_args}

修改后的代码：

--with-sodium=/usr/local/libsodium --with-webp --with-avif ${i_make_args}

修改后保存退出即可。

第五步：通过命令强制重编译

警告：不要在宝塔网页端点“重装”！必须通过命令在SSH终端安装。

请在SSH终端执行以下命令：

sudo bash /www/server/panel/install/php.sh install 83

整个过程很长，会持续20~50分钟不等，如果耐心等待。

当看到Starting php-fpm done或命令提示符重新出现且无报错时，表示安装完成。

如果你看到面板窗口卡着不动或者一直重复执行命令时，这是正常现象，只要CPU和内存在高占用、波动幅度大就没问题。

三、验证安装结果

为了确保万无一失，我们需要创建一个PHP脚本来检测GD库的实际状态。

在网站根目录创建一个avif_check.php的文件，复制下面代码粘贴到文件中保存。

<?php
// 保存为 avif_check.php
$gd_info = gd_info();

echo "<h2>AVIF支持验证</h2>";

// 检查AVIF支持
if (isset($gd_info['AVIF Support']) && $gd_info['AVIF Support']) {
    echo '<p style="color: green; font-weight: bold;">✅ GD库已启用AVIF支持</p>';
} else {
    echo '<p style="color: red; font-weight: bold;">❌ GD库未启用AVIF支持</p>';
}

// 检查imageavif函数
if (function_exists('imageavif')) {
    echo '<p style="color: green; font-weight: bold;">✅ imageavif()函数可用</p>';
} else {
    echo '<p style="color: red; font-weight: bold;">❌ imageavif()函数不可用</p>';
}

// 显示完整的GD库信息（可选）
echo "<h3>GD库完整信息</h3>";
echo "<pre>";
print_r($gd_info);
echo "</pre>";
?>

访问http://你的域名/avif_check.php，如果看到下图所示则表示成功。