配置PHP应用AWS Lambda环境的入口点问题排查

你遇到的entrypoint requires the handler name to be the first argument错误，本质是Docker CMD的传参格式和Bref基础镜像的入口逻辑不匹配：

• 你当前写的CMD _HANDLER=index.php /opt/bootstrap是shell格式的CMD，Docker启动容器时会自动把这行命令包装成/bin/sh -c "_HANDLER=index.php /opt/bootstrap"传给镜像预置的ENTRYPOINT脚本。
• Bref镜像内置的入口脚本校验规则为：接收到的第一个启动参数必须是handler名称，拿到合法参数后它会自动调用/opt/bootstrap启动运行时。你当前配置下入口脚本收到的第一个参数是/bin/sh，完全不符合参数要求，直接触发报错。

关键配置含义澄清 #

• /opt/bootstrap：Bref提前编译打包的Lambda自定义运行时二进制启动文件，是容器内对接Lambda服务的核心进程：负责和Lambda运行时API通信拉取触发事件、管理PHP-FPM进程生命周期、转发请求给PHP业务代码、把执行结果回传给Lambda，是容器启动后的实际运行时入口，不需要自行编写或修改。
• _HANDLER=index.php：传递给bootstrap进程的环境变量，用来指定业务代码的入口PHP文件路径，bootstrap启动后默认会到/var/task目录下查找对应文件加载执行。

• 修正Dockerfile配置，二选一即可：
  • 方案1（推荐，适配Bref镜像的预设逻辑）：利用镜像内置的入口规则，不需要手动调用bootstrap，避免参数传递错误

    FROM bref/php-80-fpm
    # 该镜像已预装Composer，无需重复执行安装脚本
    COPY . /var/task
    # 安装项目依赖，若composer.json已声明bref/bref依赖无需单独require
    RUN composer install --no-dev
    # 声明handler环境变量
    ENV _HANDLER=index.php
    # 直接传入口文件名给内置ENTRYPOINT即可
    CMD ["index.php"]
    

  • 方案2（手动指定bootstrap启动）：使用exec格式的CMD，避免shell包装导致参数错位

    FROM bref/php-80-fpm
    RUN curl -s https://getcomposer.org/installer | php
    RUN php composer.phar require bref/bref
    COPY . /var/task
    # 用JSON数组格式声明启动命令，确保参数正确传递
    CMD ["/bin/sh", "-c", "_HANDLER=index.php /opt/bootstrap"]
    

• 本地预校验（无需推送到Lambda即可排查问题）
  镜像构建完成后，本地执行docker run -p 9000:8080 你的镜像标签启动容器，再发送POST请求到http://localhost:9000/2015-03-31/functions/function/invocations，如果能正常返回PHP执行结果，说明配置正确。
• 路径校验
  确认你的index.php放在项目根目录，构建时会被正确复制到容器内的/var/task/index.php路径，避免bootstrap找不到入口文件。

注意：不要在Dockerfile里重复安装Bref依赖或Composer，bref/php-80-fpm镜像已经预装了匹配版本的运行时文件，重复安装可能触发版本兼容问题。

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