如何使用PHP批量替换文件夹内文件中的字符串

API 探路者

2026-5-27

嘿，这个需求太实用了！我平时改批量文档或者配置文件经常用类似的脚本，用PHP实现起来其实挺简单的，核心就是目录遍历+文件读写替换这两步，我给你拆解清楚，再附上可以直接用的完整代码。

核心思路

要实现批量替换，我们需要做这几件事：

指定目标文件夹、要替换的旧字符串、替换后的新字符串
遍历文件夹内的所有文件（包括子文件夹的话就用递归）
过滤文件类型，只处理文本类文件（避免损坏图片、压缩包这类二进制文件）
读取每个符合条件的文件内容，执行替换
把修改后的内容写回文件，同时跳过没有匹配内容的文件（减少不必要的IO操作）

完整代码示例

你只需要修改开头的几个配置参数就能用：

<?php
// -------------------------- 配置区 --------------------------
$targetDir = '/Users/yourname/documents/target-folder'; // 替换成你的目标文件夹绝对路径
$oldString = '需要替换的旧内容';       // 要被替换的字符串
$newString = '替换后的新内容';         // 替换后的字符串
// 只处理这些后缀的文件，避免损坏二进制文件
$allowedFileTypes = ['txt', 'php', 'html', 'md', 'json', 'csv'];
// -----------------------------------------------------------

// 递归遍历目录并替换内容的函数
function batchStringReplace($directory, $oldStr, $newStr, $allowedExts) {
    // 尝试打开目录
    $dirHandler = opendir($directory);
    if (!$dirHandler) {
        echo "❌ 无法打开目录: {$directory}（检查路径或权限）\n";
        return;
    }

    // 遍历目录中的每个条目
    while (($item = readdir($dirHandler)) !== false) {
        // 跳过当前目录(.)和上级目录(..)
        if ($item === '.' || $item === '..') {
            continue;
        }

        $fullPath = $directory . DIRECTORY_SEPARATOR . $item;

        // 如果是子目录，递归处理里面的文件
        if (is_dir($fullPath)) {
            batchStringReplace($fullPath, $oldStr, $newStr, $allowedExts);
        } else {
            // 获取文件后缀名并转为小写
            $fileExt = strtolower(pathinfo($fullPath, PATHINFO_EXTENSION));
            // 检查是否在允许的文件类型列表中
            if (in_array($fileExt, $allowedExts)) {
                // 读取文件内容
                $fileContent = file_get_contents($fullPath);
                if ($fileContent === false) {
                    echo "❌ 无法读取文件: {$fullPath}（权限不足或文件损坏）\n";
                    continue;
                }

                // 执行字符串替换
                $updatedContent = str_replace($oldStr, $newStr, $fileContent);

                // 只有内容有变化时才写入，避免无意义修改
                if ($updatedContent !== $fileContent) {
                    if (file_put_contents($fullPath, $updatedContent)) {
                        echo "✅ 成功替换: {$fullPath}\n";
                    } else {
                        echo "❌ 写入失败: {$fullPath}（检查文件写权限）\n";
                    }
                } else {
                    echo "ℹ️ 无匹配内容，跳过: {$fullPath}\n";
                }
            } else {
                echo "ℹ️ 跳过非文本文件: {$fullPath}\n";
            }
        }
    }
    closedir($dirHandler);
}

// 启动批量替换
batchStringReplace($targetDir, $oldString, $newString, $allowedFileTypes);
echo "\n🎉 批量替换任务完成！\n";
?>

关键注意事项

这些细节一定要留意，避免踩坑：

权限问题：确保PHP进程对目标文件夹有读权限，对文件有写权限，不然会出现无法读取或写入的错误
备份优先：执行脚本前一定要备份整个目标文件夹！万一替换错了内容，还能恢复（血的教训，别偷懒）
文件类型过滤：一定要设置$allowedFileTypes，绝对不要处理图片、视频、压缩包、exe这类二进制文件，否则会直接损坏文件
大小写敏感：默认的str_replace是大小写敏感的，如果需要不区分大小写的替换，把它改成str_ireplace就行
递归开关：如果不需要处理子文件夹里的文件，把函数里递归调用batchStringReplace($fullPath...)那一行删掉即可
正则替换需求：如果需要模糊匹配（比如带通配符、正则规则），把str_replace换成preg_replace，记得给正则加定界符，比如preg_replace('/旧内容的正则/', $newStr, $fileContent)
大文件处理：如果要处理几百MB的超大文件，file_get_contents可能会占太多内存，这时候可以改用逐行读取替换的方式，不过一般小文件用这个脚本完全没问题

内容的提问来源于stack exchange，提问作者Iros Romero