Nginx 的 map 指令可在 http 块中基于请求参数、路径、Header、IP 或正则提取值，生成变量供 ThinkPHP 通过 $_SERVER 或响应头读取，实现路由分发、模块映射、调试控制、缓存策略及 API 版本管理。
如果您在 ThinkPHP 项目中使用 Nginx 作为 Web 服务器，希望基于请求特征（如 URL 参数、路径前缀、Header 等）动态映射出可用于路由分发、缓存策略或日志标记的变量，则需借助 Nginx 的 map 指令实现变量预计算。该指令必须定义在 http 块内，不能直接写在 server 或 location 中，且其生成的变量可被 ThinkPHP 的入口逻辑间接感知（例如通过重写 URI、注入 Header 或控制 proxy_pass）。以下是多种可行的配置方法：
一、通过 map 映射请求参数为后端路由标识
此方法适用于 ThinkPHP 多应用或多模块场景，利用 query string 中的参数（如 app、module）动态生成 $tp_route 变量，供后续 rewrite 或 fastcgi_param 使用。map 在请求解析早期即完成变量赋值，确保稳定性。
1、在 nginx.conf 的 http 块中添加如下 map 块：
map $arg_app $tp_route {
default "index";
"admin" "admin";
"api" "api";
"mobile" "mobile";
}
立即学习“PHP免费学习笔记（深入）”；
2、在对应的 server 块中，将 $tp_route 注入 FastCGI 环境变量：
fastcgi_param PHP_APP_ROUTE $tp_route;
3、在 ThinkPHP 入口文件（如 public/index.php）中，通过 $_SERVER['PHP_APP_ROUTE'] 获取该值，并用于初始化应用上下文。
二、根据请求路径前缀映射 ThinkPHP 模块名并重写 URI
此方法避免在 URL 中暴露 index.php 或模块名，通过 map 提前识别路径语义，生成标准化模块标识，再结合 rewrite 统一转发至 ThinkPHP 入口。所有匹配基于字符串前缀，不依赖正则引擎，性能更高。
1、在 http 块中定义路径到模块的映射：
map $uri $tp_module {
default "index";
"/admin/" "admin";
"/api/v1/" "api";
"/mobile/" "mobile";
}
2、在 server 块中启用重写逻辑：
if ($tp_module != "index") {
rewrite ^/(.*)$ /index.php?s=/$1 last;
}
3、在 ThinkPHP 配置中启用 pathinfo 模式，并确保 route_check 开启，使框架能正确解析 $tp_module 对应的路由规则。
三、基于 HTTP 头部映射调试模式开关并注入环境变量
此方法用于灰度环境中快速切换 ThinkPHP 的调试级别，无需修改代码或部署配置。通过检查自定义 Header（如 X-TP-Debug），用 map 生成布尔型变量，再由 fastcgi_param 控制 APP_DEBUG 值。
1、在 http 块中定义头部映射：
map $http_x_tp_debug $tp_debug_flag {
default "0";
"1" "1";
"true" "1";
"on" "1";
}
2、在 server 块中传递该标志：
fastcgi_param APP_DEBUG $tp_debug_flag;
3、确认 ThinkPHP 的 env.php 或 .env 文件未硬编码 APP_DEBUG，使其以 $_SERVER['APP_DEBUG'] 为准进行运行时判定。
四、按客户端 IP 段映射缓存策略变量供 ThinkPHP 动态响应
此方法支持对内网用户关闭缓存、对外网用户启用页面级缓存。map 将 $remote_addr 映射为 $tp_cache_level，再由 Nginx 的 expires 或 add_header 指令配合生效，ThinkPHP 可通过读取响应头获知缓存等级。
1、在 http 块中定义 IP 段映射（注意需先设置 map_hash_max_size）：
map $remote_addr $tp_cache_level {
default "public";
"127.0.0.1" "no-cache";
"192.168.0.0/16" "no-cache";
"10.0.0.0/8" "no-cache";
}
2、在 location ~ \.php$ 块中设置响应头：
add_header X-TP-Cache-Level $tp_cache_level always;
3、在 ThinkPHP 的中间件中读取 $_SERVER['HTTP_X_TP_CACHE_LEVEL']，据此调用 Cache::tag() 或 Response::header() 进行差异化处理。
五、利用正则捕获 URI 中版本号并映射为 ThinkPHP 路由参数
此方法适用于 ThinkPHP API 版本化管理，例如 /v2/user/info → 自动提取 v2 并映射为 $tp_api_version，供路由分发或中间件校验。map 支持大小写不敏感正则及捕获组引用，适合结构化路径解析。
1、在 http 块中定义带捕获的正则映射：
map $uri $tp_api_version {
default "";
~*^/v(?
}
2、在 server 块中将版本号附加到查询参数：
if ($tp_api_version) {
set $args "$args&version=$tp_api_version";
}
3、在 ThinkPHP 的路由定义中，使用 Route::get('user/info', 'v2.user/info') 并在控制器中接收 input('version') 进行兼容性判断。
