301 or Internal Rewrite for Wallpaper Resolution Routing? Inside One Host, I Chose the Route That Doesn't Change the URL

The internal rewrite version

Keep the caller's URL as it is, and swap the file inside the server. No if; the map holds the answer.

# D: route with map only (the URL does not change)
map $arg_w $dir { default "/img"; "640" "/img/w640"; "1280" "/img/w1280"; }
 
location ~ ^/d/img/ {
  rewrite ^/d/img/(.+)$ $dir/$1 last;
}
 
location /img/ {
  add_header X-Served-From $uri always;   # for checking; remove it in production
}

default "/img" is the heart of this design. An unexpected value like w=999, or no w at all, falls through to the original image. No 404, no 301.

My results:

$ ./verify.sh http://127.0.0.1:8081/d/img/sunset.jpg
w        code  redirects  bytes
640      200   0          2000
1280     200   0          8000
999      200   0          30000
none     200   0          30000

One round trip, zero redirects, and the byte counts match what I expected. The X-Served-From header shows /img/w640/sunset.jpg. The URL the caller sees never changed, while the file behind it did.

Side by side

Same conditions, viewed by aspect.

The last row is why I chose the rewrite. Resolution routing is not a move; it is a storage detail. There is nothing to tell the caller, and if there is nothing to tell, I never create the extra round trip or the "remembered answer" worry in the first place.

The opposite cases belong to the 301: moving from an old domain to a new one, or telling search engines which URL is the official one. The line is not which is better. It is whether the routing is a move, or a storage detail.

The order trap: first match wins

One more thing I only understood after running it is the order of regex location blocks. nginx reads regex locations in the order written and uses the first match. Put a broad rule first and the narrower one below it never fires.

# broad first -> /e/img/w640/sunset.jpg still returns "broad"
location ~ ^/e/img/.+\.jpg$          { return 200 "broad\n"; }
location ~ ^/e/img/w640/.+\.jpg$     { return 200 "narrow\n"; }

I ran the same two lines in both orders on separate ports.

narrow-first: narrow
broad-first:  broad

nginx -t reports "syntax is ok" for both. A valid syntax and a rule that actually matches are different things. When you add a rule, put the narrower one above. I wrote that line at the top of my own checklist.

Two traps I hit during the test

Both happened while I was running this.

The first: rewrite overwrites named captures. I first captured f in location ~ ^/d/img/(?<f>.+)$ and wrote rewrite ^ $dir/$f last;. Every call returned 404. The rewrite has its own regex that matches anew, so the $f from the location was no longer usable. The fix is to capture again inside the rewrite.

# NG: the rewrite's own regex (^) overwrites $f and the path comes out empty
location ~ ^/d/img/(?<f>.+)$ { rewrite ^ $dir/$f last; }
 
# OK: capture again inside the rewrite
location ~ ^/d/img/ { rewrite ^/d/img/(.+)$ $dir/$1 last; }

The second: the previous nginx was still running. After editing the config I ran nginx -s stop, but I had started it with a different config file, so it never stopped. The new process could not bind the same port, and the old config kept answering. The error log said bind() ... failed (98: Address already in use), and that is when I noticed. If behavior does not change after you change the config, check which process is running with which config file before you suspect the rule.

A verification script

Here is a script that checks the table above mechanically. It does not follow redirects, so a 301 stands out immediately.

#!/usr/bin/env bash
# usage: ./verify.sh http://127.0.0.1:8081/d/img/sunset.jpg
URL="$1"
printf '%-8s %-5s %-10s %-8s\n' w code redirects bytes
for w in 640 1280 999 ""; do
  curl -s -o /dev/null -w "%{http_code} %{num_redirects} %{size_download}" "${URL}?w=${w}" \
    | { read -r code redirects bytes; printf '%-8s %-5s %-10s %-8s\n' "${w:-none}" "$code" "$redirects" "$bytes"; }
done

Pointed at the 301 version (A), all four rows come back as 301 with 178 bytes. Against the rewrite version (D), you get the 200s and file sizes shown earlier. If you keep the same rule in several places (multiple servers, or separate storage backends), run the script once per place. When you fix one, make the same fix in every copy of the rule. Writing that into the procedure avoids the quiet mismatch where only one side is stale.

The order I check things in

Before writing any routing rule, I check three things in this order.

1. Is the URL an "address" the caller should remember? If it moved for good, use a 301; if it is a storage detail, rewrite internally.
2. Does the target live on the same host? If you are sending callers to another host, a redirect is your only option.
3. Where do unexpected inputs land? A 404, or the original image? For wallpaper delivery, where "something showing" beats "nothing showing," I recommend writing the original as the default.

Count the round trips

A list screen with 40 thumbnails makes 80 requests with the 301 version and 40 with the internal rewrite: a 50% reduction. Fewer trips from the device also shortens the wait before images fill in as you scroll. This is an arithmetic estimate, not a measured time on a real device.

What to settle before production

When you fix a rule in production, prepare the way back first. Keep the previous config file with a date, and write the restore command into the procedure. An internal rewrite takes effect immediately, which means a mistake takes effect immediately too.

Before you publish

• An unexpected w value, and a call with no w, both return the original with a 200
• Rules are ordered narrow-first (nginx -t cannot tell you this)
• Any capture you need is taken again inside the rewrite
• The running process was restarted with the new config
• Every location that holds the same rule got the same fix

For other pitfalls around image delivery, I have also written about why an expo-image disk cache grows so large and about prefetching and scroll performance. Server-side routing and app-side caching sit at opposite ends of the same image, so I hope reading them together helps.