Docker构建Symfony PHP项目执行composer/npm命令报错排查

以下问题按报错顺序逐个修复，调整后即可正常完成镜像构建：

• 修复PHP扩展缺失问题
  原有配置仅安装了pdo_mysql扩展，缺少Composer必需的zip扩展与unzip命令，才会出现反复提示跳过dist包、从源码克隆依赖的警告，大幅拖慢构建速度。在PHP扩展安装步骤中追加zip扩展，同时通过apt安装unzip即可解决。
• 替换系统默认源的Node.js版本
  Debian默认软件源内置的Node.js版本过旧（通常为12.x），和node-sass等原生前端模块版本不兼容，会导致依赖安装后可执行文件缺失、运行报127错误。不要直接用apt安装源内的nodejs/npm，改用NodeSource提供的长期支持版Node.js（推荐18.x/20.x），同时安装build-essential、python3等原生模块编译依赖，保证node-sass可以正常完成二进制编译安装。
• 修正NPM脚本执行逻辑
  • 绝对不要在镜像构建阶段执行npm run watch：watch是文件监听常驻进程，启动后会持续运行不会主动退出，就算修复了命令找不到的问题，构建流程也会永久卡在这一步无法完成。构建阶段仅允许执行一次性运行、执行完自动退出的命令，比如前端资源编译命令。
  • 构建日志中出现的missing script: build报错是因为项目package.json内没有定义build脚本，需要自行在scripts配置中添加前端资源编译对应的命令（比如sass编译、静态资源压缩逻辑），如果是开发环境需要用watch热更新，把该命令放到容器启动脚本中，不要写在构建阶段的RUN指令里。
• 优化Composer执行参数
  构建阶段临时添加COMPOSER_ALLOW_SUPERUSER=1环境变量即可关闭root用户运行Composer的警告，同时给composer命令添加--no-interaction --no-progress --optimize-autoloader参数，适配非交互式构建环境，避免构建过程中卡住等待用户输入。
• 优化构建缓存（可选，大幅提升反复构建的速度）
  复制项目文件时，优先复制composer.json、composer.lock、package.json、package-lock.json四个依赖描述文件，先执行依赖安装步骤，再复制全量项目代码，这样后续修改业务代码时不会触发依赖重新安装，充分利用Docker的层缓存。

FROM php:8.1-apache

# 安装PHP扩展安装工具
ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/
RUN chmod +x /usr/local/bin/install-php-extensions && \
    install-php-extensions pdo_mysql zip intl opcache

# 安装Composer
RUN curl -sSk https://getcomposer.org/installer | php -- --disable-tls && \
    mv composer.phar /usr/local/bin/composer

# 安装系统依赖、Node.js 20.x、unzip
RUN apt-get update && apt-get upgrade -y && \
    apt-get install -y --no-install-recommends ca-certificates curl gnupg unzip build-essential python3 && \
    mkdir -p /etc/apt/keyrings && \
    curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
    echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && \
    apt-get update && \
    apt-get install -y --no-install-recommends nodejs && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# 先复制依赖配置文件，利用构建缓存
COPY composer.json composer.lock package.json package-lock.json /var/www/
WORKDIR /var/www

# 安装PHP依赖
RUN COMPOSER_ALLOW_SUPERUSER=1 composer install --no-interaction --no-progress --optimize-autoloader

# 安装前端依赖
RUN npm install

# 复制全量项目代码
COPY . /var/www/
# 复制Apache配置
COPY ./docker/apache.conf /etc/apache2/sites-available/000-default.conf

# 如已在package.json中配置build脚本，取消下一行注释执行前端编译
# RUN npm run build

# 配置Apache重写规则、目录权限（Symfony必需）
RUN a2enmod rewrite && \
    chown -R www-data:www-data /var/www

补充说明：如果项目不需要在构建阶段编译前端资源，可以直接注释掉npm run build步骤，在容器启动后根据开发/生产需求手动执行对应脚本即可。老项目如果使用node-sass出现兼容性问题，建议替换为官方推荐的dart-sass（即sass npm包），无需本地编译，兼容性更好。

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