Laravel项目GitLab CI/CD部署生产环境时依赖兼容问题求助

在通过GitLab CI/CD部署Laravel项目到Linux VPS时，执行composer install遇到依赖错误，具体报错如下：

Installing dependencies from lock file (including require-dev)
    Verifying lock file contents can be installed on current platform.
    Your lock file does not contain a compatible set of packages. Please run composer update.
      Problem 1
        - phpoffice/phpspreadsheet is locked to version 1.24.1 and an update of this package was not requested.
        - phpoffice/phpspreadsheet 1.24.1 requires ext-gd * -> it is missing from your system. Install or enable PHP's gd extension.
      Problem 2
        - simplesoftwareio/simple-qrcode is locked to version 4.2.0 and an update of this package was not requested.
        - simplesoftwareio/simple-qrcode 4.2.0 requires ext-gd * -> it is missing from your system. Install or enable PHP's gd extension.
      Problem 3
        - phpoffice/phpspreadsheet 1.24.1 requires ext-gd * -> it is missing from your system. Install or enable PHP's gd extension.
        - maatwebsite/excel 3.1.40 requires phpoffice/phpspreadsheet ^1.18 -> satisfiable by phpoffice/phpspreadsheet[1.24.1].
        - maatwebsite/excel is locked to version 3.1.40 and an update of this package was not requested.

当前使用的.gitlab-ci.yml脚本片段：

script:
    - ssh $VAR_USER@$VAR_IP "git config --global safe.directory '*'"
    - ssh $VAR_USER@$VAR_IP "if [ ! -d $VAR_DIREKTORI/.git ]; then echo 'Project belum ditemukan di direktori $VAR_DIREKTORI' && cd $VAR_DIREKTORI && git clone https://oauth2:$VAR_CLONE_KEY@$VAR_GIT_URL_TANPA_HTTP .; fi"
    - ssh $VAR_USER@$VAR_IP "cd $VAR_DIREKTORI && git pull origin master && exit"
    - ssh $VAR_USER@$VAR_IP "if [ -d $VAR_DIREKTORI/.env ]; then rm .env; fi"
    - ssh $VAR_USER@$VAR_IP "cd $VAR_DIREKTORI && echo '$VAR_FILE_ENV' >> .env"
    - ssh $VAR_USER@$VAR_IP "if [ -d $VAR_DIREKTORI/.htaccess ]; then rm .htaccess; fi"
    - ssh $VAR_USER@$VAR_IP "cd $VAR_DIREKTORI && echo '$VAR_FILE_HTACCESS' >> .htaccess"
    - ssh $VAR_USER@$VAR_IP "docker exec webserver composer install"
    - ssh $VAR_USER@$VAR_IP "docker exec webserver composer update"
    - ssh $VAR_USER@$VAR_IP "docker exec webserver php artisan migrate"
    - ssh $VAR_USER@$VAR_IP "docker exec webserver php artisan db:seed"
    - ssh $VAR_USER@$VAR_IP "docker exec webserver php artisan key:generate"
    - echo "Done!"

尝试过执行composer update但错误依然存在，请问该如何解决？

核心问题是你的webserver容器中缺少PHP的GD扩展，composer update无法解决扩展缺失的问题——它只负责管理PHP包，不处理系统级扩展的安装。以下是具体解决步骤：

1. 先在容器内安装GD扩展 #

根据容器的基础镜像类型，执行对应安装命令：

Ubuntu/Debian系镜像 #

# 在CI脚本中添加该步骤，或直接进入容器执行
docker exec webserver apt-get update && apt-get install -y php-gd
# 若为特定PHP版本，需调整包名，例如php8.1-gd

Alpine系镜像 #

docker exec webserver apk add --no-cache php-gd
# 对应特定PHP版本调整，例如php81-gd

安装完成后重启容器，让扩展生效：

docker restart webserver

2. 调整CI脚本执行顺序 #

当前脚本先执行composer install触发lock文件校验错误，建议先安装扩展，再处理依赖：

# 新增：先安装GD扩展并重启容器
- ssh $VAR_USER@$VAR_IP "docker exec webserver apt-get update && apt-get install -y php-gd"
- ssh $VAR_USER@$VAR_IP "docker restart webserver"
# 替换原有的composer命令，优先用install（依赖lock文件）
- ssh $VAR_USER@$VAR_IP "docker exec webserver composer install --optimize-autoloader"
# 若确实需要更新依赖，建议在本地测试后提交新的lock文件到仓库，再执行install，而非直接在生产环境update
# - ssh $VAR_USER@$VAR_IP "docker exec webserver composer update"

3. 长期解决方案：修改Dockerfile #

如果是自定义webserver镜像，直接在Dockerfile中添加GD扩展安装步骤，避免每次部署重复操作：

Ubuntu/Debian系Dockerfile示例 #

RUN apt-get update && apt-get install -y \
    php-gd \
    && rm -rf /var/lib/apt/lists/*

Alpine系Dockerfile示例 #

RUN apk add --no-cache php-gd

重新构建镜像并替换现有容器，后续部署将不再出现扩展缺失问题。

额外提示 #

• 不要在生产环境随意执行composer update，这可能更新依赖到不兼容版本导致项目崩溃。正确流程是：本地执行composer update测试通过后，提交更新后的composer.lock到Git仓库，生产环境执行composer install。
• 检查容器内PHP版本，确保安装的GD扩展与PHP版本匹配（如PHP8.0对应php8.0-gd）。

内容的提问来源于stack exchange，提问作者owf