PHP mkdir 创建目录失败原因及解决方法

PHP中mkdir()创建目录失败的常见原因并非路径错误，而是默认不递归创建父目录且对父目录写权限校验不足——必须显式传入第三个参数true启用递归，并确保最靠近目标的已存在父目录对PHP运行用户（如www-data）具有写权限；同时需警惕八进制权限写法（0755而非755）、umask对实际权限的掩盖、中文路径编码不一致导致is_dir()误判，以及Docker环境中未通过chown固化目录所有权等隐性陷阱，真正的问题往往藏在权限验证缺失和部署配置疏漏之中。

mkdir() 报 “No such file or directory” 错误

这不是路径写错了，而是 mkdir() 默认不创建父目录。比如你要建 'logs/2024/06/15'，但 'logs' 本身不存在，它就直接报错退出，连 'logs' 都不会尝试建。

必须显式传入第三个参数 true 才启用递归创建：

mkdir('logs/2024/06/15', 0755, true);

注意两点：

• 0755 是八进制，不能写成 755（PHP 会当十进制处理，权限完全不对）
• 即使加了 true，只要中间某层父目录（如 'logs/2024'）的父目录不可写，创建仍会在那层卡住

明明加了 recursive=true，还是 Permission denied

错误不是出在 mkdir() 的 $mode 参数上，而是 PHP 进程用户（如 www-data、nginx 或 Windows 下的 IUSR）对**最靠近目标的已存在父目录**没有写权限。

例如路径是 /var/www/html/uploads/images，而 /var/www/html/uploads 已存在但属主是 root、权限是 755，那么 www-data 就无法在它下面创建 images。

验证方式：

• Linux：运行 ls -ld /var/www/html/uploads，确认输出里有 www-data 或包含 w 权限的组
• Windows：检查该文件夹“属性 → 安全”，确认 PHP 运行用户有“创建文件/文件夹”权限（不是只读）
• Docker 环境：必须在 Dockerfile 中用 chown -R www-data:www-data /var/www 固化所有权，不能靠运行时 chmod 777

is_dir() 返回 false，但目录其实存在

这往往不是 mkdir() 的问题，而是权限导致的误判：is_dir() 对一个**存在但当前用户无读/执行权限的目录**也会返回 false —— 它连进去看一眼的资格都没有。

所以别单靠 is_dir() 判断是否要建目录。更稳妥的组合是：

if (!is_dir($path) && !is_writable(dirname($path))) {
    throw new RuntimeException("父目录不可写：".dirname($path));
}
if (!is_dir($path)) {
    mkdir($path, 0755, true) or die("mkdir failed: $path");
}

关键点：

• dirname($path) 拿到父目录，用 is_writable() 直接测写权限，比猜更可靠
• mkdir() 返回 false 时，立刻处理失败，别只靠日志等事后排查
• 中文路径要确保脚本编码（UTF-8）和系统 locale 一致，否则 is_dir() 可能静默失效

umask 导致实际权限和预期不符

你写了 0777，但新建目录实际是 0755，大概率是系统 umask 在起作用。PHP 的 mkdir() 权限参数是“最大允许权限”，会被 umask 掩掉一部分。

临时绕过方法（仅限关键路径）：

$old = umask(0);
mkdir($path, 0777, true);
umask($old);

但要注意：

• 并发场景下改 umask 不安全，可能影响其他线程
• 更推荐的做法是明确设为所需权限（如 0755），再配合 Web 服务器用户权限模型来保障可访问性
• Windows 下 $mode 参数基本被忽略，权限由 ACL 控制，此时重点查用户权限而非掩码

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《PHP mkdir 创建目录失败原因及解决方法》文章吧，也可关注golang学习网公众号了解相关技术文章。