Debian系统ThinkPHP依赖包管理

Debian 上 ThinkPHP 的依赖包管理

一 管理边界与总体原则

• 将依赖分为两类并分别管理：
  • 系统级依赖：由 APT 管理的 PHP 运行时与扩展（如 php-fpm、php-mysql、php-mbstring、php-xml、php-curl、php-gd、php-zip、php-bcmath、php-opcache 等），提供数据库、字符集、网络、压缩、调试等底层能力。
  • 框架与业务依赖：由 Composer 管理的 Packagist 包（如 topthink/framework、topthink-orm、league/uri 等），提供框架核心、ORM、URI 处理等上层能力。
• 原则：能用系统仓库安装的扩展优先用 APT；框架与第三方库统一用 Composer，避免混用包来源导致版本冲突与不可维护。

二 系统级依赖管理 APT

• 更新索引与基础安装：
  • 更新索引：sudo apt update
  • 安装常用组件：sudo apt install php php-cli php-fpm php-mysql php-mbstring php-xml php-curl php-gd php-zip php-bcmath php-opcache
• 按需扩展与搜索：
  • 搜索扩展：apt-cache search php-
  • 安装扩展：sudo apt install php-
• 多版本并存与指定版本：
  • 如需 PHP 8.2（Debian 默认仓库版本偏旧时），可添加 Ondřej Sur 仓库后安装对应版本与扩展（如 php8.2、php8.2-fpm、php8.2-mbstring 等）。
• 使配置生效与验证：
  • 重启服务：sudo systemctl restart php8.2-fpm 或 sudo systemctl restart apache2
  • 验证扩展：创建 /var/www/html/info.php 输出 phpinfo()，或在 CLI 执行 php -m | grep 。

三 框架与业务依赖管理 Composer

• 安装 Composer（全局）：
  • curl -sS https://getcomposer.org/installer | php
  • sudo mv composer.phar /usr/local/bin/composer
• 创建项目与安装依赖：
  • 新建项目：composer create-project topthink your_project_name
  • 进入目录后安装/更新：composer install 或 composer update
• 常见框架与库示例（出现在实际项目依赖中）：
  • 框架核心：topthink/framework
  • ORM：topthink-orm
  • 多应用支持：topthink-multi-app
  • URI 处理：league/uri（注意其要求 PHP >= 8.1，且处理 IDN 主机名需要 intl 扩展或 symfony/polyfill-intl-idn 兼容库）

四 版本匹配与扩展要点

• PHP 版本匹配：
  • 若使用 league/uri 等要求 PHP >= 8.1 的库，需确保系统安装并启用了 PHP 8.1+（可通过添加 Ondřej Sur 仓库获取所需版本）。
• 扩展与库对应关系（示例）：
  • 多字节字符串：mbstring（系统包） ↔ symfony/polyfill-mbstring（Composer 兼容库，低版本 PHP 环境常用）
  • 国际化与 IDN：intl（系统包） ↔ symfony/polyfill-intl-idn（Composer 兼容库）
  • URI 处理：league/uri（Composer 库，需 intl 或对应 polyfill 支持）
• 原则：优先用系统包提供扩展；当系统 PHP 版本较低或缺少扩展时，使用 polyfill 兼容库，再通过 Composer 管理。

五 部署与运维要点

• Web 服务与 FPM：
  • Nginx + PHP-FPM 为常见组合；FPM 需与 CLI 的 PHP 版本一致（如 php8.2-fpm 对应 PHP 8.2）。
• 路由与重写：
  • Nginx 配置需包含：try_files $uri $uri/ /index.php?$query_string;
  • Apache 需启用 mod_rewrite 并配置 .htaccess 规则。
• 目录权限与运行用户：
  • 建议以 www-data 运行（或项目实际运行用户），如：sudo chown -R www-data:www-data /var/www/html/your_project
• 故障排查：
  • 502 Bad Gateway：检查 PHP-FPM 是否运行、FPM 监听套接字路径是否与 Nginx 配置一致（如 /var/run/php/php8.2-fpm.sock）。
  • 路由失效：确认 PATHINFO 已启用且 try_files 规则正确。