Docker中用FrankenPHP运行Laravel Octane时类找不到错误排查

启动容器后日志频繁出现以下致命错误：

ERROR  PHP Fatal error:  Uncaught Error: Class "Laravel\Octane\Octane" not found in /app/vendor/laravel/octane/bin/bootstrap.php:24
Stack trace:
#0 /app/vendor/laravel/octane/bin/frankenphp-worker.php(19): require()
#1 /app/public/frankenphp-worker.php(3): require('...')
#2 {main}
  thrown in /app/vendor/laravel/octane/bin/bootstrap.php on line 24

容器会在一分钟内自动重启。

Dockerfile配置 #

FROM dunglas/frankenphp

ENV SERVER_NAME=mysite.com

RUN install-php-extensions pcntl

COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer

RUN apt-get update && \
    apt-get upgrade -y && \
    apt-get install -y git zip unzip nano && \
    rm -rf /var/lib/apt/lists//*

RUN docker-php-ext-install pdo pdo_mysql opcache

RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

COPY . /app

RUN mv /app/.env.prod /app/.env

RUN composer install \
    --no-interaction \
    --no-dev \
    --optimize-autoloader

RUN php artisan key:generate  \
    && php artisan config:clear \
    && php artisan config:cache \
    && php artisan route:cache \
    && php artisan view:cache \
    && php artisan event:cache \
    && php artisan storage:link

ARG USER=laravel

RUN addgroup -gid 1000 ${USER} && useradd -ms /bin/bash -g 1000 ${USER}

RUN setcap CAP_NET_BIND_SERVICE=+eip /usr/local/bin/frankenphp

RUN chown -R ${USER}:${USER} /data/caddy && chown -R ${USER}:${USER} /config/caddy

USER ${USER}

WORKDIR /app

docker-compose.yaml配置 #

version: "3.9"

services:
  app:
    image: "my_username/my_image:latest"
    entrypoint: php artisan octane:frankenphp
    restart: unless-stopped
    hostname: mysite.com
    ports:
      - "8002:8000"

已通过以下命令确认Octane类文件存在：

sudo docker exec app_1 ls -l /app/vendor/laravel/octane/src/Octane.php

1. 目录权限不匹配 #

Dockerfile中，composer install和artisan缓存命令均以root用户执行，生成的vendor目录、自动加载缓存文件（vendor/composer/下的文件）以及框架缓存文件（bootstrap/cache/目录）所有者为root。但容器最终以laravel普通用户运行，导致该用户无法正常读取或执行这些缓存文件，进而使自动加载器找不到Octane类。

解决方法：
在切换用户前，修改/app目录的所有者为laravel用户：

# 在 USER ${USER} 之前添加
RUN chown -R ${USER}:${USER} /app

2. 自动加载缓存与运行环境不兼容 #

构建阶段用root用户生成的优化自动加载缓存（--optimize-autoloader），和普通用户运行时的环境存在兼容性差异，导致自动加载器无法正确解析类路径。

解决方法：

• 切换到laravel用户后重新生成自动加载缓存：

USER ${USER}
WORKDIR /app
RUN composer dump-autoload --optimize

• 或提前切换到laravel用户执行所有构建命令，避免权限和环境差异：

# 提前创建并切换用户
ARG USER=laravel
RUN addgroup -gid 1000 ${USER} && useradd -ms /bin/bash -g 1000 ${USER}
USER ${USER}
WORKDIR /app

# 后续命令以laravel用户执行
COPY --chown=${USER}:${USER} . /app
RUN mv /app/.env.prod /app/.env
RUN composer install --no-interaction --no-dev --optimize-autoloader
RUN php artisan key:generate && php artisan config:clear && php artisan config:cache && php artisan route:cache && php artisan view:cache && php artisan event:cache && php artisan storage:link

3. Octane启动方式不正确 #

当前docker-compose使用php artisan octane:frankenphp作为启动命令，但FrankenPHP官方集成Laravel Octane的推荐方式是直接使用frankenphp run命令，该命令会自动加载Octane配置并启动服务，可避免artisan命令加载时的类路径问题。

解决方法：
修改docker-compose的entrypoint：

entrypoint: frankenphp run

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