file_put_contents()最适合一次性写入小文件（几MB内）且无需原子性、并发安全或自动建目录的场景；常见坑包括父目录不存在、覆盖写而非追加、并发错乱及大文件内存超限。
直接说结论：file_put_contents() 在大多数简单写文件场景下是好选择，但不是万能的，用错地方反而埋坑。
什么时候用 file_put_contents() 最合适
它本质是 fopen() + fwrite() + fclose() 的封装，适合「一次性写入完整内容」的场景，比如保存日志片段、生成配置文件、缓存 JSON 数据。
- 内容不超几 MB，且你不需要边写边校验或追加部分数据
- 不需要原子性保证（如并发写同一文件时可能被覆盖）
- 不涉及权限/上下文等复杂控制（它默认不创建父目录）
file_put_contents() 常见踩坑点
看似简单，实际出问题多在参数和路径处理上：
- 父目录不存在时会直接失败，报错
failed to open stream: No such file or directory—— 它不会自动mkdir() - 默认是覆盖写，想追加必须显式传
FILE_APPEND标志，否则上次内容全丢 - 没加
LOCK_EX时，多进程并发写同一文件可能导致内容错乱（尤其日志场景） - 写入大文件（>10MB）可能触发内存限制或超时，不如用
fopen()分块写
实用写法示例（带容错）
安全写入一个 JSON 配置文件，自动建父目录并加锁：
立即学习“PHP免费学习笔记（深入）”；
// 确保目录存在
$dir = dirname($path);
if (!is_dir($dir)) {
mkdir($dir, 0755, true);
}
// 写入并加锁，避免并发冲突
$result = file_put_contents(
$path,
json_encode($data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT),
LOCK_EX
);
if ($result === false) {
throw new RuntimeException("Failed to write file: $path");
}
注意：LOCK_EX 只对当前文件有效，且要求文件系统支持 flock（Linux/Unix 没问题，Windows 下 NFS 共享盘可能失效）。
比 file_put_contents() 更稳的替代思路
当需求变复杂，就该换方案了：
- 要确保原子写入（防止写到一半崩溃留下脏文件）→ 先写临时文件，再
rename() - 要持续追加日志且高并发 → 用
error_log()或专用日志库（如 Monolog） - 要写超大文件或流式处理 → 改用
fopen()+fwrite()+fflush() - 要控制用户权限（如 www-data 写但其他用户不可读）→ 写完后手动
chmod()
真正难的不是“怎么写进去”，而是“怎么写得可靠、可维护、不干扰别人”。file_put_contents() 是把快刀，但切硬骨头前，得先看清材质。
