file_put_contents写入失败可能静默返回false，需检查返回值是否为false或等于strlen($data)；追加必须用FILE_APPEND；推荐原子性写入（临时文件+rename）；注意编码、换行符、路径安全及权限校验。
file_put_contents写入失败但没报错？检查第三个参数
默认情况下 file_put_contents 会覆盖整个文件，如果你本意是追加内容却忘了传 FILE_APPEND 标志，旧数据就彻底丢了。更隐蔽的问题是：当目标文件被其他进程锁定（比如 Windows 下用记事本打开着），file_put_contents 可能静默失败——返回 false 但不抛异常，且 error_get_last() 也不一定有内容。
- 务必检查函数返回值：
if (file_put_contents($path, $data) === false) { /* 处理失败 */ } - 追加写入必须显式传
FILE_APPEND，不能只靠fopen('a')的直觉 - 在 Windows 上，如果文件正被占用，部分 PHP 版本会返回 0 字节写入数而非
false，建议同时检查返回值是否等于strlen($data)
原子性写入：避免中间状态损坏文件
直接覆盖写入存在风险：写到一半进程崩溃或磁盘满，原文件已被清空，新内容又没写完，结果得到一个空文件或截断文件。生产环境强烈建议用临时文件 + 原子重命名方案。
- 先写入临时文件：
$tmp = $path . '.tmp'; file_put_contents($tmp, $data); - 再用
rename($tmp, $path)替换——该操作在绝大多数文件系统上是原子的 - 注意
rename()跨分区会失败，此时需 fallback 到copy()+unlink()，但失去原子性保障 - 临时文件路径最好和目标同目录，避免跨设备问题
编码与换行符：文本文件写入前必须确认
file_put_contents 不做任何编码转换，它只是把字节原样写入。如果你传的是 UTF-8 字符串但文件原本是 GBK，或者 PHP 源码保存为 UTF-8 BOM 而你没意识到，写进去的内容就会乱码或开头多出 \xEF\xBB\xBF。
- 写入前用
mb_detect_encoding($data, ['UTF-8', 'GBK'], true)确认源编码，必要时用mb_convert_encoding()统一转为 UTF-8 - Windows 程序读取文本常依赖 CRLF 换行，而 PHP 默认用 LF；若目标是给 Excel 或记事本用，需手动替换：
str_replace("\n", "\r\n", $data) - 避免在字符串末尾意外添加空白——
file_put_contents会照单全收，可能破坏 JSON 或配置文件格式
权限与路径安全：别让写入变成漏洞入口
如果 $path 来自用户输入（比如 URL 参数或表单字段），直接拼接进 file_put_contents 就是典型的路径遍历漏洞。即使加了 realpath()，也得防住符号链接绕过。
- 绝对禁止拼接用户输入：
file_put_contents($_GET['file'], $data)是危险示范 - 限定可写目录范围，例如预设白名单：
$allowed_dir = '/var/www/config/'; $full_path = realpath($allowed_dir . basename($_GET['file'])); - 写入前检查父目录是否存在且可写：
is_writable(dirname($full_path))，否则file_put_contents可能创建失败但不提示具体原因 - 敏感目录（如
../、/etc/）应硬编码拦截，不依赖过滤逻辑
实际项目里最常被忽略的是原子性保障和编码一致性——前者导致配置丢失难排查，后者让中文显示异常却查不出源头。写入前多一步验证，远比事后恢复省事。
