file_put_contents写入失败主因是路径不存在、权限不足、磁盘满或SELinux拦截；必须用=== false检查返回值，并调用error_get_last()查具体错误。
file_put_contents 写文件失败的常见原因
直接用 file_put_contents 却没生成文件，大概率不是函数写错了，而是权限、路径或目录不存在。它不会自动创建父级目录，这点和 Python 的 open() 或 Node.js 的 fs.writeFileSync 不同。
- 目标路径含多层目录（如
"logs/2024/06/error.log"），但logs/2024根本不存在 → 写入失败，返回false - 运行 PHP 的用户（如
www-data或_www）对目标目录无写权限 → 无报错但返回false，需配合error_get_last()查看真实错误 - 路径用了相对路径（如
"data/config.json"），实际工作目录是 Web 服务器根目录或 CLI 当前路径，不一定是你预期的位置
追加内容必须加 FILE_APPEND 标志
默认行为是覆盖写入。想“追加日志”却每次都清空重写，就是因为漏了 FILE_APPEND。它不是可选参数，是必须显式传入的 flag。
- 覆盖写：
file_put_contents("log.txt", "line1\n") - 追加写：
file_put_contents("log.txt", "line2\n", FILE_APPEND) - 如果还希望自动创建目录，得自己组合
mkdir(..., 0755, true)，file_put_contents本身不支持LOCK_EX以外的其他 flag 控制目录创建
中文内容乱码或写入失败？检查编码和 flags
PHP 字符串本质是字节流，file_put_contents 不做编码转换。如果你的源字符串是 UTF-8，但文件被当成 GBK 打开，就会显示乱码；更隐蔽的问题是：Windows 下用 \n 换行，某些编辑器只认 \r\n。
- 确保字符串本身是 UTF-8（尤其从数据库或 POST 获取时，别混着 GBK）
- 需要 Windows 风格换行，手动补：
str_replace("\n", "\r\n", $content) - 想原子写入防并发覆盖，加
LOCK_EX：file_put_contents($path, $data, FILE_APPEND | LOCK_EX)，但注意这会阻塞其他进程 - 大文件慎用——它把整个内容加载进内存再一次性写入，几 MB 以上建议改用
fopen+fwrite
替代方案：什么时候不该硬用 file_put_contents
它适合小数据、简单场景。一旦涉及权限控制、大文件、流式写入、或需要精确错误分类（比如“磁盘满”和“无权限”要分别处理），就该换底层方式。
立即学习“PHP免费学习笔记（深入）”；
- 写日志且需轮转？用
error_log()或 Monolog 等库，它们内置了权限适配和缓冲 - 下载 CSV 并直接输出给浏览器？用
fopen('php://output', 'w')+fputcsv()，避免内存溢出 - 要检查磁盘空间或获取详细错误码？
fopen+fwrite+fclose能拿到资源句柄和ferror()
最常被忽略的是：file_put_contents 返回的是写入字节数（成功时）或 false（失败时），但它不抛异常，也不提示具体原因。调试时第一反应不该是“函数是不是写错了”，而是 var_dump(is_writable(dirname($path))); error_get_last();。
