RewriteMap不能在.htaccess中使用，必须配置于服务器级（httpd.conf或VirtualHost），依赖mod_so和完整mod_rewrite；需通过httpd -M、phpinfo()及测试命令确认支持，再创建txt映射文件并配合RewriteCond与RewriteRule实现301跳转或内部重写。
Apache 的 RewriteMap 是处理大规模 URL 映射的高效方式，尤其适合旧站迁移、多级目录归并或 SEO 链接保全等场景。但要注意：它**不能在 .htaccess 中使用**，必须配置在服务器级（httpd.conf 或虚拟主机配置段），且依赖 mod_so 和完整版 mod_rewrite —— 很多轻量环境（如 phpEnv）默认不支持，需先确认可用性。
确认 RewriteMap 支持是否就绪
执行以下检查，缺一不可：
- 运行
httpd -M | grep rewrite，确保输出含rewrite_module (shared) - 运行
httpd -M | grep so，确认so_module (shared)已加载（RewriteMap 依赖动态模块加载） - 访问
phpinfo()页面，查看 “Loaded Modules” 列表中是否有mod_so和完整mod_rewrite（含txt:类型） - 在
httpd.conf中临时添加一行RewriteMap test int:tolower，重启 Apache；若报错Invalid command 'RewriteMap'，说明底层不支持，需换方案
创建并配置 txt 映射文件
映射文件是纯文本，每行一个键值对，用空格分隔，支持注释（以 # 开头）：
例如，新建文件 /usr/local/apache/conf/redirect-map.txt：
Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。
/old/about-us.html /about
/old/blog/2023/05/post.html /articles/2023/05/post
# 保留跳转但不暴露内部路径
/legacy/download.zip /assets/files/latest.zip
注意：
• 路径以 / 开头，匹配的是请求 URI（不含域名和查询参数）
• 键必须完全匹配（不支持通配符），区分大小写（除非配合 int:tolower）
• 文件保存为 UTF-8 无 BOM 格式，Apache 启动时会自动缓存内容，修改后需 reload 或 restart 生效
在虚拟主机中启用 RewriteMap 并编写规则
将以下配置放入 <VirtualHost> 块内（不能放 .htaccess）：
RewriteMap redirectmap txt:/usr/local/apache/conf/redirect-map.txt
RewriteCond ${redirectmap:$1} !=""
RewriteRule ^(/.*)$ ${redirectmap:$1} [R=301,L]
说明：
• ${redirectmap:$1} 中的 $1 来自 ^(/.*)$ 捕获的完整路径（含开头 /）
• RewriteCond 确保只对映射表中存在键的请求生效，避免空值导致 500 错误
• [R=301,L] 表示永久重定向并终止后续规则；如需内部重写，改用 [L] 即可
• 若希望忽略大小写，可叠加 int:tolower：
RewriteMap lcmap int:tolower<br>RewriteMap redirectmap txt:/path/to/map.txt<br>RewriteCond ${redirectmap:${lcmap:$1}} !=""<br>RewriteRule ^(/.*)$ ${redirectmap:${lcmap:$1}} [R=301,L]
调试与常见问题处理
开启 Rewrite 日志便于排查（仅用于开发环境，勿在生产启用）：
- 在
httpd.conf全局添加：RewriteLog "/usr/local/apache/logs/rewrite.log"（Apache 2.2）或使用RewriteLogLevel；Apache 2.4+ 改用RewriteOptions Inherit+ErrorLog级别调试 - 日志中重点看 “applying pattern... to ...”、“map lookup OK/NOTFOUND” 等线索
- 常见失败原因：
– 映射文件路径权限不足（Apache 进程需有读取权限）
– 文件编码错误（Windows 编辑器保存为 ANSI 可能乱码）
– 键中包含未转义的特殊字符（如空格、括号），应 URL 编码或避免使用）
– 规则位置错误（RewriteMap 必须在 VirtualHost 内定义，不能跨作用域引用）
