QSA标志明确指示Apache将原始URL查询参数追加到重写目标后而非覆盖。其原理是默认不匹配query string，启用QSA才将原始参数以&形式拼接；常见于路径映射和重定向叠加参数场景，需注意substitution中必须含?、多规则需各自声明QSA、编码自动保留等细节。
QSA（Query String Append）标志是 Apache mod_rewrite 中专门用来处理查询参数的关键机制。它不是“自动保留”，而是明确告诉服务器：把原始 URL 中的 query string 追加到新生成的 substitution 地址后面，而不是覆盖或丢弃。
QSA 的作用原理
Apache 的 RewriteRule 默认只匹配 URI path（比如 /search/abc），不包含问号后的 query string（如 ?q=abc&page=2）。即使你在 substitution 中写了新参数，原始参数也不会自动出现——除非显式启用 QSA。
- 没有 QSA：
RewriteRule ^search/(.*)$ /search.php?term=$1 [R,L]→ 原始请求/search/test?page=3会变成/search.php?term=test（page=3彻底丢失） - 启用 QSA：
RewriteRule ^search/(.*)$ /search.php?term=$1 [QSA,R,L]→ 同样请求变成/search.php?term=test&page=3
常见使用场景与写法
QSA 最常用于两类操作：带参数的路径重写、以及在重定向中叠加固定参数的同时保留动态参数。
Apache Superset Dashboard and SQL Exploration Skill
下载
Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。
- 将短路径映射为带参脚本，并保留额外参数：
RewriteRule ^/p/([0-9]+)$ /view.php?id=$1 [QSA,L]
访问/p/123?ref=home&utm=2026→ 内部调用/view.php?id=123&ref=home&utm=2026 - 跳转时添加固定参数，又不丢用户原参数：
RewriteRule ^/$ /home.php?source=direct [QSA,R=302,L]
请求/?lang=zh&debug=1→ 跳转到/home.php?source=direct&lang=zh&debug=1 - 配合 RewriteCond 判断 query string 后再重写（QSA 仍生效）：
RewriteCond %{QUERY_STRING} ^id=(\d+)RewriteRule ^/item$ /product.php?pid=%1 [QSA,L]
容易踩的坑
QSA 看似简单，但配置错误会导致参数静默丢失，且不易察觉。
-
QSA 必须和 substitution 中的 ? 同时存在：如果 substitution 没有问号（比如
/search.php），QSA 无意义；如果 substitution 已含问号（如/search.php?mode=full），QSA 才会把原始参数以 & 形式接在后面 - 不要混淆 R 和内部重写：QSA 对内部重写（无 R）和外部重定向（带 R）都有效，但只有带 R 时你才能在浏览器地址栏看到拼接后的完整 URL
- 多个规则叠加时，QSA 只作用于当前规则的 substitution：后续规则不会“继承”前一条的 QSA 行为，每条需要保留参数的规则都得单独加 [QSA]
- 注意编码问题：原始 query string 中的特殊字符（如空格、中文）已被 URL 编码，QSA 会原样追加，无需手动 encode 或 decode
验证是否生效的小技巧
临时加一条测试规则，把 query string 显式输出到响应头，方便调试：
RewriteCond %{QUERY_STRING} .+RewriteRule ^test$ - [E=QS:%{QUERY_STRING},L]- 再在 PHP 中用
header("X-Debug-QS: " . $_SERVER['HTTP_X_DEBUG_QS'] ?? '');查看原始值（需配合 SetEnvIf 或 Header 模块）
更直接的方式是开启 rewrite 日志（Apache 2.4+ 使用 LogLevel alert rewrite:trace3），观察日志中 “appending query string” 是否出现。
