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

Simple Introduction to the map Directive

The map directive belongs to the ngx_http_map_module module and allows you to create a new variable based on the value of an existing one.

Syntax

map string $variable { ... }

Only usable inside the http block.

Basic Example

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 numeric $name variable. The hostnames parameter enables prefix or suffix wildcard matching and must appear first in the list. If no pattern matches, the default value (0) is used.

Practical Uses

1. Cookie‑Based Multi‑Environment Routing

Instead of maintaining multiple domain names for different test environments, a single domain can be used and the target backend selected via a cookie.

map $cookie_cl_env_num $cl_backend_map {
    default   1.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 routes requests to different backends according to the value of the cl_env_num cookie.

2. Secure Multi‑Domain CORS Configuration

When a service must restrict cross‑origin requests to a known set of domains, the map directive can generate the appropriate Access‑Control‑Allow‑Origin header.

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;
        # ... other config ...
    }
}

This snippet only permits the listed origins and denies all others.

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.