先确认PHP进程用户（如www-data或\_www），再检查目标目录属主、属组及wx权限是否匹配；目录须有x位才能进入，仅文件可写而目录不可写仍会失败，禁用chmod 777。
确认PHP进程用户和目标路径权限是否匹配
权限报错不是PHP语法问题，而是系统拒绝访问——www-data（Linux）或_www（macOS）这类用户没被授予对应目录的读/写/执行权。先查清谁在跑PHP：ps aux | grep -E '(php-fpm|nginx|httpd)' 或在脚本里加 echo posix_getpwuid(posix_geteuid())['name']。再用 ls -ld /path/to/dir 看目录属主、属组和权限位。常见误判是：目录权限为 755 但属主不是 PHP 用户，或目录权限是 750 却没把 PHP 用户加进对应组。
- 目录必须有
x（执行）位才能进入，所以写入前父目录至少得是755；仅文件可写而目录不可写，file_put_contents()仍会失败 - 不要用
chmod 777临时解围——它绕过最小权限原则，在启用了 SELinux/AppArmor 的服务器上甚至会被直接拦截 - macOS 上 Homebrew 安装的 php-fpm 默认可能以
_www运行，但你的项目目录属主是你自己的 macOS 用户，此时改属主比硬调权限更可靠：sudo chown -R _www:staff /path/to/storage
用 is_readable() 和 is_writable() 做预检不等于万全
is_writable() 在 NFS、某些容器卷或挂载点上会返回 false 即使实际能写，属于已知误判场景。它只检查权限位和属主/属组关系，不模拟真实 I/O。所以不能单靠它断言“安全”，尤其在部署环境。
- 对关键路径（如日志目录、上传目录），建议组合验证：
is_writable($dir) && @file_put_contents("$dir/test.tmp", "x", LOCK_EX) !== false，写完立刻unlink() -
is_readable()同样有局限——它不检查 open_basedir 限制或 SELinux 上下文，若返回true却仍读失败，就得查error_get_last()的具体错误信息 - 别在循环里反复调用这些函数，它们有 stat 开销；一次检查、缓存结果更稳妥
写入失败时捕获 Permission denied 而非依赖 try/catch
file_put_contents() 和 fopen() 权限失败触发的是 E_WARNING，不是异常，try/catch 捕不到。必须靠返回值 + error_get_last() 提取原始错误字符串来识别。
- 正确做法：
if (file_put_contents($path, $data) === false) { $err = error_get_last(); if ($err && str_contains($err['message'], 'Permission denied')) { /* 处理权限问题 */ } } - 注意：
error_get_last()是全局状态，多线程/并发请求下可能被覆盖，应在失败后立即调用 - 避免用
@抑制警告——它让错误静默消失，调试时极难定位，且影响 opcache 编译优化
容器与跨平台部署时权限容易被忽略的点
Docker 镜像里 PHP 进程用户常是 www-data，但宿主机挂载的卷默认属主是 root，导致容器内无权写入。这问题在本地开发（Mac/Linux）和 CI 环境中高频出现，却常被归因为“代码问题”。
立即学习“PHP免费学习笔记（深入）”；
- 启动容器时显式指定用户：
docker run -u www-data ...，并确保挂载路径在宿主机上已chown www-data:www-data - Alpine 镜像默认不含
acl工具，若要用setfacl授权，需提前apk add acl - Laravel 的
storage/和bootstrap/cache/目录在 Git 中通常不存文件，但权限必须由部署脚本初始化，不能靠首次访问自动创建——因为创建动作本身就会因权限不足失败
