GD 是 PHP 底层扩展，需系统启用而非 Composer 安装；Linux 用 apt install php-gd、macOS 用 brew install php@x-gd、Windows 取消 php.ini 中 ;extension=gd 注释，再重启服务并验证 php -m | grep gd。
GD 库不是 Composer 能“安装”的东西，它是 PHP 的底层扩展，必须先在系统里启用，Composer 只能装基于它的封装库（比如 intervention/image）。
PHP 环境里 GD 扩展没开，装了库也没用
很多同学跑 composer require intervention/image 成功了，一调 Image::make() 就报 Class 'GdImage' not found 或 Call to undefined function imagecreatefromstring()——这说明 PHP 根本没加载 GD。
- Linux（如 Ubuntu）：运行
sudo apt install php-gd，然后重启 Web 服务（sudo systemctl restart apache2或sudo systemctl restart php8.1-fpm） - macOS（Homebrew + PHP）：用
brew install php@8.2-gd（版本号对齐你当前的 PHP），再改php.ini确保有extension=gd - Windows（XAMPP/WAMP）：打开
php.ini，取消注释;extension=gd这一行，重启 Apache - 验证是否生效：终端执行
php -m | grep gd，或写个phpinfo()页面搜 “gd”
装 intervention/image 时得选对驱动和版本
这个库默认优先用 GD，但如果你系统里 GD 没开、而 Imagick 又装了，它会自动 fallback 到 Imagick——行为不一致，调试时容易懵。
- 强制指定 GD 驱动：在配置里加
'driver' => 'gd'，避免静默切换 - PHP 8.1+ 用户注意：
intervention/imagev2 不支持 PHP 8.1+ 的 GD 新类型（GdImage），必须升到 v3（composer require intervention/image:^3.0） - v3 默认返回
GdImage实例，不能直接 echo 或赋值给旧代码里的resource变量，否则报Trying to access array offset on value of type bool - 示例兼容写法：
$img = Image::make($path)->resize(300, null, function ($constraint) { $constraint->aspectRatio(); }); $img->toJpeg(80)->stream();
本地开发和生产环境 GD 状态不一致，CI 会挂
Docker 或 GitHub Actions 里常漏掉 GD，导致测试通过、上线就炸。
- Dockerfile 里别只写
FROM php:8.2-apache，得显式装扩展：RUN docker-php-ext-install gd - Laravel Sail 用户：在
.env里确认SAIL_PHP_VERSION=8.2，再sail up --build重构建 - GitHub Actions：PHP setup 步骤要加
extensions: [gd]，否则默认不带 - 部署后快速验证：在项目里临时加个路由，返回
extension_loaded('gd')的布尔值
GD 是开关型依赖，不是版本型依赖——开了就是开了，关了怎么 composer update 都没用。最容易被忽略的是 Docker 和 CI 环境里那一行 docker-php-ext-install gd，漏了它，所有图片逻辑都只是本地幻觉。
