Debian下PHP扩展如何安装

Debian 下 PHP 扩展安装指南

一 准备与版本确认

• 更新索引并确认 PHP 版本 与 SAPI（如 Apache 模块 或 PHP-FPM）：
  • 更新包列表：sudo apt update
  • 查看版本：php -v
  • 查看已加载 SAPI：php -m | grep -i apache2handler 或 ps aux | grep php-fpm
• 若系统源中 PHP 版本较旧 或需要多版本并存，可添加 Ondřej Surý 的 PHP 仓库（Debian 12 常用）：
  • 安装工具：sudo apt install -y ca-certificates lsb-release apt-transport-https
  • 导入 GPG：wget -qO - https://packages.sury.org/php/apt.gpg | sudo gpg --dearmor -o /usr/share/keyrings/php-archive-keyring.gpg
  • 写入源：echo "deb [signed-by=/usr/share/keyrings/php-archive-keyring.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list > /devref
  • 更新索引：sudo apt update
• 使用 Nginx + PHP-FPM 时，需安装对应版本的 FPM，例如：sudo apt install php8.2-fpm。

二 安装方式一 APT 安装常用扩展（推荐）

• 语法：sudo apt install php-[扩展名]；多版本并存时显式指定版本，例如 PHP 8.2：sudo apt install php8.2-[扩展名]。
• 常用扩展示例：
  • 数据库与连接：sudo apt install php-mysql php-pdo php-curl
  • 图像处理：sudo apt install php-gd
  • 数据与编码：sudo apt install php-xml php-mbstring php-zip php-opcache
• 安装完成后重启服务：
  • Apache：sudo systemctl restart apache2
  • PHP-FPM：sudo systemctl restart php8.2-fpm（按需替换为你的版本）
• 验证：
  • 命令行：php -m | grep -iE 'curl|gd|mysql|mbstring|zip|opcache'
  • 或创建 /var/www/html/info.php：<?php phpinfo(); ?> 并访问 http://服务器IP/info.php 搜索扩展名。

三 安装方式二 PECL 安装（仓库缺失或需新版本时）

• 安装工具链：sudo apt install -y php-pear php-dev
• 安装扩展（示例为 redis）：sudo pecl install redis
• 启用扩展：
  • 常见做法：在 /etc/php/8.2/mods-available/ 创建 redis.ini，写入 extension=redis.so，然后用 sudo phpenmod redis 启用；或直接在对应 php.ini 加入 extension=redis.so
• 重启服务：sudo systemctl restart apache2 或 sudo systemctl restart php8.2-fpm
• 验证：php -m | grep redis。

四 安装方式三 编译安装与 Docker 场景

• 编译安装通用步骤（适用于官方扩展源码或 PECL 下载包）：
  • 准备：sudo apt install -y php-dev build-essential
  • 解压并进入扩展目录：tar xzf extension.tar.gz && cd extension
  • 构建安装：

    phpize
    ./configure
    make -j$(nproc)
    sudo make install
    

  • 在 php.ini 加入 extension=extension.so，重启服务并验证 php -m
• Docker（php:*-fpm 镜像）常用快捷命令：
  • 内置快捷：docker-php-ext-install gd pdo_mysql mysqli zip bcmath opcache pcntl
  • 依赖示例（gd）：apt-get update && apt-get install -y libwebp-dev libjpeg-dev libpng-dev libfreetype6-dev
  • PECL 扩展：pecl install redis && docker-php-ext-enable redis
  • 验证：php -r 'print_r(gd_info());'（以 gd 为例）。

五 常见问题与排错

• 扩展安装了但 php -m 看不到：确认安装到正确的 PHP 版本目录（如 /usr/lib/php/20220829/），并在对应 SAPI 的 php.ini 或 /etc/php/8.2/mods-available/ 正确启用；使用 phpenmod 后重启服务。
• 找不到包或版本不匹配：优先使用 Ondřej Surý 仓库 获取新版本；多版本并存时务必指定如 php8.2- 前缀。
• 编译失败：安装对应 -dev 依赖（如 php-dev、libzip-dev、libpng-dev 等），确保 phpize 与头文件可用。
• 服务未生效：重启 Apache 或 PHP-FPM；Nginx 场景同时确认 php-fpm 与 nginx 均已重启。
• 生产建议：优先使用 APT 管理扩展；PECL/编译 仅用于仓库缺失或特定版本需求，变更前做好配置与扩展的备份与回滚方案。