最直接可控的方式是用 file_get_contents + str_replace 处理单个文件再写回，适合中小批量、替换逻辑简单的情况，关键在于读-改-写原子性及编码、并发、备份等细节处理。
用 file_get_contents + str_replace 处理单个文件再写回
这是最直接可控的方式，适合中小批量（几十个文件）、内容替换逻辑不复杂的情况。关键不是“一次扫所有文件”，而是确保每次读-改-写原子性，避免因异常中断导致文件损坏。
常见错误现象：file_put_contents 覆盖失败但没报错，结果文件变空；或编码不一致导致中文乱码替换失败。
- 务必检查
file_get_contents返回值是否为false，再执行替换 - 替换前建议用
mb_detect_encoding判断源文件编码，必要时用mb_convert_encoding统一为 UTF-8 - 写入时加上
LOCK_EX标志防止并发写冲突：file_put_contents($path, $content, LOCK_EX) - 操作前可先备份原文件：
copy($path, $path . '.bak')
用 RecursiveDirectoryIterator 批量遍历符合条件的文件
别硬写递归函数，PHP 原生迭代器更稳。重点是过滤路径和扩展名，避免误操作 vendor/、.git/ 或二进制文件（如 .png）。
使用场景：需要按后缀筛选（如只处理 .php 和 .html），或排除某些目录。
立即学习“PHP免费学习笔记（深入）”；
- 构造迭代器时传入
FilesystemIterator::SKIP_DOTS跳过.和.. - 用
pathinfo($file->getPathname(), PATHINFO_EXTENSION)判断扩展名，比substr()更可靠 - 对
$file调用isFile()和isWritable()双重校验，跳过目录或只读文件 - 避免在迭代过程中修改正在遍历的目录结构（比如边遍历边删文件）
用 preg_replace 替换含正则模式的内容，但注意 PCRE 限制
当要替换的是动态模式（如版本号 v1.2.3 → v2.0.0，或 HTML 中特定属性），str_replace 不够用，必须上正则。但容易踩坑的是修饰符和性能问题。
参数差异：str_replace 是字面量替换，preg_replace 默认区分大小写且不支持多行匹配，需手动加修饰符。
- 含换行的内容替换，必须加
s修饰符（如/pattern/s），否则.匹配不到换行符 - 批量处理大量文件时，避免在循环内重复编译正则——把
preg_replace的模式字符串提取为常量或变量，不要拼接 - 用
preg_quote($search, '/')转义用户输入的搜索字符串，防止正则注入 - 替换失败时
preg_replace返回null，不是原字符串，需显式判断
大项目慎用全目录暴力扫描，优先靠 git grep 或构建工具定位目标文件
在 Laravel、Symfony 等框架项目里，盲目遍历 ./ 可能命中缓存、日志、node_modules，轻则慢，重则崩内存。真实工程中，“批量替换”往往不需要覆盖全部文件，而是改配置、模板、路由定义等特定位置。
性能影响：10 万+ 文件的目录下，RecursiveDirectoryIterator 构建过程本身就会卡顿，file_get_contents 频繁读磁盘更是瓶颈。
- 先用命令行快速定位：
git grep -l 'old_string' -- '*.php'生成待处理文件列表 - 把结果保存为文本，PHP 脚本只读这个列表，跳过遍历开销
- CI/CD 流程中，这类操作更适合交给
sed -i（Linux/macOS）或 PowerShell（Windows）完成，PHP 不是最佳选择 - 如果必须用 PHP，考虑分块处理（如每次 50 个文件），并用
gc_collect_cycles()主动回收内存
真正麻烦的从来不是“怎么替换”，而是确认哪些文件该换、换完是否破坏引用、有没有漏掉隐藏配置项——比如 .env.example 里的占位符，或者 Dockerfile 里硬编码的路径。
