hyperf 权限错误主因是部署环境文件系统权限配置不当，需确保swoole进程用户对runtime、storage、vendor等目录有读写权限，并避免root执行composer，容器中需显式设置用户或预设目录权限。
Hyperf 应用运行时报权限错误，多数不是框架本身问题，而是部署环境的文件系统权限配置不当。核心要确认两点：Web 服务（如 Swoole 进程）运行用户对缓存目录、日志目录、运行时生成文件（如代理类、AOP 切面）是否有读写权限；Composer 安装依赖后生成的 vendor 目录是否被限制了执行或写入。
检查 Swoole 进程运行用户与目录归属
Hyperf 默认通过 Swoole 启动，进程通常以非 root 用户（如 www-data、nginx、nobody 或自定义用户）运行。若项目目录属主是 root 或开发用户，Swoole 进程很可能无权写入 runtime/、storage/ 等目录。
- 用 ps aux | grep swoole 查看实际运行用户
- 执行 ls -ld runtime storage 确认目录属主和权限（建议至少为 755，属主可读写）
- 若属主不匹配，用 sudo chown -R www-data:www-data runtime storage（按实际用户调整）
修复 Composer 安装后 vendor 权限异常
在 root 下执行 composer install 会导致 vendor 中部分脚本（如 bin 文件）属主为 root，Swoole 进程无法加载或执行某些扩展类。尤其在 Docker 或 CI/CD 环境中容易复现。
- 避免用 root 执行 composer 命令；推荐在构建镜像或部署脚本中指定用户：sudo -u www-data composer install --no-dev --optimize-autoloader
- 若已发生，可重设 vendor 权限：sudo chown -R www-data:www-data vendor
- 检查 vendor/bin/hyperf.php 是否有执行权限（chmod +x vendor/bin/hyperf.php）
清理并重建运行时缓存目录
权限错误常伴随 “Permission denied” 写入 runtime/container 或 runtime/proxy，导致后续启动失败。即使改完权限，残留的只读文件仍会报错。
- 先停掉所有 Hyperf 进程：kill -9 $(pgrep -f 'hyperf:server')
- 清空 runtime：rm -rf runtime/*
- 确保 runtime 目录权限正确后，再启动：php bin/hyperf.php start
容器环境特别注意点
Docker 中常见问题是挂载卷（volume）默认以 root 属主映射进容器，而容器内 Swoole 使用非 root 用户运行。
- 在 docker-compose.yml 中显式设置用户：user: "82:82"（对应 www-data UID/GID）
- 或使用 init 容器预设目录权限：RUN mkdir -p runtime storage && chown -R www-data:www-data runtime storage
- 避免将 host 的整个项目目录直接 bind mount，优先用 COPY 构建，仅挂载日志或上传目录
