Mastering Nginx map Directive: Dynamic Variable Mapping and Real-World Use Cases

Simple Introduction to map Directive

The map directive belongs to the ngx_http_map_module and allows you to create a new variable based on the value of another variable. syntax: map string $variable { ... } Official documentation provides examples to illustrate its usage.

map $http_host $name {
    hostnames;
    default 0;
    example.com 1;
    *.example.com 1;
    example.org 2;
    *.example.org 2;
    .example.net 3;
    wap.* 4;
}

This example maps incoming $http_host values to a new variable $name, using hostnames to enable wildcard matching and default for unmatched hosts.

Practical Uses of map Directive

1. Environment routing based on cookie

Large projects often need to switch between multiple test environments without managing many domain names. By mapping a cookie value to an upstream name, traffic can be directed to the appropriate environment.

map $cookie_cl_env_num $cl_backend_map {
    default 1.1.1:80;
    dev-01 upstream_dev-01;
    dev-02 upstream_dev-02;
    dev-03 upstream_dev-03;
    test-01 upstream_test-01;
    test-02 upstream_test-02;
    test-03 upstream_test-03;
    test-04 upstream_test-04;
    test-05 upstream_test-05;
    test-06 upstream_test-06;
    test-07 upstream_test-07;
    test-08 upstream_test-08;
    test-09 upstream_test-09;
    test-10 upstream_test-10;
    test-11 upstream_test-11;
    test-12 upstream_test-12;
    test-13 upstream_test-13;
    test-14 upstream_test-14;
    test-15 upstream_test-15;
}

upstream upstream_test-14 {
    server 2.2.2.2:80;
}

location / {
    proxy_pass http://$cl_backend_map;
}

# Example request
# curl --cookie "cl_env_num=test-15" a.test.com/api/v1/hahaha

This configuration demonstrates how a single domain can serve different back‑ends simply by changing the cookie value.

2. Secure multi‑domain CORS handling

Instead of allowing all origins with *, you can whitelist specific domains using map, which is useful for services with strict security requirements.

map $http_origin $allow_origin {
    ~http://www.baidu.com http://www.baidu.com;
    ~http://m.baidu.com http://m.baidu.com;
    ~http://a.baidu.com http://a.baidu.com;
    default deny;
}

server {
    listen 80;
    server_name www.baidu.com;
    location / {
        # other config ...
        add_header Access-Control-Allow-Origin $allow_origin;
    }
}

The variable $allow_origin is set to the matching origin or deny if none match, and the header is added accordingly.

Conclusion

The map directive is versatile and can be applied to many scenarios beyond the examples shown; understanding its syntax and capabilities enables flexible, maintainable Nginx configurations.