str_replace()是PHP中高性能、无正则的字符串批量替换函数，适用于配置模板占位符替换；支持单/多值替换、次数统计、关联数组驱动映射，并需注意大小写、空值、编码等避坑点。
str_replace() 是 PHP 中最常用、最直接的字符串批量替换函数，特别适合处理配置模板这类“占位符替换”场景。它不依赖正则，性能高，语法简单，只要明确知道要找什么、换成什么，就能快速完成任务。
基础用法：一次替换所有匹配项
str_replace() 支持单个或多个搜索项与替换项，自动遍历并全部替换：
- 单值替换：str_replace('{host}', '192.168.1.100', $template)
- 多值同步替换：str_replace(['{host}', '{port}', '{dbname}'], ['db.example.com', '3306', 'app_prod'], $template)
- 替换并统计次数（第三个参数为引用）：$count = 0; str_replace('{env}', 'prod', $template, $count); // $count 得到实际替换次数
处理配置模板：安全替换 + 防止误伤
模板中常有类似 {DB_HOST}、{{APP_NAME}} 这类占位符。为避免替换时污染真实内容（比如把 user_db_host 里的 _host 错替），建议：
- 统一使用边界清晰的占位符格式，如大写+下划线+花括号：{DB_HOST}、{CACHE_TTL}
- 替换前对键名做预处理，确保大小写一致（模板和数据都转大写或都小写）：$keys = array_map('strtoupper', array_keys($config));
- 若需严格匹配完整单词（防子串误替），可改用 preg_replace() 配合 word boundary（\b{DB_HOST}\b），但 str_replace() 在绝大多数配置场景已足够且更快
批量替换进阶：关联数组驱动 + 自动映射
当配置项较多时，用关联数组管理更清晰。可用 array_keys() 和 array_values() 拆解后传入 str_replace：
立即学习“PHP免费学习笔记（深入）”；
- $config = ['DB_HOST' => 'localhost', 'DB_PORT' => '5432', 'APP_ENV' => 'staging'];
- $template = file_get_contents('config.tpl.php');
- $replaced = str_replace(array_map(fn($k) => "{${k}}", array_keys($config)), array_values($config), $template);
也可封装成小函数提升复用性：
$renderTemplate = function(string $tpl, array $data): string {
$search = array_map(fn($k) => "{${k}}", array_keys($data));
return str_replace($search, array_values($data), $tpl);
};
注意事项与避坑提醒
str_replace() 看似简单，但在配置模板中容易踩几个隐性坑：
- 区分大小写：{db_host} ≠ {DB_HOST}，建议统一约定命名规范
- 不支持嵌套/条件逻辑：它只是纯文本替换，无法处理 {% if ENV == 'dev' %}...{% endif %} 这类模板语法，复杂需求请用 Twig/Blade
- 空值处理：若某配置项为 null 或空字符串，会被替换成空，可能导致语法错误（如 host = ），建议提前校验或设默认值
- 编码问题：确保模板文件与 PHP 脚本编码一致（推荐 UTF-8 without BOM），否则花括号或中文占位符可能乱码导致匹配失败
