Class not found 在 Hyperf 中90%是因 vendor 目录属主为 root 或入口未引入 vendor/autoload.php；需检查 ls -ld vendor 权限、确认 bin/hyperf.php 首行 require_once，以及 Docker/CI 中用户与归属一致性。
Hyperf 项目报 Class not found，90% 不是类写错了，而是 vendor 目录归属权被 root 占了，或者 vendor/autoload.php 根本没被引入。
vendor 目录属主是 root，Swoole 进程直接拒绝加载
Hyperf 启动时用的是非 root 用户（比如 www-data 或自定义 UID），但 composer install 是在 root 下执行的，导致整个 vendor/ 目录及其子项属主为 root:root。Swoole 子进程无法读取或执行其中文件，报错如：file_put_contents(/path/to/project/vendor/autoload.php): Failed to open stream: Permission denied。
- 立刻执行
ls -ld vendor—— 若输出开头是drwxr-xr-x 12 root root，问题锁定 - 别用
chmod -R 777 vendor，它不解决归属问题，还可能破坏 Phar 包或符号链接 - 推荐操作：先确认当前用户名（
whoami），再运行sudo chown -R $USER:$USER vendor/ - 特别注意
vendor/bin/hyperf.php必须有执行权限：chmod +x vendor/bin/hyperf.php
public/index.php 或入口脚本漏引 vendor/autoload.php
Hyperf 默认入口是 bin/hyperf.php，但如果你改过启动方式（比如用 php public/index.php），就极容易漏掉自动加载入口。没有这行，所有 vendor 类都不可见，哪怕权限完全正确。
- 检查
bin/hyperf.php开头是否含：require_once __DIR__.'/../vendor/autoload.php'; - 若你自建了 Web 入口（如
public/index.php），必须手动加这行，且路径要对：require_once __DIR__.'/../vendor/autoload.php';（不能写成./vendor/autoload.php） - 运行
php -l vendor/autoload.php确认该文件语法无误；若报错，说明vendor/被删过半或composer install中断过
Docker 或 CI 环境中 vendor 权限更隐蔽
宿主机挂载目录进容器后，默认属主是 root，而容器内以非 root 用户（如 UID 1001）运行 Hyperf，vendor/ 就变成“可看不可读”。这类问题在本地开发不显，在 CI 流水线或 docker-compose up 时突然爆发。
- 构建镜像时，应在
Dockerfile中明确切换用户后再装依赖：RUN chown -R www-data:www-data /app && su www-data -c "composer install" - 若用 volume 挂载源码，避免挂载整个项目根目录；改用
rsync或COPY复制代码，再chown目录 - CI 脚本里加校验步骤：
ls -ld vendor composer.lock | grep -q "$(whoami)" || (echo "vendor ownership wrong" && exit 1)
真正难排查的不是报错本身，而是错误发生在哪一层：是 vendor/ 归属不对、autoload.php 没 require、还是 composer.lock 和实际 vendor/ 内容已脱节——这三个点必须逐个排除，少一个都会白调半天。
